> ## Documentation Index > Fetch the complete documentation index at: https://docs.qoder.com/llms.txt > Use this file to discover all available pages before exploring further. # 更新 Schedule > 更新 Forward Schedule 配置。 `POST /api/v1/forward/schedules/{schedule_id}` 使用 merge-patch 语义：请求体中出现的字段会被更新，未出现字段保持不变。 ## 请求头 | Header | 是否必填 | 说明 | | --------------- | ---- | ------------------ | | Authorization | 是 | `Bearer ` | | Content-Type | 是 | `application/json` | | Idempotency-Key | 否 | 有副作用请求可选的幂等键。 | ## 路径参数 | 参数 | 类型 | 是否必填 | 说明 | | ------------ | ------ | ---- | -------------------- | | schedule\_id | string | 是 | Forward Schedule ID。 | ## 请求体参数 | 参数 | 类型 | 是否必填 | 说明 | | --------------- | -------------- | ---- | ------------------------------------ | | name | string | 否 | 新的 Schedule 名称。 | | description | string | 否 | 新的 Schedule 描述。 | | template\_id | string | 否 | 新的 Forward Template ID。 | | initial\_events | array | 否 | 替换初始事件列表。 | | execution | object | 否 | 合并更新执行策略。 | | trigger\_policy | object \| null | 否 | 更新触发策略；`null` 表示改为 manual。 | | environment\_id | string | 否 | 新的执行环境。 | | metadata | object | 否 | 合并更新 metadata；value 为 `null` 删除 key。 | ## 触发策略 `trigger_policy` 是按 `type` 分发的对象。创建和更新请求只接收配置字段：`type`、`expression`、`timezone`。更新时传 `null` 表示改为 `{"type":"manual"}`。`upcoming_runs_at`、`last_run_at` 是服务端计算出的响应字段。 | 字段 | 类型 | 是否必填 | 说明 | | ------------------ | -------------- | ---- | ---------------------------------------------------------------------------------------- | | type | string | 是 | `cron`、`once`、`interval` 或 `manual`。 | | expression | string | 条件必填 | 触发表达式；`cron`、`once`、`interval` 必填，`manual` 不需要。 | | timezone | string | 条件必填 | IANA timezone，例如 `Asia/Shanghai`；`cron` 必填，`once` 在表达式不带时区时必填，`interval` 和 `manual` 可省略。 | | upcoming\_runs\_at | array | 响应返回 | 后续触发时间，UTC ISO 8601。当前实现返回 `[]` 或最多一个下一次计划触发时间。 | | last\_run\_at | string \| null | 响应返回 | 最近一次触发时间。 | | type | 创建/更新入参 | 说明 | | ---------- | --------------------------------- | ------------------------------------------------ | | `cron` | `type`、`expression`、`timezone` | 使用 5 字段 cron 表达式按指定 IANA timezone 重复触发。 | | `once` | `type`、`expression`、可选 `timezone` | 按 ISO 8601 时间触发一次；表达式不带 offset 时必须提供 `timezone`。 | | `interval` | `type`、`expression` | 按 ISO 8601 duration 重复触发，例如 `PT15M`。 | | `manual` | `type` | 不自动触发，只能通过 Run Schedule 接口手动执行。 | | type | expression 格式 | 示例 | 说明 | | ---------- | ----------------- | ---------------------------------------------- | -------------------------- | | `cron` | 标准 5 字段 cron | `0 9 * * *` | 分钟级日历规则；不支持秒字段和 6 字段 cron。 | | `once` | ISO 8601 绝对时间 | `2026-06-23T09:00:00` 或 `2026-06-23T01:00:00Z` | 目标时间必须至少晚于服务端当前时间 1 分钟。 | | `interval` | ISO 8601 duration | `PT15M`、`PT1H`、`P1D` | 固定间隔触发，最小粒度 1 分钟。 | | `manual` | 省略或空字符串 | - | 不产生计划触发时间。 | ## 执行策略 `execution` 使用合并更新语义，未出现的字段保持原值。 | 字段 | 类型 | 默认值 | 说明 | | --------------------- | ------- | ------------- | ------------------------------------------------ | | session\_mode | string | `new_session` | Session 使用方式，取值 `new_session` 或 `reuse_session`。 | | max\_concurrent\_runs | integer | 1 | 同一个 Schedule 最大并发 Run 数。 | | max\_attempts | integer | 1 | 预留字段；当前实现只记录、校验和回显，单个 Run 仍只执行一次。 | | timeout\_ms | integer | 300000 | 单次尝试超时时间。 | | session\_mode | 说明 | | --------------- | -------------------------------------------------------------------------- | | `new_session` | 每次触发都创建新的执行 Session，不延续历史上下文。 | | `reuse_session` | Forward 为该 Schedule 管理一个固定执行 Session，并在多次触发间持续使用；调用方不能指定任意已有 `session_id`。 | ## 示例请求 ```bash theme={null} curl -s -X POST 'https://api.qoder.com/api/v1/forward/schedules/sched_019f00112233445566778899aabbccdd' \ -H "Authorization: Bearer $QODER_PAT" \ -H "Content-Type: application/json" \ -d '{ "name": "Weekday tech brief", "trigger_policy": { "type": "cron", "expression": "0 9 * * 1-5", "timezone": "Asia/Shanghai" } }' ``` ## 示例响应 **HTTP 200 OK** ```json theme={null} { "id": "sched_019f00112233445566778899aabbccdd", "identity_id": "idn_019eabc123", "template_id": "tmpl_support", "name": "Weekday tech brief", "description": "Generate a daily technology news summary", "status": "active", "initial_events": [ { "type": "user.message", "content": "Summarize current technology news in five bullet points." } ], "execution": { "session_mode": "new_session", "max_concurrent_runs": 1, "max_attempts": 1, "timeout_ms": 300000 }, "trigger_policy": { "type": "cron", "expression": "0 9 * * 1-5", "timezone": "Asia/Shanghai", "upcoming_runs_at": [ "2026-06-23T01:00:00Z" ] }, "environment_id": "env_019e64e01a137caf953ac2ac7b42ec5c", "sinks": [], "metadata": {}, "created_at": "2026-06-22T10:00:00Z", "updated_at": "2026-06-22T10:30:00Z" } ``` ## 响应字段 | 字段 | 类型 | 说明 | | --- | ------ | ----------------- | | 返回值 | object | 更新后的 Schedule 对象。 | ## 错误 | HTTP | Type | Code | 触发条件 | | ---- | ----------------------- | ------------------------- | ------------------ | | 400 | `invalid_request_error` | `invalid_trigger_policy` | 触发策略不合法。 | | 400 | `invalid_request_error` | `unsupported_sinks_input` | 请求体包含不支持的 `sinks`。 | | 404 | `not_found_error` | `schedule_not_found` | Schedule 不存在。 | | 409 | `invalid_request_error` | `schedule_archived` | Schedule 已归档。 | | 401 | `authentication_error` | `authentication_required` | PAT 无效或已过期。 | ## 注意事项 * HTTP 更新请求不支持更新 `sinks`。 * `reuse_session` 表示 Forward 为该 Schedule 管理固定执行 Session，调用方不能指定任意已有 Session。 ## 相关