发布工作流

创建工作流，或在提供 workflow_id 时发布该工作流的新定义。发布只保存工作流定义，不表示该工作流已执行。

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

调用前准备

准备有目标工作区访问权限且具有创建工作流权限的个人访问令牌、目标工作区 ID 和工作流 DSL。

下方示例使用：

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

• $WORKSPACE_ID：要发布工作流的工作区 ID，通过 X-Workspace-ID Header 传递。

请求体不能包含运行时上下文字段。

请求体

创建或更新发布时，需要同时指定名称和 DSL；其余字段按执行模式和触发方式提供。

字段	类型	是否必填	说明
name	string	是	工作流名称。
dsl_yaml	string	是	工作流 DSL 的 YAML 文本。
workflow_id	string	否	已有工作流 ID；提供时更新该工作流的部署定义。
description	string	否	工作流说明。
source_type	string	否	工作流来源类型；省略时为 manual_dsl。发布 Memory Governance 模板时必须传 memory_governance。
execution_mode	string	否	执行模式。可选值为 one_shot（默认）、dynamic_service、stream、cron、volume_trigger；cron 必须同时提供 cron_expression，不支持 manual。
cron_expression	string	否	定时执行的 Cron 表达式。
compute_resource_id	string	否	工作流关联的计算资源 ID。
runtime_fields	object	否	运行时输入表单定义。
runtime_layout	object	否	运行时输入表单布局。
default_values	object	否	运行时输入的默认值。
volume_trigger	object	否	卷触发器配置。
dynamic_service	object	否	动态服务配置。
design_graph	object	否	工作流设计图。

请求示例

curl -X POST "https://moi.matrixorigin.cn/newmoi/workflow/v2/workflow-deployments" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "<WORKFLOW_NAME>",
    "dsl_yaml": "<WORKFLOW_DSL_YAML>",
    "execution_mode": "<EXECUTION_MODE>"
  }'

成功响应

成功时返回 200。data.workflow 是已发布工作流的摘要；data.deployment 仅在服务返回部署信息时出现。保存 data.workflow.id，用于后续管理和运行。发布成功不表示该工作流已执行。

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "workflow": {
      "id": "wf-001",
      "name": "daily-import",
      "source_type": "manual_dsl",
      "execution_mode": "cron",
      "cron_expression": "0 2 * * *",
      "status": "ready"
    },
    "warnings": []
  }
}

响应字段如下。

字段	类型	说明
code	string	成功时为 OK。
msg	string	成功时为 OK。
data.workflow	object	已发布工作流摘要。
data.workflow.id	string	工作流 ID。
data.workflow.name	string	工作流名称。
data.workflow.source_type	string	工作流来源类型。
data.workflow.execution_mode	string	已发布的执行模式。
data.workflow.cron_expression	string	Cron 表达式；仅定时模式返回。
data.workflow.draft_id	string	草稿标识；服务端提供时返回。
data.workflow.candidate_id	string	候选标识；服务端提供时返回。
data.workflow.status	string	当前工作流状态。
data.deployment	object	服务返回的部署信息；仅在服务返回时出现。
data.warnings	string（字符串数组）	发布成功但需要调用方关注的警告；仅在有警告时返回。

执行模式说明

• 单次运行： 手工从 API 启动一次工作流时，使用 one_shot，或省略 execution_mode。不要传 manual；该值会返回 ErrParamInvalid。

• 定时触发： 使用 cron 描述持久化的定时触发，并同时提供 cron_expression。仍可通过作业启动接口手动运行一次。

• 卷触发： 使用 volume_trigger 描述持久化的卷触发。仍可通过作业启动接口手动运行一次。

错误响应

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

常见 HTTP 错误

HTTP 状态码	错误代码	常见原因	建议操作
400	ErrParamInvalid	请求体、DSL、执行模式、触发器或计算资源配置不符合要求。	修正请求字段和 DSL 后重新提交。
401	ErrUnauthorized	缺少或无效的访问凭据。	检查 API Key 和工作区 Header。
403	ErrForbidden	当前身份没有创建工作流或使用依赖资源的权限。	请求授予所需权限。
404	ErrNotFound	请求引用的资源不存在。	核对资源 ID 与当前工作区。
409	ErrConflict	工作流标识或发布操作与已有状态冲突。	读取现有工作流后按最新状态重试。
500	ErrServer	服务端发布失败。	稍后重试。

后续操作

查询工作流详情或启动工作流作业。

最后更新于 2026 年 8 月 22 日