千问办公企业旗舰版开发者文档:使用指南。
计划任务使用指南
认证方式见APP开发者文档 → 认证接入。
HTTP 操作
接口前缀为 /api/openapi/app/v1/scheduler,操作要求有效 IAM 用户身份及资源归属校验。
| Method | 相对路径 | 成功响应 |
|---|---|---|
| POST | /tasks | 201,Task对象 |
| GET | /tasks | 200,items、limit、offset |
| GET | /tasks/{task_id} | 200,Task对象 |
| POST | /tasks/{task_id}/pause | 204,无正文 |
| POST | /tasks/{task_id}/resume | 204,无正文 |
| DELETE | /tasks/{task_id} | 204,无正文 |
| GET | /tasks/{task_id}/executions | 200,items、limit、offset |
| PATCH | /tasks/{task_id} | 200,Task对象 |
| POST | /tasks/{task_id}/run-once | 202,Execution对象 |
| POST | /executions/{execution_id}/rerun | 202,Execution对象 |
| GET | /executions | 200,items、limit、offset |
| GET | /tasks/{task_id}/sessions | 200,items、limit、offset |
| GET | /session-groups | 200,items、limit、offset |
| GET | /session-groups/{task_id}/sessions | 200,items、limit、offset |
| DELETE | /session-groups/{task_id} | 200,deleted_count |
创建字段与返回
| 字段 | 必填 | 说明 |
|---|---|---|
| name | 是 | 任务名称,1~100字符 |
| description | 否 | 任务说明 |
| trigger | 是 | at、cron或every规则,见下表 |
| target | 是 | kind 固定 cloud_session;prompt 非空;mode 最多 128 字节;agent_id 为可选非零 UUID;session_name 最多 255 个字符 |
| status | 否 | active或paused |
| schedule_by | 否 | 只支持cloud |
任务规则
| 规则 | trigger.kind | trigger.spec |
|---|---|---|
| 单次 | at | fire:未来 RFC3339 日期时间 |
| 每天 | cron | 五段 expr,例如 0 9 * * *,tz 使用 IANA 时区 |
| 每周 | cron | 例如 0 9 * * 1 |
| 每月 | cron | 例如 0 9 1 * * |
Asia/Shanghai。支持单次、按天、按周和按月规则。
rest_day 不设置或 Enabled=false,不过滤节假日和调休日。
创建示例
全生命周期
创建后保存完整的下一次触发日期时间。多副本通过 PostgreSQL 原子领取到期任务,领取成功的副本派发执行,其他副本继续扫描其他任务。
isolated 每次触发创建新会话,同一次执行重试复用原会话;当前新建和更新不接受 bound 或 session_id。创建计划任务代表用户授权该计划执行;后续按正常会话流程启动和执行,运行阻塞时反映到任务和会话状态。
可查询任务与执行流水,暂停、恢复或删除任务。删除或暂停不会自动删除既有执行会话与历史。
主动错峰与补执行
按天、周、月的 Cron 任务采用固定 0~59 秒错峰:设定 09:00 的任务可在当日 09:00:37 到期,37 秒只是该任务固定的秒偏移。单次 at 保持原定时间,every 按起算时间与间隔计算,不叠加错峰。
到期条件是完整 next_fire_at 不晚于当前时间,不要求扫描恰好命中第37秒。停机错过多个时间点时,恢复后补执行一次已到期记录,再计算下一个未来时间,避免集中补跑。
空闲扫描间隔5秒,有到期任务时短间歇后继续排空;Web集群启动额度复用Biz的配置值,与Desktop分别计数。
逐接口文档
目录提供十五篇接口页,覆盖任务管理、配置修改、立即执行、执行重跑、执行记录与会话分组查询。恢复已消费单次任务当前返回400 OPERATION_NOT_ALLOWED,不是重新安排已发生的那次执行。暂停/删除不取消已开始的Session交接,执行流水仍按原Owner读取。
手动执行与重跑
立即执行与历史重跑必须携带 Idempotency-Key,不改变计划的下次触发时间。重跑使用原执行快照,要求源执行已结束且任务处于 active 状态、未删除。重复提交相同幂等键返回同一执行。
清理计划会话
DELETE /api/openapi/app/v1/scheduler/session-groups/{task_id} 清理当前用户该计划的未删除主会话,复用普通会话资源释放流程。它不暂停或删除计划,也不删除执行流水;若希望停止未来触发,先暂停或删除计划。清理可能部分成功后报错,重试只处理剩余会话。已软删除计划的保留会话仍可清理。
扩展参数
- every:interval_ns 为 1 分钟至 365 天的纳秒数,start_from 为 RFC3339 起算时间;错过多次时补一次,随后仍沿用原起算时间。
- delivery_mode:省略或 isolated,每次新建会话;新建和更新必须省略 session_id。存量绑定任务读取时规范化为独立执行,历史执行快照可能保留 bound,仅作历史记录。
- files:附件引用包含 oss_id、可选 name/mime_type,复用文件服务复制链路;文件访问依赖实际服务权限。
- delete_after_run:默认 false,at 自动执行成功后软删除计划,保留执行记录及会话;手动执行不消费计划。
- 列表支持 status=active/paused、sort=created_asc/created_desc;默认降序;CLI --all 自动执行 limit/offset 翻页。