# 创建工作流

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

在当前工作区创建工作流定义。创建成功后不会自动启动作业。

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

## 调用前准备

准备具有创建工作流权限的[个人访问令牌](../../../../../guides/genesis/api-keys.md#创建和管理个人访问令牌)、[目标工作区 ID](../../../../../guides/ai-studio/resource-center/workspace.md#复制工作区-id)和工作流 DSL。

## 请求体

将 `$AI_STUDIO_API_KEY`、`$WORKSPACE_ID` 和示例中的工作流名称、DSL 替换为实际值。

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

::::{tab-set}
:::{tab-item} 单次运行

```bash
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": "daily-import",
    "dsl_yaml": "workflow:\\n  name: daily-import\\n  root: main\\nroot:\\n  chain: []\\n",
    "execution_mode": "one_shot"
  }'
```

:::
:::{tab-item} 动态服务

```bash
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": "order-query-service",
    "dsl_yaml": "workflow:\\n  name: order-query-service\\n  root: main\\nroot:\\n  chain: []\\n",
    "execution_mode": "dynamic_service",
    "dynamic_service": {
      "service_name": "order-query-service"
    }
  }'
```

:::
:::{tab-item} 定时触发

```bash
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": "daily-import",
    "dsl_yaml": "workflow:\\n  name: daily-import\\n  root: main\\nroot:\\n  chain: []\\n",
    "execution_mode": "cron",
    "cron_expression": "0 2 * * *"
  }'
```

:::
:::{tab-item} 卷触发

```bash
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": "volume-import",
    "dsl_yaml": "workflow:\\n  name: volume-import\\n  root: main\\nroot:\\n  chain: []\\n",
    "execution_mode": "volume_trigger",
    "volume_trigger": {
      "volume_id": 1001,
      "enabled": true
    }
  }'
```

:::
::::

:::::

:::::{tab-item} 参数说明

创建工作流时必须提供 `name` 和 `dsl_yaml`。`source_type` 省略时按手写 DSL（`manual_dsl`）处理。创建时不传 `workflow_id` 或 `runtime_context`；修改已有工作流请使用[更新工作流](update-workflow.md#请求体)。

::::{tab-set}
:class: mo-api-parameter-table

:::{tab-item} 单次运行

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 是 | 工作流名称。 |
| `description` | string | 否 | 工作流说明。 |
| `dsl_yaml` | string | 是 | 工作流 DSL 的 YAML 文本。 |
| `execution_mode` | string | 否 | 运行方式；省略时为 `one_shot`。 |
| `source_type` | string | 否 | 工作流来源类型；省略时为 `manual_dsl`。DSL 使用记忆治理 WorkItem 时必须传 `memory_governance`。 |
| `runtime_fields` | object | 否 | 运行时输入表单配置。 |
| `runtime_layout` | object | 否 | 运行时输入表单的布局配置。 |
| `default_values` | object | 否 | 运行时输入表单的默认值。 |
| `design_graph` | object | 否 | 工作流设计图配置。 |
| `compute_resource_id` | string | 否 | 关联的计算资源 ID。 |

:::
:::{tab-item} 动态服务

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 是 | 工作流名称。 |
| `dsl_yaml` | string | 是 | 工作流 DSL 的 YAML 文本。 |
| `execution_mode` | string | 是 | 填写 `dynamic_service`。 |
| `dynamic_service` | object | 是 | 动态服务配置。 |
| `dynamic_service.service_name` | string | 否 | 动态服务名称。 |
| `dynamic_service.input_schema` | string | 否 | 动态服务输入的 Schema。 |
| `dynamic_service.output_schema` | string | 否 | 动态服务输出的 Schema。 |
| `dynamic_service.result_mode` | string | 否 | 动态服务的结果模式。 |
| `dynamic_service.runtime_spec_json` | string | 否 | 动态服务运行时配置的 JSON 文本。 |

其他可选字段可参见“单次运行”页签。

:::
:::{tab-item} 定时触发

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 是 | 工作流名称。 |
| `dsl_yaml` | string | 是 | 工作流 DSL 的 YAML 文本。 |
| `execution_mode` | string | 是 | 填写 `cron`。 |
| `cron_expression` | string | 是 | Cron 表达式。 |

其他可选字段可参见“单次运行”页签。

:::
:::{tab-item} 卷触发

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 是 | 工作流名称。 |
| `dsl_yaml` | string | 是 | 工作流 DSL 的 YAML 文本。 |
| `execution_mode` | string | 是 | 填写 `volume_trigger`。 |
| `volume_trigger` | object | 否 | 卷触发配置；运行时输入表单未提供卷 ID 时，必须填写其中的 `volume_id`。 |
| `volume_trigger.volume_id` | integer | 条件必填 | 卷 ID；运行时输入表单未提供卷 ID 时必填。 |
| `volume_trigger.enabled` | boolean | 否 | 是否启用卷触发。 |
| `volume_trigger.auto_dispatch_enabled` | boolean | 否 | 是否自动派发卷触发的运行。 |
| `volume_trigger.vars_json` | string | 否 | 卷触发时使用的变量 JSON 文本。 |
| `volume_trigger.max_concurrency` | integer | 否 | 卷触发运行的最大并发数。 |

其他可选字段可参见“单次运行”页签。

:::
::::

:::::
::::::
:::::::

## 成功响应

成功时返回 200。服务保存工作流定义，但不会自动启动作业。记录 `data.workflow.id`，用于后续查看、更新或启动。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "workflow": {
      "id": "wf-001",
      "name": "daily-import",
      "source_type": "manual_dsl",
      "execution_mode": "one_shot",
      "draft_id": "draft-001",
      "status": "ready"
    },
    "deployment": {
      "workflow_app_id": "wf-001",
      "workflow_def_id": "def-001",
      "workflow_version_id": "ver-001",
      "workflow_name": "daily-import",
      "version": 1,
      "execution_mode": "one_shot"
    }
  }
}
```

:::::
:::::{tab-item} 字段说明

::::{tab-set}
:::{tab-item} 通用字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data` | object | 响应数据。 |
| `workflow` | object | 已保存的工作流信息。 |
| `deployment` | object | 本次提交生成的部署信息；服务端提供时返回。 |

:::
:::{tab-item} 工作流信息

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 工作流 ID。 |
| `name` | string | 工作流名称。 |
| `source_type` | string | 工作流来源类型。 |
| `execution_mode` | string | 已保存的运行方式。 |
| `draft_id` | string | 工作流草稿 ID。 |
| `status` | string | 当前工作流状态。 |
| `cron_expression` | string | Cron 表达式；仅定时触发时返回。 |
| `candidate_id` | string | 候选 ID；存在候选版本时返回。 |

:::
:::{tab-item} 部署信息

下面表格展开响应示例中 `data` 下的 `deployment` 对象；每一行是该对象的一个字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `workflow_app_id` | string | 工作流应用 ID。 |
| `workflow_def_id` | string | 工作流定义 ID。 |
| `workflow_version_id` | string | 工作流版本 ID。 |
| `workflow_name` | string | 工作流名称。 |
| `version` | integer | 工作流版本号。 |
| `execution_mode` | string | 已发布的运行方式。 |
| `previous_workflow_version_id` | string | 上一工作流版本 ID；更新已有工作流版本时返回。 |
| `disabled_cron_task_ids` | array of string | 已停用的定时任务 ID；替换定时任务时返回。 |
| `volume_trigger` | object | 卷触发配置；卷触发时返回。 |
| `cron_task` | object | 定时任务信息；定时触发时返回。 |
| `dynamic_service` | object | 动态服务信息；动态服务时返回。 |

:::
:::{tab-item} 警告

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `warnings` | array of string | 部署警告；存在警告时返回。 |

:::
::::

:::::
::::::
:::::::

## 错误响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

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

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 错误代码。 |
| `msg` | string | 错误说明。 |
| `data` | null | 错误时为空。 |

:::::
::::::
:::::::

## 后续操作

记录 `data.workflow.id`。需要核对创建结果时，[查看工作流详情](get-workflow.md#请求示例)；准备立即执行时，[启动工作流作业](../workflow-jobs/start-workflow-job.md#请求示例)。