开发文档
能力中心
应用市场
WebOffice
开发者后台

接口说明​ ​

成功生成脚本令牌后，就可以通过 HTTP 接口执行脚本了，我们提供了同步执行和异步执行两种脚本执行接口供开发者使用。

相较而言，前者使用更简单，接口调用后会直接返回执行结果，适用于执行耗时一般的场景；而后者则略微复杂一点，接口调用后不会返回最终的执行的结果，但会立即返回一个task_id，您需要根据此task_id轮询脚本执行的日志，而无需同步等待结果阻塞业务流程，该接口适用于执行耗时比较大的场景。

无论使用您使用哪个接口，都必须先获取到文件 ID 和脚本 ID，请先进入脚本编辑器，在侧边栏列表的更多菜单里复制 webhook 链接即可。

同步执行脚本​ ​

POST /api/v3/ide/file/:file_id/script/:script_id/sync_task

Header 参数 ​

参数必须类型说明
Content-Type是stringapplication/json
AirScript-Token是string传入您通过 AirScript 编辑器生成的脚本令牌（APIToken）

path 参数 ​

参数必须类型说明
script_id是string脚本的 ID
file_id是string运行脚本的文件 ID

body 参数 ​

参数必须类型说明
Context是Object运行时的上下文参数
Context.argv否Object传入的上下文参数对象，比如传入{name: 'xiaomeng', age: 18}，在 AS 代码中可通过Context.argv.name获取到传入的值
Context.sheet_name否stringdb,et,ksheet 运行时所在表名
Context.range否stringet,ksheet 运行时所在区域，例如$B$156
Context.link_from否stringet,ksheet 点击超链接所在单元格
Context.db_active_view否stringdb 运行时所在 view 名
Context.db_selection否stringdb 运行时所在选区

返回参数 ​

参数必须类型说明
data是Object任务执行数据对象
data.result是string任务执行返回的数据
data.logs是Array任务执行日志
data.logs[i].filename是string执行文件的名称
data.logs[i].timestamp是string执行时间
data.logs[i].unix_time是number执行 unix 时间戳
data.logs[i].level是string日志级别
data.logs[i].args是string[]日志打印参数
status是string任务是否执行完毕
error是string任务执行错误信息
error_details是Object错误信息详情对象
error_details.name否string错误信息名称
error_details.msg否string错误信息
error_details.stack否string[]错误信息栈
error_details.unix_time否number错误信息 unix 时间

请求示例 ​

shell
curl --request POST \
	--url https://www.kdocs.cn/api/v3/ide/file/:file_id/script/:script_id/sync_task \
	--header 'AirScript-Token: xxx' \
	--header 'Content-Type: application/json' \
	--data '{"Context":{"argv":{},"sheet_name":"表名"}}'

返回示例 ​

javascript
{
  "data": {
    "logs": [
      {
        "filename": "<system>",
        "timestamp": "16:44:08.271",
        "unix_time": 1690274648271,
        "level": "info",
        "args": ["脚本环境初始化..."]
      },
      {
        "filename": "<system>",
        "timestamp": "16:44:08.953",
        "unix_time": 1690274648953,
        "level": "info",
        "args": ["已开始执行"]
      },
      {
        "filename": "未命名脚本.js:1:9",
        "timestamp": "16:44:08.968",
        "unix_time": 1690274648968,
        "level": "info",
        "args": ["打印参数A：111"]
      },
      {
        "filename": "<system>",
        "timestamp": "16:44:08.969",
        "unix_time": 1690274648969,
        "level": "info",
        "args": ["执行完毕"]
      }
    ],
    "result": "[Undefined]"
  },
  "error": "",
  "status": "finished"
}

异步执行脚本 ​

POST /api/v3/ide/file/:file_id/script/:script_id/task

Header 参数 ​

参数必须类型说明
Content-Type是stringapplication/json
AirScript-Token是string传入您通过 AirScript 编辑器生成的脚本令牌（APIToken）

path 参数 ​

参数必须类型说明
script_id是string脚本的 ID
file_id是string运行脚本的文件 ID

body 参数 ​

参数必须类型说明
Context是Object运行时的上下文参数
Context.argv否Object传入的上下文参数对象，比如传入{name: 'xiaomeng', age: 18}，在 AS 代码中可通过Context.argv.name获取到传入的值
Context.sheet_name否stringdb,et,ksheet 运行时所在表名
Context.range否stringet,ksheet 运行时所在区域，例如$B$156
Context.link_from否stringet,ksheet 点击超链接所在单元格
Context.db_active_view否stringdb 运行时所在 view 名
Context.db_selection否stringdb 运行时所在选区

返回参数 ​

参数必须类型说明
task_id是string运行的任务 Id，用于轮循运行结果
task_type是string任务类型

请求示例 ​

shell
curl --request POST \
	--url https://www.kdocs.cn/api/v3/ide/file/:file_id/script/:script_id/task \
	--header 'AirScript-Token: xxx' \
	--header 'Content-Type: application/json' \
	--data '{"Context":{"argv":{},"sheet_name":"表名"}}'

返回示例 ​

javascript
{
  "data": {
    "task_id": "GN/KU3B3BG84MdCjraN5mukx0Rt5Sp1eJ9k2qClmcaOkkF3PUVNDOYPY7Kz4aQMXSvXn9N08QabldRKjPfzii87fuGYydIuK2la2HMfcxmGK1Pf4WcPEflb5xOOkQQEo8fmEbzcobhurYg=="
  },
  "task_id": "GN/KU3B3BG84MdCjraN5mukx0Rt5Sp1eJ9k2qClmcaOkkF3PUVNDOYPY7Kz4aQMXSvXn9N08QabldRKjPfzii87fuGYydIuK2la2HMfcxmGK1Pf4WcPEflb5xOOkQQEo8fmEbzcobhurYg==",
  "task_type": "open_air_script"
}

获取任务运行情况 ​

GET /api/v3/script/task

query 参数 ​

参数必须类型说明
task_id是string执行异步任务时返回的 ID

任务ID为query参数，拼接时请注意先编码下，比如encodeURIComponent(task_id)

返回参数 ​

参数必须类型说明
data是Object任务执行数据对象
data.result是string任务执行返回的数据
data.logs是Array任务执行日志
data.logs[i].filename是string执行文件的名称
data.logs[i].timestamp是string执行时间
data.logs[i].unix_time是number执行 unix 时间戳
data.logs[i].level是string日志级别
data.logs[i].args是string[]日志打印参数
status是string任务是否执行完毕
error是string任务执行错误信息
error_details否object错误信息详情对象
error_details.name否string错误信息名称
error_details.msg否string错误信息
error_details.stack否string[]错误信息栈
error_details.unix_time否number错误信息 unix 时间

请求示例 ​

shell
curl --request GET \
	--url https://www.kdocs.cn/api/v3/script/task

返回示例 ​

json
{
  "data": {
    "logs": [
      {
        "filename": "<system>",
        "timestamp": "17:05:16.164",
        "unix_time": 1692090316164,
        "level": "info",
        "args": ["脚本环境初始化..."]
      }
    ],
    "result": null
  },
  "error": "Unexpected token (1:91)",
  "error_details": {
    "name": "SyntaxError",
    "msg": "Unexpected token (1:91)",
    "stack": ["    at 未命名脚本.js:1:91"],
    "unix_time": 1692090318372
  },
  "status": "finished"
}