任务提交执行 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

  • 请求参数

参数名称参数说明请求类型是否必须数据类型schema
ididpathtruestring
  • 返回示例
  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

  • 请求参数

参数名称参数说明请求类型是否必须数据类型schema
path结果集目录路径querytruestring
  • 返回示例
  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

  • 请求参数

参数名称参数说明请求类型是否必须数据类型schema
path结果集文件querytruestring
charset字符集queryfalsestring
page页码queryfalseref
pageSize页面大小queryfalseref
  • 返回示例
  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

  • 请求参数

参数名称参数说明请求类型是否必须数据类型schema
autoFormat是否自动转换格式queryfalseboolean
charset字符集queryfalsestring
csvSeperatorcsv分隔栏queryfalsestring
limit获取行数queryfalseref
nullValue空值转换queryfalsestring
outputFileName输出文件名称queryfalsestring
outputFileType输出文件类型 csv 或者Excelqueryfalsestring
path结果集路径queryfalsestring
  • 返回示例
  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. }