文档中心

搜索

文档中心开发者中心 API 文档Python 脚本

Python 脚本

本文面向调用 DeepFOS Python 脚本能力的开发者，说明不同接口适合什么场景。

下文 Path 均为相对路径。完整地址由环境域名、服务前缀和 Path 组成；通用鉴权、请求头、响应结构按开发者文档统一约定处理。

适用说明

Python 脚本接口主要分为三组：

运行接口：用于触发 Python 元素执行。对外系统优先使用 Python 路由风格；已有统一封装层的调用方可以使用通用脚本风格。
异步结果查询接口：用于异步运行后，通过任务 ID 查询脚本返回值或执行输出。
文件上传接口：用于导入 .py 文件或包含 .py 文件的 .zip 包，适合初始化项目空间或迁移脚本。

如果对方是 ESB、API 网关、调度平台或第三方系统，建议优先使用 /py/{element_name}/... 这一类 Python 路由风格接口。接口地址本身带业务语义，更适合在外部系统中配置、区分和维护。

运行接口

运行接口用于触发 Python 元素执行。根据调用方的配置方式，可以选择 Python 路由风格或通用脚本风格。

异步运行 Python 元素（路由风格）

用于提交运行任务并立即返回任务 ID。适合耗时较长、调用方不需要同步等待结果的脚本。

请求

项目	值
HTTP Method	`POST`
Path	`/py/{element_name}/run`
Content-Type	`application/json`

Path Parameters

参数名	类型	必填	说明
element_name	String	是	Python 元素名称。

Request Body 字段

字段名	类型	必填	说明
parameter	Object	是	脚本执行参数，结构由 Python 脚本约定。
folderId	String	否	Python 元素所在目录 ID，与 `path` 二选一。
path	String	否	Python 元素所在路径，与 `folderId` 二选一。
taskName	String	否	任务名称，用于识别本次运行。

Request Body 示例

Copy

{
  "path": "//finance/consolidation",
  "taskName": "合并报表数据预处理",
  "parameter": {
    "batchNo": "B20260610001",
    "sourceSystem": "ERP"
  }
}

响应

成功时 data 为任务 ID，可用于查询结果或执行输出。

Copy

{
  "status": true,
  "code": null,
  "message": null,
  "data": "7f6b5f0c-8d3a-4c10-9b60-65e8f0d7a001"
}

同步运行 Python 元素（路由风格）

用于启动脚本并等待返回值。适合运行时间可控、调用方需要立即拿到结果的脚本。

请求

项目	值
HTTP Method	`POST`
Path	`/py/{element_name}/run-sync`
Content-Type	`application/json`

Path Parameters

参数名	类型	必填	说明
element_name	String	是	Python 元素名称。

Request Body 字段

字段名	类型	必填	说明
parameter	Object	是	脚本执行参数，结构由 Python 脚本约定。
folderId	String	否	Python 元素所在目录 ID，与 `path` 二选一。
path	String	否	Python 元素所在路径，与 `folderId` 二选一。
timeout	Integer	否	等待脚本完成的超时时间，单位秒。
terminateOnTimeout	Boolean	否	超时时是否终止脚本。

Request Body 示例

Copy

{
  "path": "//finance/budget",
  "timeout": 60,
  "terminateOnTimeout": true,
  "parameter": {
    "period": "2026M01",
    "company": "A01"
  }
}

响应

成功时 data 为脚本返回值，具体结构由脚本定义。

Copy

{
  "status": true,
  "code": null,
  "message": null,
  "data": {
    "valid": true,
    "message": "校验通过"
  }
}

异步运行脚本（通用风格）

用于通过统一接口异步运行脚本。适合调用方已有统一代理、统一调度或统一封装层，需要在请求体中动态指定不同 Python 元素的场景。

请求

项目	值
HTTP Method	`POST`
Path	`/script/run`
Content-Type	`application/json`

Request Body 字段

字段名	类型	必填	说明
elementName	String	是	Python 元素名称。
elementType	String	是	元素类型，Python 脚本传 `PY`。
parameter	Object	是	脚本执行参数，结构由 Python 脚本约定。
folderId	String	否	Python 元素所在目录 ID，与 `path` 二选一。
path	String	否	Python 元素所在路径，与 `folderId` 二选一。

Request Body 示例

Copy

{
  "elementName": "receive_budget",
  "elementType": "PY",
  "path": "//finance/budget",
  "parameter": {
    "period": "2026M01"
  }
}

响应

成功时 data 为任务 ID，可用于异步结果查询。

同步运行脚本（通用风格）

用于通过统一接口同步运行脚本。适合调用方希望在同一个接口中动态指定 Python 元素，并立即取得脚本返回值的场景。

请求

项目	值
HTTP Method	`POST`
Path	`/script/run-sync`
Content-Type	`application/json`

Request Body 字段

字段名	类型	必填	说明
elementName	String	是	Python 元素名称。
elementType	String	是	元素类型，Python 脚本传 `PY`。
parameter	Object	是	脚本执行参数，结构由 Python 脚本约定。
folderId	String	否	Python 元素所在目录 ID，与 `path` 二选一。
path	String	否	Python 元素所在路径，与 `folderId` 二选一。
timeout	Integer	否	等待脚本完成的超时时间，单位秒。
terminateOnTimeout	Boolean	否	超时时是否终止脚本。

Request Body 示例

Copy

{
  "elementName": "receive_budget",
  "elementType": "PY",
  "path": "//finance/budget",
  "timeout": 60,
  "terminateOnTimeout": true,
  "parameter": {
    "period": "2026M01"
  }
}

响应

成功时 data 为脚本返回值，具体结构由脚本定义。

异步结果查询接口

异步运行接口返回任务 ID。调用方需要结果时，再使用任务 ID 查询脚本返回值或执行输出。

查询脚本返回值

用于获取脚本返回值。适合业务系统只关心最终业务结果、不需要查看执行输出的场景。

请求

项目	值
HTTP Method	`GET`
Path	`/script/result/{taskId}`

Path Parameters

参数名	类型	必填	说明
taskId	String	是	异步运行接口返回的任务 ID。

Query Parameters

参数名	类型	必填	说明
timeout	Integer	否	等待结果的超时时间，单位秒。

请求示例

Copy

GET /script/result/{taskId}?timeout=30

查询脚本执行输出

用于获取脚本返回值、执行输出和错误信息。适合联调、排查或需要查看脚本执行过程的场景。

请求

项目	值
HTTP Method	`GET`
Path	`/script/lifespan/{taskId}`

Path Parameters

参数名	类型	必填	说明
taskId	String	是	异步运行接口返回的任务 ID。

Query Parameters

参数名	类型	必填	说明
timeout	Integer	否	等待结果的超时时间，单位秒。

请求示例

Copy

GET /script/lifespan/{taskId}?timeout=30

响应体字段

字段名	类型	说明
success	Boolean	是否正常结束。
retval	Object	脚本返回值。
stdout	String	执行输出。
stderr	String	错误信息。

文件上传接口

文件上传接口用于把 .py 文件或包含 .py 文件的 .zip 包导入为 Python 元素。单个文件上传也使用该接口，只传一个 batchFile 即可。

上传 Python 文件

适合初始化项目空间、迁移脚本、批量导入脚本文件等场景。

请求

项目	值
HTTP Method	`POST`
Path	`/file/batch-upload`
Content-Type	`multipart/form-data`

Form Data

字段名	类型	必填	说明
batchFile	File	是	上传文件，支持 `.py` 和 `.zip`，可传一个或多个。
folderId	String	否	导入目标目录 ID，与 `path` 二选一。
path	String	否	导入目标路径，与 `folderId` 二选一。
overwrite	Boolean	否	是否覆盖同名元素。

请求示例

Copy

curl -X POST "https://{host}/{service-prefix}/file/batch-upload" \
  -F "batchFile=@import_sales_order.py" \
  -F "path=//sales/order" \
  -F "overwrite=false"

响应

data 为每个文件的处理结果列表。

Copy

{
  "status": true,
  "code": null,
  "message": null,
  "data": [
    {
      "filePath": "//sales/order/import_sales_order.py",
      "status": 0,
      "message": "成功"
    }
  ]
}

上一篇：API 文档概述

下一篇：变量

本页目录

适用说明
运行接口

异步运行 Python 元素（路由风格）
同步运行 Python 元素（路由风格）
异步运行脚本（通用风格）
同步运行脚本（通用风格）

异步结果查询接口

查询脚本返回值
查询脚本执行输出

文件上传接口

上传 Python 文件

回到顶部

咨询热线

400-821-9199

我们使用 ChatGPT，基于文档中心的内容以及对话上下文回答您的问题。