Skip to main content

使用指南

千问办公企业旗舰版开发者文档:使用指南。

计划任务使用指南

认证方式见APP开发者文档 → 认证接入。

HTTP 操作

接口前缀为 /api/openapi/app/v1/scheduler,操作要求有效 IAM 用户身份及资源归属校验。
Method相对路径成功响应
POST/tasks201,Task对象
GET/tasks200,items、limit、offset
GET/tasks/{task_id}200,Task对象
POST/tasks/{task_id}/pause204,无正文
POST/tasks/{task_id}/resume204,无正文
DELETE/tasks/{task_id}204,无正文
GET/tasks/{task_id}/executions200,items、limit、offset
PATCH/tasks/{task_id}200,Task对象
POST/tasks/{task_id}/run-once202,Execution对象
POST/executions/{execution_id}/rerun202,Execution对象
GET/executions200,items、limit、offset
GET/tasks/{task_id}/sessions200,items、limit、offset
GET/session-groups200,items、limit、offset
GET/session-groups/{task_id}/sessions200,items、limit、offset
DELETE/session-groups/{task_id}200,deleted_count
列表与执行流水使用offset分页:limit默认20,范围1~100;offset默认0,必须非负。task_id为UUID且任务需属于当前用户。

创建字段与返回

字段必填说明
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
不要发送owner作为授权依据。返回Task含id、owner、name、description、trigger、target、status、schedule_by、next_fire_at、created_at、updated_at;next_fire_at为完整日期时间,未安排后续触发时可为空。 已触发的单次任务不能通过resume重复安排执行。暂停、恢复、删除前均检查任务归属;依赖错误不意味着任务或执行会话已删除。

任务规则

规则trigger.kindtrigger.spec
单次atfire:未来 RFC3339 日期时间
每天cron五段 expr,例如 0 9 * * *,tz 使用 IANA 时区
每周cron例如 0 9 * * 1
每月cron例如 0 9 1 * *
at、cron、every 各自字段不混用。Cron 未指定 tz 时沿用 UTC;国内业务应显式传 Asia/Shanghai。支持单次、按天、按周和按月规则。 rest_day 不设置或 Enabled=false,不过滤节假日和调休日。

创建示例

{
  "name": "每日摘要",
  "trigger": {"kind": "cron", "spec": {"expr": "0 9 * * *", "tz": "Asia/Shanghai"}},
  "target": {"kind": "cloud_session", "payload": {"prompt": "生成当天摘要"}}
}
目标采用 cloud_session。模式选择通过 payload.mode 保存档位;任务 owner 不从请求体取得。

全生命周期

创建后保存完整的下一次触发日期时间。多副本通过 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 翻页。
variant、子 Agent、cursor 兼容仍不支持,日历过滤保持关闭。