创建自定义算子

创建一个可在工作流中使用的自定义算子。代码类型提供 Python 代码或源文件；内置绑定类型基于一个工作流算子版本创建绑定配置。

POST https://api.moi.matrixorigin.cn/v5/workflow/v2/custom-operators

调用前准备

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID，分别通过 X-API-Key 和 X-Workspace-ID 请求头传递。然后按要创建的类型准备内容：

• 创建代码类型时，准备 Python 源代码或源文件 ID。

• 创建内置绑定类型时，先查看工作流算子详情，选择基础算子版本，并记录其算子 ID 和版本以及所需的绑定配置。

请求体

输入示例

curl -X POST "https://api.moi.matrixorigin.cn/v5/workflow/v2/custom-operators" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "文本计数",
    "identifier": "text_counter",
    "description": "统计输入文本的字符数。",
    "language": "python",
    "handler": "main.handle",
    "input_schema": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "description": "要统计的文本。"
        }
      }
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "count": {
          "type": "integer",
          "description": "文本的字符数。"
        }
      }
    },
    "code": "def handle(workspace_id, sdk, input):\n    return {\"count\": len(input[\"text\"])}"
  }'

参数说明

字段	类型	是否必填	说明
name	string	必填	算子名称。
identifier	string	必填	算子标识。
description	string	必填	算子说明。
kind	string	否	算子类型；省略时为代码类型。
language	string	否	代码类型的实现语言；当前仅支持 python。
handler	string	否	代码类型的处理函数。Python 处理函数使用模块和函数名，例如 main.handle；对应函数必须接受 workspace_id、sdk 和 input 三个参数。
input_schema	object	必填	输入定义。每个属性必须提供类型和说明。
output_schema	object	必填	输出定义。每个属性必须提供类型和说明。
version	string	否	算子版本；省略时为 v1。
isolation_level	string	否	代码类型的隔离配置；当前仅支持 PUBLIC。
code	string	否	代码类型的源代码；与 source_file_id 二选一。
source_file_id	string	否	代码类型的源文件 ID；与 code 二选一。
base_node_id	string	否	内置绑定类型所需的基础算子 ID。
base_node_version	string	否	内置绑定类型所需的基础算子版本。
binding_config	object	否	内置绑定类型所需的绑定配置。
node_id	string	否	自定义的工作流算子 ID。省略时系统根据目标工作区和 identifier 生成。
enabled	boolean	否	初始是否启用。
catalog_id	integer	否	关联的 Catalog ID。
database_id	integer	否	关联的数据库 ID。

成功响应

响应返回新建算子的 ID 和配置。保存算子 ID，后续查看、更新、试运行、启用、停用和删除均需使用该 ID。

响应字段如下。

响应示例

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": 123,
    "node_id": "moi:custom.operator:workspace:text_counter",
    "name": "文本计数",
    "identifier": "text_counter",
    "description": "统计输入文本的字符数。",
    "language": 1,
    "kind": 1,
    "handler": "main.handle",
    "input_schema": "{\"type\":\"object\"}",
    "output_schema": "{\"type\":\"object\"}",
    "isolation_level": "PUBLIC",
    "catalog_id": 1,
    "database_id": 2,
    "enabled": true,
    "created_by": "user_01",
    "updated_by": "user_01"
  }
}

字段说明

字段	类型	是否必填	说明
code	string	否	成功时为 OK。
msg	string	否	成功时为 OK。
data.id	integer	否	新建的自定义算子 ID。
data.node_id	string	否	工作流中的算子 ID。
data.name	string	否	算子名称。
data.identifier	string	否	算子标识。
data.description	string	否	算子说明；有值时返回。
data.version	string	否	算子版本；有值时返回。
data.language	integer	否	算子实现语言代码。
data.kind	integer	否	算子类型代码。
data.handler	string	否	代码类型的处理函数；有值时返回。
data.input_schema	string	否	输入定义的序列化内容；有值时返回。
data.output_schema	string	否	输出定义的序列化内容；有值时返回。
data.isolation_level	string	否	算子隔离配置；有值时返回。
data.source_file_id	string	否	源文件 ID；以源文件创建时返回。
data.catalog_id	integer	否	关联的 Catalog ID；有值时返回。
data.database_id	integer	否	关联的数据库 ID；有值时返回。
data.enabled	boolean	否	算子是否已启用。
data.created_by	string	否	创建者标识；有值时返回。
data.updated_by	string	否	最近更新者标识；有值时返回。

错误响应

响应示例

{
  "code": "ErrParamInvalid",
  "msg": "请求参数无效",
  "data": null
}

字段说明

字段	类型	是否必填	说明
code	string	否	错误代码。
msg	string	否	可读错误信息。
data	null	否	错误响应中为 null。

后续操作

记录响应中的自定义算子 ID 后，查看自定义算子详情确认配置。只有已启用的 Python 代码类型才可试运行自定义算子。

最后更新于 2026 年 9 月 11 日