任务提交执行 Rest API 文档

任务提交执行 Rest API 文档

Linkis Restful接口的返回，都遵循以下的标准返回格式：

{
  "method": "",
  "status": 0,
  "message": "",
  "data": {}
}

约定：

method：返回请求的Restful API URI，主要是 WebSocket 模式需要使用。
status：返回状态信息，其中：-1表示没有登录，0表示成功，1表示错误，2表示验证失败，3表示没该接口的访问权限。
data：返回具体的数据。
message：返回请求的提示信息。如果status非0时，message返回的是错误信息，其中data有可能存在stack字段，返回具体的堆栈信息。

更多关于 Linkis Restful 接口的规范，请参考：Linkis Restful 接口规范

1. 提交执行

接口 /api/rest_j/v1/entrance/submit
提交方式 POST

{
  "executionContent": {
    "code": "show tables",
    "runType": "sql"
  },
  "params": {
    "variable": {// task variable 
      "testvar": "hello"
    },
    "configuration": {
      "runtime": {// task runtime params 
        "jdbc.url": "XX"
      },
      "startup": { // ec start up params 
        "spark.executor.cores": "4"
      }
    }
  },
  "source": { //task source information
    "scriptPath": "file:///tmp/hadoop/test.sql"
  },
  "labels": {
    "engineType": "spark-2.4.3",
    "userCreator": "hadoop-IDE"
  }
}

返回示例

{
 "method": "/api/rest_j/v1/entrance/submit",
 "status": 0,
 "message": "请求执行成功",
 "data": {
   "execID": "030418IDEhivebdpdwc010004:10087IDE_hadoop_21",
   "taskID": "123"  
 }
}

execID是用户任务提交到 Linkis 之后，为该任务生成的唯一标识执行ID，为 String 类型，这个ID只在任务运行时有用，类似PID的概念。ExecID 的设计为(requestApplicationName长度)(executeAppName长度)(Instance长度)${requestApplicationName}${executeApplicationName}${entranceInstance信息ip+port}${requestApplicationName}_${umUser}_${index}
taskID 是表示用户提交task的唯一ID，这个ID由数据库自增生成，为 Long 类型

2. 获取状态

接口 /api/rest_j/v1/entrance/${execID}/status
提交方式 GET
返回示例

{
 "method": "/api/rest_j/v1/entrance/{execID}/status",
 "status": 0,
 "message": "获取状态成功",
 "data": {
   "execID": "${execID}",
   "status": "Running"
 }
}

3. 获取日志

接口 /api/rest_j/v1/entrance/${execID}/log?fromLine=${fromLine}&size=${size}
提交方式 GET
请求参数fromLine是指从第几行开始获取，size是指该次请求获取几行日志
返回示例，其中返回的fromLine需要作为下次请求该接口的参数

{
  "method": "/api/rest_j/v1/entrance/${execID}/log",
  "status": 0,
  "message": "返回日志信息",
  "data": {
    "execID": "${execID}",
    "log": ["error日志","warn日志","info日志", "all日志"],
    "fromLine": 56
  }
}

4. 获取进度

接口 /api/rest_j/v1/entrance/${execID}/progress
提交方式 GET
返回示例

{
  "method": "/api/rest_j/v1/entrance/{execID}/progress",
  "status": 0,
  "message": "返回进度信息",
  "data": {
    "execID": "${execID}",
    "progress": 0.2,
    "progressInfo": [
        {
            "id": "job-1",
            "succeedTasks": 2,
            "failedTasks": 0,
            "runningTasks": 5,
            "totalTasks": 10
        },
        {
            "id": "job-2",
            "succeedTasks": 5,
            "failedTasks": 0,
            "runningTasks": 5,
            "totalTasks": 10
        }
    ]
  }
}

5. kill任务

接口 /api/rest_j/v1/entrance/${execID}/kill
提交方式 GET
返回示例

{
 "method": "/api/rest_j/v1/entrance/{execID}/kill",
 "status": 0,
 "message": "OK",
 "data": {
   "execID":"${execID}"
  }
}

6. 获取任务信息

接口 /api/rest_j/v1/jobhistory/{id}/get
提交方式 GET
请求参数

参数名称	参数说明	请求类型	是否必须	数据类型	schema
id	id	path	true	string

返回示例

{
  "method": null,
  "status": 0,
  "message": "OK",
  "data": {
    "task": {
      "taskID": 1,
      "instance": "xxx",
      "execId": "exec-id-xxx",
      "umUser": "test",
      "engineInstance": "xxx",
      "progress": "10%",
      "logPath": "hdfs://xxx/xxx/xxx",
      "resultLocation": "hdfs://xxx/xxx/xxx",
      "status": "FAILED",
      "createdTime": "2019-01-01 00:00:00",
      "updatedTime": "2019-01-01 01:00:00",
      "engineType": "spark",
      "errorCode": 100,
      "errDesc": "Task Failed with error code 100",
      "executeApplicationName": "hello world",
      "requestApplicationName": "hello world",
      "runType": "xxx",
      "paramJson": "{\"xxx\":\"xxx\"}",
      "costTime": 10000,
      "strongerExecId": "execId-xxx",
      "sourceJson": "{\"xxx\":\"xxx\"}"
    }
  }
}

7. 获取结果集信息

支持多结果集信息

接口 /api/rest_j/v1/filesystem/getDirFileTrees
提交方式 GET
请求参数

参数名称	参数说明	请求类型	是否必须	数据类型	schema
path	结果集目录路径	query	true	string

返回示例

{
  "method": "/api/filesystem/getDirFileTrees",
  "status": 0,
  "message": "OK",
  "data": {
    "dirFileTrees": {
      "name": "1946923",
      "path": "hdfs:///tmp/hadoop/linkis/2022-07-06/211446/IDE/1946923",
      "properties": null,
      "children": [
        {
          "name": "_0.dolphin",
          "path": "hdfs:///tmp/hadoop/linkis/2022-07-06/211446/IDE/1946923/_0.dolphin",//result set 1
          "properties": {
            "size": "7900",
            "modifytime": "1657113288360"
          },
          "children": null,
          "isLeaf": true,
          "parentPath": "hdfs:///tmp/hadoop/linkis/2022-07-06/211446/IDE/1946923"
        },
        {
          "name": "_1.dolphin",
          "path": "hdfs:///tmp/hadoop/linkis/2022-07-06/211446/IDE/1946923/_1.dolphin",//result set 2
          "properties": {
            "size": "7900",
            "modifytime": "1657113288614"
          },
          "children": null,
          "isLeaf": true,
          "parentPath": "hdfs:///tmp/hadoop/linkis/2022-07-06/211446/IDE/1946923"
        }
      ],
      "isLeaf": false,
      "parentPath": null
    }
  }
}

8. 获取结果集内容

接口 /api/rest_j/v1/filesystem/openFile
提交方式 GET
请求参数

参数名称	参数说明	请求类型	是否必须	数据类型
path	结果集文件	query	true	string
charset	字符集	query	false	string
page	页码	query	false	ref
pageSize	页面大小	query	false	ref

返回示例

{
  "method": "/api/filesystem/openFile",
  "status": 0,
  "message": "OK",
  "data": {
    "metadata": [
      {
        "columnName": "count(1)",
        "comment": "NULL",
        "dataType": "long"
      }
    ],
    "totalPage": 0,
    "totalLine": 1,
    "page": 1,
    "type": "2",
    "fileContent": [
      [
        "28"
      ]
    ]
  }
}

9. 获取结果集按照文件流的方式

获取结果集为CSV和Excel按照流的方式

接口 /api/rest_j/v1/filesystem/resultsetToExcel
提交方式 GET
请求参数

参数名称	参数说明	请求类型	是否必须	数据类型
autoFormat	是否自动转换格式	query	false	boolean
charset	字符集	query	false	string
csvSeperator	csv分隔栏	query	false	string
limit	获取行数	query	false	ref
nullValue	空值转换	query	false	string
outputFileName	输出文件名称	query	false	string
outputFileType	输出文件类型 csv 或者Excel	query	false	string
path	结果集路径	query	false	string

返回示例

文件流

10. 兼容0.X的任务执行接口

接口 /api/rest_j/v1/entrance/execute
提交方式 POST

{
    "executeApplicationName": "hive", //Engine type
    "requestApplicationName": "dss", //Client service type
    "executionCode": "show tables",
    "params": {
      "variable": {// task variable 
        "testvar": "hello"
      },
      "configuration": {
        "runtime": {// task runtime params 
          "jdbc.url": "XX"
        },
        "startup": { // ec start up params 
          "spark.executor.cores": "4"
        }
      }
    },
    "source": { //task source information
      "scriptPath": "file:///tmp/hadoop/test.sql"
    },
    "labels": {
      "engineType": "spark-2.4.3",
      "userCreator": "hadoop-IDE"
    },
    "runType": "hql", //The type of script to run
    "source": {"scriptPath":"file:///tmp/hadoop/1.hql"}
}

Sample Response

{
 "method": "/api/rest_j/v1/entrance/execute",
 "status": 0,
 "message": "Request executed successfully",
 "data": {
   "execID": "030418IDEhivebdpdwc010004:10087IDE_hadoop_21",
   "taskID": "123"
 }
}