任务提交执行 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 接口规范

• 接口 /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 类型
• 接口 /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. }

• 接口 /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. }

• 接口 /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. }

• 接口 /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. }

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

• 返回示例

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. }

支持多结果集信息

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

• 返回示例

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. }

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

• 返回示例

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. }

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

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

• 返回示例

1. 文件流

• 接口 /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. }