创建自定义算子

创建一个可在工作流中使用的自定义算子。代码类型算子需要提供源代码或源文件 ID；内置绑定类型使用基础算子和绑定配置。

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

调用前准备

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。先确定创建代码类型还是内置绑定类型，并准备对应的实现内容。

下方示例使用：

• $AI_STUDIO_API_KEY：实际个人访问令牌，通过 X-API-Key Header 传递。

• $WORKSPACE_ID：目标工作区 ID，通过 X-Workspace-ID Header 传递。

请求体

参数	类型	是否必填	说明
name	string	是	算子名称。
identifier	string	是	算子标识。
description	string	是	算子说明。
input_schema	object	是	输入定义。每个 properties 项必须提供 description。
output_schema	object	是	输出定义。每个 properties 项必须提供 description。
kind	string	否	算子类型；省略时为代码类型。
language	string	否	代码类型的实现语言；当前仅支持 python。
handler	string	否	代码类型的处理函数。Python 处理函数使用模块和函数名，例如 main.handle；对应函数必须接受 workspace_id、sdk 和 input 三个参数。
version	string	否	代码类型的版本。
isolation_level	string	否	代码类型的隔离配置。
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，格式为 moi:custom.operator:<工作区 ID>:<identifier>。
enabled	boolean	否	初始是否启用。
catalog_id	integer	否	关联的 Catalog ID。
database_id	integer	否	关联的数据库 ID。

按算子类型提供字段

kind	必填字段	限制
code（默认）	code 或 source_file_id	两者只能提供一个。
builtin_binding	base_node_id、base_node_version、binding_config	不提供代码或语言字段。

请求示例

curl -X POST "https://moi.matrixorigin.cn/newmoi/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",
    "node_id": "moi:custom.operator:$WORKSPACE_ID: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\"])}"
  }'

成功响应

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

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": 123,
    "node_id": "moi:custom.operator:workspace:text_counter",
    "name": "文本计数",
    "identifier": "text_counter",
    "language": 1,
    "kind": 1,
    "input_schema": "{\"type\":\"object\"}",
    "output_schema": "{\"type\":\"object\"}",
    "enabled": true
  }
}

响应字段如下。

字段	类型	说明
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.language	integer	实现语言的数值编码。请求中的 language 使用字符串。
data.kind	integer	算子类型的数值编码。请求中的 kind 使用字符串。
data.handler	string	处理函数；有值时返回。
data.version	string	算子版本；有值时返回。
data.isolation_level	string	隔离配置；有值时返回。
data.source_file_id	string	源文件 ID；使用源文件创建时返回。
data.input_schema	string	输入定义的序列化内容。
data.output_schema	string	输出定义的序列化内容。
data.created_by	string	创建者标识；有值时返回。
data.updated_by	string	最后更新者标识；有值时返回。
data.created_at	integer	创建时间戳；有值时返回。
data.updated_at	integer	最后更新时间戳；有值时返回。
data.base_node_id	string	内置绑定类型关联的基础算子；有值时返回。
data.base_node_version	string	内置绑定类型关联的基础算子版本；有值时返回。
data.binding_config	string	绑定配置的序列化内容；有值时返回。
data.catalog_id	integer	关联的 Catalog ID；有值时返回。
data.database_id	integer	关联的数据库 ID；有值时返回。
data.enabled	boolean	算子是否已启用。

错误响应

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

常见 HTTP 错误

HTTP 状态码	错误代码	常见原因	建议操作
400	ErrParamInvalid	请求体缺少必填字段、schema 属性未提供 description，或算子类型与实现字段不匹配。	检查请求体，并为每个 schema 属性补充 description。
401	ErrUnauthorized	个人访问令牌缺失或无效。	检查个人访问令牌和工作区 ID。
403	ErrForbidden	当前身份没有创建自定义算子的权限。	使用有权限的凭据，或联系管理员授权。
409	ErrConflict	新算子与已有资源冲突。	修改标识或处理冲突资源后重试。
500	ErrServer	服务暂时无法创建算子。	记录错误信息后重试。

后续操作

查询自定义算子详情或试运行自定义算子。

最后更新于 2026 年 8 月 22 日