任务提交执行 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": "030418IDEhivelocalhost010004: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

• 请求参数

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

• 请求参数

参数名称	参数说明	请求类型	是否必须	数据类型	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

• 返回示例

文件流

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": "030418IDEhivelocalhost010004:10087IDE_hadoop_21",
   "taskID": "123"
 }
}