# 运行、查询与取消

启动已经部署的工作流，查询工作流作业状态和结果，并在仍允许取消时终止工作流作业。工作流运行是异步操作：创建工作流作业成功只表示平台已接受请求，不表示所有算子已经完成。

## 前提条件

- 已取得 Product API Base URL、个人访问令牌和目标工作区 ID。
- 已部署工作流，并从部署、列表或详情响应中保存工作流 ID。
- 当前身份具有在目标工作区运行和查看该工作流的权限。

Product API 使用 `X-API-Key` 传递个人访问令牌，并使用 `X-Workspace-ID` 指定工作区。不要把 Genesis Base URL、Genesis API Key 或 `Authorization: Bearer` 示例用于这些请求。

## 接口

以下路径相对于 Product API Base URL。Base URL 应包含当前环境要求的产品 API 前缀。

| 方法与路径 | 用途 |
| --- | --- |
| `POST /workflow/v2/workflow-apps/{workflow_id}/executions` | 创建一次工作流作业 |
| `GET /workflow/v2/workflow-apps/{workflow_id}/executions` | 列出指定工作流的工作流作业 |
| `GET /workflow/v2/workflow-apps/{workflow_id}/executions/{execution_id}` | 查询一次工作流作业的状态 |
| `GET /workflow/v2/workflow-apps/{workflow_id}/executions/{execution_id}/result` | 获取工作流作业结果和算子状态 |
| `POST /workflow/v2/workflow-apps/{workflow_id}/executions/{execution_id}/cancel` | 请求取消一次工作流作业 |

## 启动工作流

运行时输入放在 `values` 对象中，键使用工作流运行表单定义的字段 ID。不要将界面标签或自定义显示名称直接当作字段 ID。

```bash
curl -X POST \
  "$PRODUCT_API_BASE_URL/workflow/v2/workflow-apps/$WORKFLOW_ID/executions" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "values": {
      "<FIELD_ID>": "<VALUE>"
    }
  }'
```

| 字段 | 类型 | 必需 | 说明 |
| --- | --- | --- | --- |
| `values` | object | 否 | 运行时输入。对象键是运行表单中的字段 ID，值的类型应与该字段定义一致。没有运行时输入时可以省略。 |
| `trigger_now` | boolean | 否 | 是否立即触发本次运行。只在调用场景需要覆盖工作流触发方式时设置。 |
| `execution_mode` | string | 否 | 本次运行的模式。使用当前接口或工作流详情返回的受支持值。 |
| `compute_resource_id` | string | 否 | 本次运行使用的计算实例 ID。省略时使用工作流当前配置。 |

没有运行时输入时发送空对象 `{}`。成功响应的工作流作业信息位于 `data.workflow_run`：

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "workflow_run": {
      "execution_id": "<EXECUTION_ID>",
      "workflow_id": "<WORKFLOW_ID>",
      "status": "<STATUS>",
      "execution_mode": "<EXECUTION_MODE>",
      "available_actions": []
    }
  }
}
```

| 字段 | 说明 |
| --- | --- |
| `data.workflow_run.execution_id` | 本次工作流作业 ID。查询状态、结果或取消时继续使用该值。 |
| `data.workflow_run.workflow_id` | 运行的工作流 ID。 |
| `data.workflow_run.status` | 当前状态。后续仍需通过工作流作业详情确认终态。 |
| `data.workflow_run.execution_mode` | 本次运行实际使用的模式。 |
| `data.workflow_run.available_actions` | 当前状态允许的操作。取消、暂停或重试工作流作业前应重新读取。 |
| `data.workflow_run.error` | 创建工作流作业时已经返回的错误信息。仅在存在错误时返回；未返回不代表后续算子一定成功。 |

保存 `execution_id` 后再进入状态查询。网络超时或客户端未收到响应时，不要立即重复提交；先查询工作流作业列表，确认平台是否已经创建工作流作业。

## 查询状态

```bash
curl \
  "$PRODUCT_API_BASE_URL/workflow/v2/workflow-apps/$WORKFLOW_ID/executions/$EXECUTION_ID" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

工作流作业详情位于 `data.execution`。轮询时设置调用方自己的超时和最大次数；状态进入终态或超过等待预算后停止。不要仅根据 HTTP 请求成功判断工作流运行成功。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "execution": {
      "execution_id": "<EXECUTION_ID>",
      "workflow_id": "<WORKFLOW_ID>",
      "status": "<STATUS>",
      "execution_mode": "<EXECUTION_MODE>",
      "available_actions": [],
      "started_at": "<STARTED_AT>",
      "updated_at": "<UPDATED_AT>"
    }
  }
}
```

保存每次响应中的 `status` 和 `available_actions`。后者表示当前时刻允许的操作，不能作为下一次请求仍然可执行的保证。

需要获取输出和各算子状态时，调用结果接口：

```bash
curl \
  "$PRODUCT_API_BASE_URL/workflow/v2/workflow-apps/$WORKFLOW_ID/executions/$EXECUTION_ID/result" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

结果响应包含 `data.result.status`、`data.result.case_result`、`data.result.case_error`、`data.result.node_states` 和 `data.result.available_actions` 等字段：

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "result": {
      "execution_id": "<EXECUTION_ID>",
      "workflow_id": "<WORKFLOW_ID>",
      "status": "<STATUS>",
      "case_result": "<RESULT>",
      "node_states": [],
      "available_actions": []
    }
  }
}
```

`case_result` 和 `case_error` 只在服务端有对应内容时返回。只读取实际返回的字段；算子状态成功不替代业务侧对输出内容的校验。

## 取消工作流作业

先重新查询工作流作业详情，确认 `available_actions` 仍允许取消。取消会影响仍在运行的算子，但不能推断外部系统已经回滚之前产生的副作用。

```bash
curl -X POST \
  "$PRODUCT_API_BASE_URL/workflow/v2/workflow-apps/$WORKFLOW_ID/executions/$EXECUTION_ID/cancel" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Stopped by application request"}'
```

取消成功时，最新工作流作业信息位于 `data.execution`：

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "execution": {
      "execution_id": "<EXECUTION_ID>",
      "workflow_id": "<WORKFLOW_ID>",
      "status": "<STATUS>",
      "execution_mode": "<EXECUTION_MODE>",
      "available_actions": []
    }
  }
}
```

取消请求返回后，再查询工作流作业详情确认服务端状态。请求已接受不等于所有算子和外部副作用已经停止。

## 常见问题

| 现象 | 先检查 | 下一步 |
| --- | --- | --- |
| 找不到工作流 | `WORKFLOW_ID` 和 `X-Workspace-ID` | 从同一工作区的工作流列表重新取得 ID。 |
| 运行输入无效 | `values` 的字段 ID、必填值和类型 | 读取工作流详情中的运行表单定义后修正输入。 |
| 工作流作业长期没有进入终态 | 工作流作业详情中的状态、错误和算子信息 | 保存工作流作业 ID，停止无界轮询，并检查工作流作业详情。 |
| 无法取消 | 最新状态和 `available_actions` | 不要重复取消；重新读取状态，确认工作流作业是否已经结束或进入不可取消阶段。 |
| 返回失败但没有完整原因 | `result.case_error` 和 `result.node_states` | 查询失败算子详情，并保留工作流作业 ID 用于排查。 |

## 下一步

- [重新运行算子](rerun-nodes.md)
- [工作流产物、数据血缘与版本切换](artifacts-lineage-version-switching.md)
- [使用 Product SDK 管理工作流](../../../sdk/product-sdk/guides/workflows-workitems-lineage.md)
- [使用 MOI-CLI 管理工作流](../../../cli/tasks/workflows.md)