任务提交执行 Rest API 文档

  • Linkis Restful接口的返回，都遵循以下的标准返回格式：
1. {
2. "method": "",
3. "status": 0,
4. "message": "",
5. "data": {}
6. }

约定：

  • 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
1. {
2. "executionContent": {
3. "code": "show tables",
4. "runType": "sql"
5. },
6. "params": {
7. "variable": {// task variable
8. "testvar": "hello"
9. },
10. "configuration": {
11. "runtime": {// task runtime params
12. "jdbc.url": "XX"
13. },
14. "startup": { // ec start up params
15. "spark.executor.cores": "4"
16. }
17. }
18. },
19. "source": { //task source information
20. "scriptPath": "file:///tmp/hadoop/test.sql"
21. },
22. "labels": {
23. "engineType": "spark-2.4.3",
24. "userCreator": "hadoop-IDE"
25. }
26. }
  • 返回示例
1. {
2. "method": "/api/rest_j/v1/entrance/submit",
3. "status": 0,
4. "message": "请求执行成功",
5. "data": {
6. "execID": "030418IDEhivebdpdwc010004:10087IDE_hadoop_21",
7. "taskID": "123"
8. }
9. }
  • 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
  • 返回示例
1. {
2. "method": "/api/rest_j/v1/entrance/{execID}/status",
3. "status": 0,
4. "message": "获取状态成功",
5. "data": {
6. "execID": "${execID}",
7. "status": "Running"
8. }
9. }

3. 获取日志

  • 接口 /api/rest_j/v1/entrance/${execID}/log?fromLine=${fromLine}&size=${size}
  • 提交方式 GET
  • 请求参数fromLine是指从第几行开始获取，size是指该次请求获取几行日志
  • 返回示例，其中返回的fromLine需要作为下次请求该接口的参数
1. {
2. "method": "/api/rest_j/v1/entrance/${execID}/log",
3. "status": 0,
4. "message": "返回日志信息",
5. "data": {
6. "execID": "${execID}",
7. "log": ["error日志","warn日志","info日志", "all日志"],
8. "fromLine": 56
9. }
10. }

4. 获取进度

  • 接口 /api/rest_j/v1/entrance/${execID}/progress
  • 提交方式 GET
  • 返回示例
1. {
2. "method": "/api/rest_j/v1/entrance/{execID}/progress",
3. "status": 0,
4. "message": "返回进度信息",
5. "data": {
6. "execID": "${execID}",
7. "progress": 0.2,
8. "progressInfo": [
9. {
10. "id": "job-1",
11. "succeedTasks": 2,
12. "failedTasks": 0,
13. "runningTasks": 5,
14. "totalTasks": 10
15. },
16. {
17. "id": "job-2",
18. "succeedTasks": 5,
19. "failedTasks": 0,
20. "runningTasks": 5,
21. "totalTasks": 10
22. }
23. ]
24. }
25. }

5. kill任务

  • 接口 /api/rest_j/v1/entrance/${execID}/kill
  • 提交方式 GET
  • 返回示例
1. {
2. "method": "/api/rest_j/v1/entrance/{execID}/kill",
3. "status": 0,
4. "message": "OK",
5. "data": {
6. "execID":"${execID}"
7. }
8. }

6. 获取任务信息

  • 接口 /api/rest_j/v1/jobhistory/{id}/get
  • 提交方式 GET
  • 请求参数
参数名称 参数说明 请求类型 是否必须 数据类型 schema
id id path true string
  • 返回示例
1. {
2. "method": null,
3. "status": 0,
4. "message": "OK",
5. "data": {
6. "task": {
7. "taskID": 1,
8. "instance": "xxx",
9. "execId": "exec-id-xxx",
10. "umUser": "test",
11. "engineInstance": "xxx",
12. "progress": "10%",
13. "logPath": "hdfs://xxx/xxx/xxx",
14. "resultLocation": "hdfs://xxx/xxx/xxx",
15. "status": "FAILED",
16. "createdTime": "2019-01-01 00:00:00",
17. "updatedTime": "2019-01-01 01:00:00",
18. "engineType": "spark",
19. "errorCode": 100,
20. "errDesc": "Task Failed with error code 100",
21. "executeApplicationName": "hello world",
22. "requestApplicationName": "hello world",
23. "runType": "xxx",
24. "paramJson": "{\"xxx\":\"xxx\"}",
25. "costTime": 10000,
26. "strongerExecId": "execId-xxx",
27. "sourceJson": "{\"xxx\":\"xxx\"}"
28. }
29. }
30. }

7. 获取结果集信息

支持多结果集信息

  • 接口 /api/rest_j/v1/filesystem/getDirFileTrees
  • 提交方式 GET
  • 请求参数
参数名称 参数说明 请求类型 是否必须 数据类型 schema
path 结果集目录路径 query true string
  • 返回示例
1. {
2. "method": "/api/filesystem/getDirFileTrees",
3. "status": 0,
4. "message": "OK",
5. "data": {
6. "dirFileTrees": {
7. "name": "1946923",
8. "path": "hdfs:///tmp/hadoop/linkis/2022-07-06/211446/IDE/1946923",
9. "properties": null,
10. "children": [
11. {
12. "name": "_0.dolphin",
13. "path": "hdfs:///tmp/hadoop/linkis/2022-07-06/211446/IDE/1946923/_0.dolphin",//result set 1
14. "properties": {
15. "size": "7900",
16. "modifytime": "1657113288360"
17. },
18. "children": null,
19. "isLeaf": true,
20. "parentPath": "hdfs:///tmp/hadoop/linkis/2022-07-06/211446/IDE/1946923"
21. },
22. {
23. "name": "_1.dolphin",
24. "path": "hdfs:///tmp/hadoop/linkis/2022-07-06/211446/IDE/1946923/_1.dolphin",//result set 2
25. "properties": {
26. "size": "7900",
27. "modifytime": "1657113288614"
28. },
29. "children": null,
30. "isLeaf": true,
31. "parentPath": "hdfs:///tmp/hadoop/linkis/2022-07-06/211446/IDE/1946923"
32. }
33. ],
34. "isLeaf": false,
35. "parentPath": null
36. }
37. }
38. }

8. 获取结果集内容

  • 接口 /api/rest_j/v1/filesystem/openFile
  • 提交方式 GET
  • 请求参数
参数名称 参数说明 请求类型 是否必须 数据类型 schema
path 结果集文件 query true string
charset 字符集 query false string
page 页码 query false ref
pageSize 页面大小 query false ref
  • 返回示例
1. {
2. "method": "/api/filesystem/openFile",
3. "status": 0,
4. "message": "OK",
5. "data": {
6. "metadata": [
7. {
8. "columnName": "count(1)",
9. "comment": "NULL",
10. "dataType": "long"
11. }
12. ],
13. "totalPage": 0,
14. "totalLine": 1,
15. "page": 1,
16. "type": "2",
17. "fileContent": [
18. [
19. "28"
20. ]
21. ]
22. }
23. }

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

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

  • 接口 /api/rest_j/v1/filesystem/resultsetToExcel
  • 提交方式 GET
  • 请求参数
参数名称 参数说明 请求类型 是否必须 数据类型 schema
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
  • 返回示例
1. 文件流

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

  • 接口 /api/rest_j/v1/entrance/execute
  • 提交方式 POST
1. {
2. "executeApplicationName": "hive", //Engine type
3. "requestApplicationName": "dss", //Client service type
4. "executionCode": "show tables",
5. "params": {
6. "variable": {// task variable
7. "testvar": "hello"
8. },
9. "configuration": {
10. "runtime": {// task runtime params
11. "jdbc.url": "XX"
12. },
13. "startup": { // ec start up params
14. "spark.executor.cores": "4"
15. }
16. }
17. },
18. "source": { //task source information
19. "scriptPath": "file:///tmp/hadoop/test.sql"
20. },
21. "labels": {
22. "engineType": "spark-2.4.3",
23. "userCreator": "hadoop-IDE"
24. },
25. "runType": "hql", //The type of script to run
26. "source": {"scriptPath":"file:///tmp/hadoop/1.hql"}
27. }
  • Sample Response
1. {
2. "method": "/api/rest_j/v1/entrance/execute",
3. "status": 0,
4. "message": "Request executed successfully",
5. "data": {
6. "execID": "030418IDEhivebdpdwc010004:10087IDE_hadoop_21",
7. "taskID": "123"
8. }
9. }