Skip to main content

修改计划任务

千问办公企业旗舰版开发者文档:修改计划任务。

认证方式见APP开发者文档 → 认证接入。
  • 模块:计划任务
  • 接口:PATCH/api/openapi/app/v1/scheduler/tasks/{task_id}
  • operationId:update-scheduled-task

接口说明

按需传入 name、description、trigger、target、status,至少一项。trigger/target 整体替换,不做嵌套合并;拒绝 null、未知字段、owner/user_id、Desktop目标及启用日历过滤。只改名称或目标不改变 next_fire_at;触发规则确实变化时重新计算未来触发时间。修改和领取在同一计划行锁下串行,已生成的执行快照保持不变。已消费的单次计划改名称不会再次执行,恢复已消费计划返回400;明确设置新的未来 at 或 cron 可安排新的触发。

请求参数

字段类型必填说明
task_id (path)string (uuid)是计划任务 ID

请求体

字段类型必填说明
descriptionstring否任务说明,可传空字符串清空
delete_after_runboolean否默认false;仅at支持;自动计划执行成功后软删除计划,保留流水与会话
namestring否任务名称,去首尾空白后 1–100 个字符
statusstring否计划状态:active(启用)、paused(暂停)
targetobject否会话运行配置;PATCH 提供时完整替换
target.kindstring是trigger 为 at/cron/every;target 固定为 cloud_session
target.payloadobject是创建会话使用的运行参数
target.payload.agent_idstring否可选 Agent 标识
target.payload.modestring否用户选择的运行档位
target.payload.promptstring是提交给会话的任务内容
target.payload.session_namestring否会话名称,未命名时可为空
target.payload.delivery_modestring否新建及更新仅允许省略或 isolated,每次触发新建会话;历史执行快照可能保留 bound
target.payload.session_idstring否仅历史绑定快照可能返回;新建及更新必须省略
target.payload.filesarray否附件引用数组,每项含必填 oss_id、可选 name/mime_type;通过现有文件服务复制至工作区
triggerobject否触发规则;PATCH 提供时完整替换
trigger.kindstring是trigger 为 at/cron/every;target 固定为 cloud_session
trigger.specobject是触发规则配置
trigger.spec.exprstring否cron 五段表达式:分、时、日、月、周
trigger.spec.firestring (date-time)否at 单次触发时间;创建或修改触发规则时须为未来时间,历史快照可为过去时间
trigger.spec.interval_nsinteger否every 必填;1分钟至365天,单位纳秒,存储规范化到毫秒
trigger.spec.start_fromstring (date-time)否every 必填;RFC3339 起算时间,可在过去;按固定间隔推进至未来
trigger.spec.rest_dayobject否日历过滤配置;不支持启用
trigger.spec.rest_day.enabledboolean是只允许 false
trigger.spec.rest_day.regionstring否日历区域保留字段;不参与调度
trigger.spec.rest_day.skip_onstring否日历规则保留字段;不参与调度
trigger.spec.tzstring否cron 的 IANA 时区,省略时为 UTC

成功响应

HTTP 200

字段类型必填说明
created_atstring (date-time)是任务创建时间
descriptionstring是任务说明,可传空字符串清空
delete_after_runboolean是默认false;仅at支持;自动计划执行成功后软删除计划,保留流水与会话
idstring是计划任务 UUID。
namestring是任务名称,去首尾空白后 1–100 个字符
next_fire_atstring/null (date-time)是下一次自动触发的完整时间;单次已消费时为空
ownerobject是服务端记录的任务归属,调用方不可修改
owner.org_idstring否归属企业 ID,未设置时省略
owner.team_idstring否归属团队 ID,未设置时省略
owner.user_idstring是IAM 用户 ID
schedule_bystring是当前固定 cloud
statusstring是计划状态:active(启用)、paused(暂停)
targetobject是会话运行配置;PATCH 提供时完整替换
target.kindstring是trigger 为 at/cron/every;target 固定为 cloud_session
target.payloadobject是创建会话使用的运行参数
target.payload.agent_idstring否可选 Agent 标识
target.payload.modestring否用户选择的运行档位
target.payload.promptstring是提交给会话的任务内容
target.payload.session_namestring否会话名称,未命名时可为空
target.payload.delivery_modestring否新建及更新仅允许省略或 isolated,每次触发新建会话;历史执行快照可能保留 bound
target.payload.session_idstring否仅历史绑定快照可能返回;新建及更新必须省略
target.payload.filesarray否附件引用数组,每项含必填 oss_id、可选 name/mime_type;通过现有文件服务复制至工作区
triggerobject是触发规则;PATCH 提供时完整替换
trigger.kindstring是trigger 为 at/cron/every;target 固定为 cloud_session
trigger.specobject是触发规则配置
trigger.spec.exprstring否cron 五段表达式:分、时、日、月、周
trigger.spec.firestring (date-time)否at 单次触发时间;创建或修改触发规则时须为未来时间,历史快照可为过去时间
trigger.spec.interval_nsinteger否every 必填;1分钟至365天,单位纳秒,存储规范化到毫秒
trigger.spec.start_fromstring (date-time)否every 必填;RFC3339 起算时间,可在过去;按固定间隔推进至未来
trigger.spec.rest_dayobject否日历过滤配置;不支持启用
trigger.spec.rest_day.enabledboolean是只允许 false
trigger.spec.rest_day.regionstring否日历区域保留字段;不参与调度
trigger.spec.rest_day.skip_onstring否日历规则保留字段;不参与调度
trigger.spec.tzstring否cron 的 IANA 时区,省略时为 UTC
updated_atstring (date-time)是任务最后更新时间

错误与边界

401:缺少有效IAM入口身份;404:资源不存在或非本人;409:计划暂停或原执行尚未结束等状态冲突;422:参数、时间范围、请求体或幂等键无效;503:Session计划组件未启用。部分更新恢复已消费单次任务返回400。错误体沿用Session统一中间件。 202 表示执行已接收并等待派发,不表示沙箱或 Agent 已启动。 新增字段规则与创建计划相同:every 必须同时提供 interval_ns/start_from;仅支持独立会话执行;delete_after_run 仅用于 at。trigger/target 仍完整替换,未提供的顶层字段保持原值。将删除标记为 true 的 at 改为周期任务时,须同时设置 delete_after_run=false。