运行、查询与取消

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

前提条件

  • 已取得 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。

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：

{
  "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 后再进入状态查询。网络超时或客户端未收到响应时，不要立即重复提交；先查询工作流作业列表，确认平台是否已经创建工作流作业。

查询状态

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 请求成功判断工作流运行成功。

{
  "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。后者表示当前时刻允许的操作，不能作为下一次请求仍然可执行的保证。

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

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 等字段：

{
  "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 仍允许取消。取消会影响仍在运行的算子，但不能推断外部系统已经回滚之前产生的副作用。

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：

{
  "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 用于排查。

下一步

最后更新于