# 定时运行工作流

把已经验证的工作流配置为按 Cron 表达式定时运行，并通过工作流详情和工作流作业列表检查调度是否生效。

## 前提条件

- 已完成一次手动部署和运行，确认 DSL、运行输入和计算实例可用。
- 已保存工作流 ID。
- 已明确业务时区、运行频率、并发影响和失败后的处理方式。

不要用定时运行替代首次验证。错误的输入、权限或外部依赖会在每个调度周期重复失败；有写操作的工作流还可能产生重复副作用。

## 在部署时配置定时运行

部署请求中同时设置 `execution_mode` 和 `cron_expression`：

```json
{
  "workflow_id": "<WORKFLOW_ID>",
  "name": "scheduled-catalog-workflow",
  "dsl_yaml": "<WORKFLOW_DSL_YAML>",
  "execution_mode": "cron",
  "cron_expression": "CRON_TZ=Asia/Shanghai 0 */5 * * * *"
}
```

示例表达式只用于展示字段形态，不是推荐运行频率。时区和 Cron 语法应使用当前部署支持的格式；不要依赖服务器的隐含本地时区。

也可以通过以下接口更新已有工作流：

```bash
curl -X PATCH \
  "$PRODUCT_API_BASE_URL/workflow/v2/workflow-apps/$WORKFLOW_ID" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "execution_mode": "cron",
    "cron_expression": "CRON_TZ=Asia/Shanghai 0 */5 * * * *"
  }'
```

| 字段 | 类型 | 必需 | 说明 |
| --- | --- | --- | --- |
| `execution_mode` | string | 是 | 定时运行使用 `cron`。 |
| `cron_expression` | string | 是 | 调度表达式。应明确时区，并通过当前部署的校验。 |
| `default_values` | object | 视工作流而定 | 定时运行无法在每次触发前等待用户填写表单，因此必需运行输入应有稳定默认值或由算子自行取得。 |
| `compute_resource_id` | string | 视工作流而定 | 定时任务使用的默认计算实例。变更后应重新检查部署结果。 |

## 检查调度配置

更新或部署后读取工作流详情：

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

确认响应中的 `data.workflow.execution_mode`、`data.workflow.cron_expression`、状态和触发摘要符合预期。配置已保存不表示第一个调度周期已经运行。

第一个预期触发时间过去后，列出工作流作业：

```bash
curl --get \
  "$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 "Accept: application/json" \
  --data-urlencode "execution_mode=cron"
```

保存最新工作流作业 ID，并按[运行、查询与取消](run-query-cancel.md)读取状态和结果。Cron 工作流的一次工作流作业结束后可能回到等待下次调度的状态，不要只根据工作流顶层状态判断最近一次运行成功。

## 暂停和恢复

暂停工作流可阻止创建新的调度工作流作业：

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

恢复时将路径末尾改为 `/resume`。暂停不会取消已经开始的工作流作业；如需停止当前工作流作业，应先查询工作流作业 ID，再使用工作流作业取消接口。

## 常见问题

| 现象 | 先检查 | 下一步 |
| --- | --- | --- |
| 表达式校验失败 | 时区前缀、字段数量和当前部署支持的语法 | 从当前产品提供的调度配置重新取得表达式，不照搬其他 Cron 实现。 |
| 到时间没有运行 | 工作流状态、时区、暂停状态和工作流作业列表 | 先确认换算后的实际触发时间，再检查工作流详情和权限。 |
| 每次调度都失败 | 默认输入、计算实例和外部依赖 | 暂停新调度，修复并手动验证后再恢复。 |
| 暂停后仍看到运行中任务 | 工作流作业开始时间和工作流作业 ID | 暂停只影响新调度；按需单独取消已有工作流作业。 |

## 下一步

- [运行、查询与取消](run-query-cancel.md)
- [重新运行算子](rerun-nodes.md)