Skip to main content

立即执行计划任务

千问办公企业旗舰版开发者文档:立即执行计划任务。

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

接口说明

仅允许当前用户未删除且 active 的 cloud 计划。无请求体(或空对象),身份由IAM确定。写入一条 manual 执行后返回202,再由现有worker派发;不改变原 next_fire_at,也不代表Agent完成。重复 Idempotency-Key 在同一用户/计划/动作范围内返回相同执行,包括之后暂停或删除的已有执行;新的Key代表新的执行。每个执行新建会话,内部派发重试复用执行ID。暂停会阻止尚未开始交接的执行,删除会取消这些排队执行,已开始的会话继续。 Idempotency-Key 必填,1–128个可见ASCII字符。同一个请求超时后复用原Key,避免新建重复会话。幂等身份持久化在既有执行流水中。

请求参数

字段类型必填说明
task_id (path)string (uuid)是计划任务 ID
Idempotency-Key (header)string是请求幂等键;同一操作重试复用原值

成功响应

HTTP 202

字段类型必填说明
dispatch_idstring是内部派发标识,不是会话查询地址
error_messagestring是执行错误说明,无错误时为空字符串
finished_atstring (date-time)否执行结束时间,尚未结束时省略
fired_atstring (date-time)否该执行写入待派发队列的时间
idstring是本次执行 UUID。
origin_execution_idstring否重跑的原执行 ID;非重跑时省略
origin_scheduled_atstring (date-time)否重跑原执行的分区时间;非重跑时省略
ownerobject是服务端记录的任务归属,调用方不可修改
owner.org_idstring否归属企业 ID,未设置时省略
owner.team_idstring否归属团队 ID,未设置时省略
owner.user_idstring是IAM 用户 ID
run_typestring是运行类型:scheduled 自动触发;manual 手动执行或重跑
scheduled_atstring (date-time)是执行对应的完整日期时间;重跑请求须使用原记录返回值
statusstring是执行状态:fired、running、success、failed、cancelled、timeout
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;通过现有文件服务复制至工作区
task_idstring是计划任务 ID
task_name_snapshotstring是触发时保存的任务名称
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

错误与边界

401:缺少有效IAM入口身份;404:资源不存在或非本人;409:计划暂停或原执行尚未结束等状态冲突;422:参数、时间范围、请求体或幂等键无效;503:Session计划组件未启用。部分更新恢复已消费单次任务返回400。错误体沿用Session统一中间件。 202 表示执行已接收并等待派发,不表示沙箱或 Agent 已启动。