搜索

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

Python 脚本

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

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

适用说明

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

运行接口（外部集成）：用于外部客户业务系统、ESB、API 网关和第三方系统调用 Python 元素。
运行接口（内部调用）：用于 DeepFOS 平台内部服务、组件及统一封装层调用 Python 元素。
异步结果查询接口：用于异步运行后，通过任务 ID 查询脚本返回值或执行输出。
文件上传接口：用于导入 .py 文件或包含 .py 文件的 .zip 包，适合初始化项目空间或迁移脚本。

运行接口（外部集成）

外部集成接口只供外部客户业务系统、ESB、API 网关和第三方系统调用，不用于 DeepFOS 平台内部服务或组件之间的调用。

接口将 Python 元素名称放在请求路径中，将元素定位和运行控制参数放在 Query 中。请求 Body 只包含脚本需要的业务参数，整个 Body 会直接作为脚本的 parameter，不需要增加 parameter 外层包装。

path 和 folderId 用于定位 Python 元素，二者不能同时传入：

传入 path 时，在指定路径下查找对应 Python 元素。
传入 folderId 时，在指定目录下查找对应 Python 元素。
两者都不传时，按照 elementName 和元素类型 PY 查找；唯一命中时执行该元素。
未找到对应元素时，返回元素不存在错误。
两者都不传且存在多个同名 Python 元素时，返回同名元素不唯一错误。调用方需要补充 path 或 folderId。

同步运行 Python 元素

用于启动 Python 脚本、等待执行完成并直接取得脚本返回值。适合执行时间可控，且调用方需要立即获得业务结果的场景。

请求

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

Path Parameters

参数名	类型	必填	说明
elementName	String	是	Python 元素名称或编码。

Query Parameters

参数名	类型	必填	默认值	说明
path	String	否	-	Python 元素所在路径，与 `folderId` 不能同时传入。
folderId	String	否	-	Python 元素所在目录 ID，与 `path` 不能同时传入。
taskName	String	否	-	本次运行任务的名称。
timeout	Integer	否	无超时	等待脚本完成的超时时间，单位为秒。
terminateOnTimeout	Boolean	否	`false`	超时后是否终止仍在运行的脚本。
compressedFlag	Boolean	否	`false`	请求参数是否使用压缩格式。
elementType	String	否	`PY`	元素类型。调用 Python 元素时使用 `PY`。

Request Body 示例

Copy

{
  "period": "2026M01",
  "company": "A01"
}

请求地址示例：

Copy

POST /external/check_budget/run-sync?path=//finance/budget&timeout=60&terminateOnTimeout=true

成功响应

执行成功时，不使用统一响应结构。Python 脚本 return 什么内容，接口就直接返回什么内容。

例如脚本返回校验结果时，接口直接响应：

Copy

{
  "valid": true,
  "message": "校验通过"
}

失败响应

接口参数校验失败、元素定位失败或脚本执行失败时，继续使用原有错误响应结构：

Copy

{
  "status": false,
  "code": 28030001,
  "message": "脚本运行失败",
  "data": null
}

异步运行 Python 元素

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

请求

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

Path Parameters

参数名	类型	必填	说明
elementName	String	是	Python 元素名称或编码。

Query Parameters

参数名	类型	必填	默认值	说明
path	String	否	-	Python 元素所在路径，与 `folderId` 不能同时传入。
folderId	String	否	-	Python 元素所在目录 ID，与 `path` 不能同时传入。
taskName	String	否	-	本次运行任务的名称。
compressedFlag	Boolean	否	`false`	请求参数是否使用压缩格式。
elementType	String	否	`PY`	元素类型。调用 Python 元素时使用 `PY`。

Request Body 示例

Copy

{
  "batchNo": "B20260610001",
  "sourceSystem": "ERP"
}

请求地址示例：

Copy

POST /external/prepare_consolidation/run?path=//finance/consolidation&taskName=合并报表数据预处理

响应

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

Copy

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

运行接口（内部调用）

内部调用接口供 DeepFOS 平台内部服务、组件及统一封装层使用，不作为外部客户、ESB 或第三方系统的集成入口。

同步运行脚本

用于通过统一接口同步运行脚本。适合调用方希望在同一个接口中动态指定 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 为脚本返回值，具体结构由脚本定义。

异步运行脚本

用于通过统一接口异步运行脚本。适合平台内部统一代理、统一调度或统一封装层需要在请求体中动态指定不同 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，可用于异步结果查询。

异步结果查询接口

异步运行接口返回任务 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": "成功"
    }
  ]
}