Skip to main content

创建计划任务

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

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

接口说明

创建仅保存计划,不代表Agent已执行或完成。每次新创建请求产生新任务;当前接口不提供创建幂等键,超时后不要直接重复创建。 接口只消费可信入口的当前用户;需启用Session计划组件且依赖就绪。支持单次与周期计划。

请求头

参数/字段位置类型必填说明
Content-TypeheaderstringJSON body时application/json

请求参数

参数/字段位置类型必填说明
————无额外参数

请求体

参数/字段位置类型必填说明
descriptionbodystring否任务描述
delete_after_runbodyboolean否默认false;仅at支持;自动计划执行成功后软删除计划,保留流水与会话
namebodystring是去首尾空白后1–100个字符
ownerbody任意JSON否旧字段兼容接收但忽略;Owner由IAM身份派生
schedule_bybodystring否仅cloud,创建默认cloud;值:cloud
statusbodystring否active/paused,创建默认active;未知值拒绝;值:active, paused
targetbodyobject是对象结构;字段及条件列于下方 target.* 行。
target.kindbodystring是trigger仅at/cron/every,target仅cloud_session;值:cloud_session
target.payloadbodyobject是对象结构;字段及条件列于下方 target.payload.* 行。
target.payload.agent_idbodystring否可选非零UUID,作为已有Agent配置选择
target.payload.modebodystring否档位选择,最多128字节;不暴露海外模型ID
target.payload.promptbodystring是文本Prompt不能为空或仅空白
target.payload.session_namebodystring否可选,最多255个字符
target.payload.delivery_modebodystring否新建及更新仅允许省略或 isolated,每次触发新建会话;历史执行快照可能保留 bound
target.payload.session_idbodystring否仅历史绑定快照可能返回;新建及更新必须省略
target.payload.filesbodyarray否附件引用数组,每项含必填 oss_id、可选 name/mime_type;通过现有文件服务复制至工作区
triggerbodyobject是对象结构;字段及条件列于下方 trigger.* 行。
trigger.kindbodystring是trigger仅at/cron/every,target仅cloud_session;值:at, cron, every
trigger.specbodyobject是对象结构;字段及条件列于下方 trigger.spec.* 行。
trigger.spec.exprbodystring否仅cron必填;标准5字段,不接受描述符或秒字段
trigger.spec.firebodystring (date-time)否仅at必填;未来RFC3339时间,规范化为UTC毫秒
trigger.spec.interval_nsbodyinteger否every 必填;1分钟至365天,单位纳秒,存储规范化到毫秒
trigger.spec.start_frombodystring (date-time)否every 必填;RFC3339 起算时间,可在过去;按固定间隔推进至未来
trigger.spec.rest_daybodyobject否对象结构;字段及条件列于下方 trigger.spec.rest_day.* 行。
trigger.spec.rest_day.enabledbodyboolean是rest_day只能false;true拒绝;值:false
trigger.spec.rest_day.regionbodystring否保留的地区字段,本期不参与调度。
trigger.spec.rest_day.skip_onbodystring否保留的日历策略字段,本期不参与调度。
trigger.spec.tzbodystring否仅cron可用;IANA时区,省略默认UTC
嵌套字段必填性以父对象存在为前提,at/cron/every条件规则以以下示例和约束为准。未知字段和多个JSON对象拒绝;不要发送owner作为授权依据。

单次与周期示例

单次示例的fire必须替换为实际未来时间。at不额外加秒位错峰,不允许同时传expr或tz。
{"name":"单次汇总","trigger":{"kind":"at","spec":{"fire":"2030-01-01T09:00:00+08:00"}},"target":{"kind":"cloud_session","payload":{"prompt":"汇总待办"}}}
按天示例;按周一将expr改为0 9 * * 1,按每月15日改为0 9 15 * *。cron不同时传fire。
{"name":"每日汇总","trigger":{"kind":"cron","spec":{"expr":"0 9 * * *","tz":"Asia/Shanghai"}},"target":{"kind":"cloud_session","payload":{"prompt":"汇总待办","mode":"pro"}},"status":"active","schedule_by":"cloud"}
Cron复用任务UUID的FNV-1a哈希模60得到固定0–59秒偏移,分散在指定分钟内;重启和副本变化不重新抽签。next_fire_at包含日期、时间、时区对应的完整时刻,不只存时分秒。停机后补执行一次已到期记录,再推进至下一个未来时间;同次执行重试复用执行身份,不会为每次重试创建新会话。每个新触发实例创建新会话;新建或更新不接受 bound。 不启用节假日/调休过滤,rest_day省略或enabled=false;true拒绝,false规范化后不参与计算。连接器、Harness覆盖及子Agent字段仍不支持,不静默丢弃。修改已有计划使用 PATCH /api/openapi/app/v1/scheduler/tasks/{task_id}。

成功响应

HTTP 201

参数/字段位置类型必填说明
created_atresponsestring (date-time)是计划创建时间,RFC3339。
descriptionresponsestring是用户填写的计划描述;未填写时为空字符串。
delete_after_runresponseboolean是默认false;仅at支持;自动计划执行成功后软删除计划,保留流水与会话
idresponsestring是计划任务 UUID。
nameresponsestring是去首尾空白后1–100个字符
next_fire_atresponsestring / null (date-time)是完整UTC日期时间;无后续触发时可为null
ownerresponseobject是服务端保存的归属身份;不由调用方指定
owner.org_idresponsestring否归属企业 UUID,未设置时省略。
owner.team_idresponsestring否归属团队 UUID,未设置时省略。
owner.user_idresponsestring是归属 IAM 用户 UUID。
schedule_byresponsestring是仅cloud,创建默认cloud
statusresponsestring是active/paused,创建默认active;未知值拒绝
targetresponseobject是本记录保存的执行目标配置,子字段见下。
target.kindresponsestring是trigger仅at/cron/every,target仅cloud_session;值:cloud_session
target.payloadresponseobject是会话创建所用的运行参数;执行记录中为触发时快照。
target.payload.agent_idresponsestring否可选非零UUID,作为已有Agent配置选择
target.payload.moderesponsestring否档位选择,最多128字节;不暴露海外模型ID
target.payload.promptresponsestring是文本Prompt不能为空或仅空白
target.payload.session_nameresponsestring否可选,最多255个字符
target.payload.delivery_moderesponsestring否新建及更新仅允许省略或 isolated,每次触发新建会话;历史执行快照可能保留 bound
target.payload.session_idresponsestring否仅历史绑定快照可能返回;新建及更新必须省略
target.payload.filesresponsearray否附件引用数组,每项含必填 oss_id、可选 name/mime_type;通过现有文件服务复制至工作区
triggerresponseobject是本记录保存的触发规则,子字段见下。
trigger.kindresponsestring是trigger仅at/cron/every,target仅cloud_session;值:at, cron, every
trigger.specresponseobject是与 trigger.kind 对应的规则参数。
trigger.spec.exprresponsestring否仅cron必填;标准5字段,不接受描述符或秒字段
trigger.spec.fireresponsestring (date-time)否仅at必填;保存的RFC3339触发时刻(UTC毫秒),执行后可为过去时间
trigger.spec.interval_nsresponseinteger否every 必填;1分钟至365天,单位纳秒,存储规范化到毫秒
trigger.spec.start_fromresponsestring (date-time)否every 必填;RFC3339 起算时间,可在过去;按固定间隔推进至未来
trigger.spec.rest_dayresponseobject否保留的日历策略结构;本期不启用日历过滤。
trigger.spec.rest_day.enabledresponseboolean是rest_day只能false;true拒绝;值:false
trigger.spec.rest_day.regionresponsestring否保留的地区字段;本期不参与调度。
trigger.spec.rest_day.skip_onresponsestring否保留的跳过日期策略字段;本期不参与调度。
trigger.spec.tzresponsestring否仅cron可用;IANA时区,省略默认UTC
updated_atresponsestring (date-time)是计划最近更新时间,RFC3339。

拒绝与排查

HTTP错误语义
401缺少或无效的可信IAM用户入口身份;不能通过切换身份参数重试
404任务不存在或非当前用户;除执行流水外,软删除任务也不可读取
422无效任务ID、分页、请求体、触发规则或目标参数
503Session计划组件未启用或所需服务不可用
当前恢复已消费单次任务的拒绝是400 OPERATION_NOT_ALLOWED;不要把它当作任务成功恢复。错误体沿用Session现有运行时中间件,不套用管理后台错误码或生成器默认problem+json字段。保存trace_id排查,移除用户凭据。

固定间隔与独立会话

{"name":"每90分钟检查","trigger":{"kind":"every","spec":{"interval_ns":5400000000000,"start_from":"2030-01-01T09:00:00+08:00"}},"target":{"kind":"cloud_session","payload":{"prompt":"检查进度","delivery_mode":"isolated"}}}
every 按起算时间加整数个间隔计算,下一时刻严格晚于当前时间;不加 Cron 秒位错峰,也不启用日历过滤。起算时间未来时,第一次触发就是起算时间;停机补执行一次,再按原起算时间推进。 存量任务中的旧绑定配置在读取时规范化为独立会话;历史执行快照仍可能保留原绑定字段,不代表当前允许创建绑定任务。 delete_after_run=true 只允许 at。自动计划执行成功后软删除计划;失败、取消、仅派发成功及手动 run-once 均不触发删除。执行期间重设了触发时间的计划不会被旧执行删除。 附件是文件引用,不是上传接口。新建会话沿用现有结构化 Prompt 复制与失败保留原URI的行为。真实可读性及后台凭据仍依赖文件服务联调。