千问办公企业旗舰版开发者文档:立即执行计划任务。
认证方式见APP开发者文档 → 认证接入。
仅允许当前用户未删除且 active 的 cloud 计划。无请求体(或空对象),身份由IAM确定。写入一条 manual 执行后返回202,再由现有worker派发;不改变原 next_fire_at,也不代表Agent完成。重复 Idempotency-Key 在同一用户/计划/动作范围内返回相同执行,包括之后暂停或删除的已有执行;新的Key代表新的执行。每个执行新建会话,内部派发重试复用执行ID。暂停会阻止尚未开始交接的执行,删除会取消这些排队执行,已开始的会话继续。
401:缺少有效IAM入口身份;404:资源不存在或非本人;409:计划暂停或原执行尚未结束等状态冲突;422:参数、时间范围、请求体或幂等键无效;503:Session计划组件未启用。部分更新恢复已消费单次任务返回400。错误体沿用Session统一中间件。
202 表示执行已接收并等待派发,不表示沙箱或 Agent 已启动。
- 模块:计划任务
- 接口: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_id | string | 是 | 内部派发标识,不是会话查询地址 |
| error_message | string | 是 | 执行错误说明,无错误时为空字符串 |
| finished_at | string (date-time) | 否 | 执行结束时间,尚未结束时省略 |
| fired_at | string (date-time) | 否 | 该执行写入待派发队列的时间 |
| id | string | 是 | 本次执行 UUID。 |
| origin_execution_id | string | 否 | 重跑的原执行 ID;非重跑时省略 |
| origin_scheduled_at | string (date-time) | 否 | 重跑原执行的分区时间;非重跑时省略 |
| owner | object | 是 | 服务端记录的任务归属,调用方不可修改 |
| owner.org_id | string | 否 | 归属企业 ID,未设置时省略 |
| owner.team_id | string | 否 | 归属团队 ID,未设置时省略 |
| owner.user_id | string | 是 | IAM 用户 ID |
| run_type | string | 是 | 运行类型:scheduled 自动触发;manual 手动执行或重跑 |
| scheduled_at | string (date-time) | 是 | 执行对应的完整日期时间;重跑请求须使用原记录返回值 |
| status | string | 是 | 执行状态:fired、running、success、failed、cancelled、timeout |
| target | object | 是 | 会话运行配置;PATCH 提供时完整替换 |
| target.kind | string | 是 | trigger 为 at/cron/every;target 固定为 cloud_session |
| target.payload | object | 是 | 创建会话使用的运行参数 |
| target.payload.agent_id | string | 否 | 可选 Agent 标识 |
| target.payload.mode | string | 否 | 用户选择的运行档位 |
| target.payload.prompt | string | 是 | 提交给会话的任务内容 |
| target.payload.session_name | string | 否 | 会话名称,未命名时可为空 |
| target.payload.delivery_mode | string | 否 | 新建及更新仅允许省略或 isolated,每次触发新建会话;历史执行快照可能保留 bound |
| target.payload.session_id | string | 否 | 仅历史绑定快照可能返回;新建及更新必须省略 |
| target.payload.files | array | 否 | 附件引用数组,每项含必填 oss_id、可选 name/mime_type;通过现有文件服务复制至工作区 |
| task_id | string | 是 | 计划任务 ID |
| task_name_snapshot | string | 是 | 触发时保存的任务名称 |
| trigger | object | 是 | 触发规则;PATCH 提供时完整替换 |
| trigger.kind | string | 是 | trigger 为 at/cron/every;target 固定为 cloud_session |
| trigger.spec | object | 是 | 触发规则配置 |
| trigger.spec.expr | string | 否 | cron 五段表达式:分、时、日、月、周 |
| trigger.spec.fire | string (date-time) | 否 | at 单次触发时间;创建或修改触发规则时须为未来时间,历史快照可为过去时间 |
| trigger.spec.interval_ns | integer | 否 | every 必填;1分钟至365天,单位纳秒,存储规范化到毫秒 |
| trigger.spec.start_from | string (date-time) | 否 | every 必填;RFC3339 起算时间,可在过去;按固定间隔推进至未来 |
| trigger.spec.rest_day | object | 否 | 日历过滤配置;不支持启用 |
| trigger.spec.rest_day.enabled | boolean | 是 | 只允许 false |
| trigger.spec.rest_day.region | string | 否 | 日历区域保留字段;不参与调度 |
| trigger.spec.rest_day.skip_on | string | 否 | 日历规则保留字段;不参与调度 |
| trigger.spec.tz | string | 否 | cron 的 IANA 时区,省略时为 UTC |