Scheduler

Scheduler 是注册到某个 Space 中、用于重复执行的定时任务。将一个 Script 与运行时刻绑定后，每到该时刻，服务器就会执行该 Script。例如，在服装网店中，若想每天运行一次查找库存为 0 的商品并调用供应商订货窗口的 Script，就为该 Script 创建一个 Scheduler。

Scheduler 是由 CMA 管理的 Space 子资源，路径以 /spaces/{spaceId}/schedulers 为基准。它没有发布（publish）概念，也没有 sys.version。创建后会立即进入调度，修改时不需要版本请求头。不过有两点与其他资源不同。要执行的 Script 在创建后无法更改，而且创建或修改它时，除了 Space 设置权限外，还需要单独具备该 Script 的执行权限。执行结果会以 SchedulerLog 形式保留，成功的执行在 1 小时后消失，失败的执行在 3 天后消失。

资源结构

以下是创建 Scheduler 时的响应。sys 中包含标识符和引用，主体中包含名称、运行时刻和是否开启。

{
  "sys": {
    "id": "7kQm2ZbTn4Rc9WvXpL3dHsY6fJ",
    "type": "Scheduler",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "script": { "sys": { "id": "3trmXRMKq7bd0Prbef1NcZ", "type": "Refer", "targetType": "Script" } },
    "createdBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-08-26T01:20:07.442Z",
    "updatedBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-08-26T01:20:07.442Z"
  },
  "name": "库存订货",
  "cronExpression": "0 0 * * *",
  "activated": true
}

主要键：

• sys.id：Scheduler 的唯一标识符。用于单条查询、修改、删除路径中的 {schedulerId}。
• sys.script：该 Scheduler 要执行的 Script。只能在创建时指定，之后无法更改。 若要运行其他 Script，请新建一个 Scheduler。
• name：在控制台中显示的标签。不用于执行。
• cronExpression：运行时刻。由五个字段（分、时、日、月、星期）组成，并按 UTC 解释。参见下方 编写运行时刻。
• activated：是否开启。为 false 时，保存的记录仍然保留，只是不会执行。

没有 sys.version。修改请求中不发送 X-Weegloo-Version 请求头。

系统属性 (sys)

space、script、createdBy、updatedBy 以 Refer 形式（{ "sys": { "id", "type": "Refer", "targetType" } }）表示。

主体属性：

编写运行时刻

五个字段从左到右按 分、时、日、月、星期 的顺序书写。没有秒字段。

可以使用 *（全部）、,（列表）、-（范围）、/（间隔），星期可用数字（07，0 和 7 表示星期日）或名称（SUNSAT）表示。

所有值都按 UTC 解释。 需要自行计算与本地时间的时差并填入，对于指定了日期或星期几的时刻，实际运行的日期可能会因该时差而改变。

从不触发的值不会被保存。 像 0 0 30 2 *（2 月 30 日）这样，即使格式正确，但指向永远不会到来的日期时，会被拒绝。

状态与约束

关于行为和权限的规则：

• 需要同时具备两种权限。 角色（SpaceRole）的 settings 中必须有 SETTING_SCHEDULER，此外还必须单独拥有对目标 Script 的 Execute 权限。不仅创建时，修改和部分修改时也会检查。 因为更改运行时刻就是在决定何时执行该 Script，而将关闭状态改为开启则是在启动执行。只要缺少其中任意一项，请求就会被拒绝。
• 执行以 sys.createdBy 的权限进行。 Script 中的 :self 过滤器也会解析为该用户。即使修改者不同，执行主体也不会改变。
• 当创建者失去执行权限时会自动关闭。 在下一个执行时刻，服务器会进行检查，不执行并将 activated 降为 false。即使权限恢复，也不会自动开启。
• 数量有上限。 一个 Organization 可拥有的 Scheduler 数量按套餐规定（Free 1 个、Basic 3 个、Pro 30 个、Enterprise 无限制）。超过该上限时，创建会被拒绝。
• 执行次数与 Script 共享。 每运行一次，就会消耗一次套餐的 Script 执行次数。没有 Scheduler 专用的执行上限。若因超过该上限导致 Organization 的 Script 执行被暂停，则此后到达运行时刻的 Scheduler 将不会执行，activated 会变为 false。此时会留下一条 SchedulerLog，sys.error 中载入原因。该 Scheduler 关闭之后不会再重新进入调度。
• 错过的执行不会补偿。 即使某些执行时刻被错过，之后也不会一次性集中执行，而是从下一个时刻起重新运行。
• 正在使用的 Script 无法删除。 尝试删除被某个 Scheduler 引用的 Script 时，该删除会被拒绝（参见 Script 的错误）。
• 没有发布。 创建时无需状态值或发布步骤即可立即进入调度，删除也无需前置步骤即可直接完成。

SchedulerLog

Scheduler 每运行一次，就会留下一条执行记录。它是只读的，没有创建、修改、删除端点。路径为 /spaces/{spaceId}/schedulers/{schedulerId}/logs。

{
  "sys": {
    "id": "5nRt8YcVm2Qb7WxZpK4dGhJ9sL",
    "type": "SchedulerLog",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "requestId": "3trmXRM8dNvQ2LbYpK7fHsJ3gWc4Rt",
    "success": true,
    "createdBy": { "sys": { "id": "7kQm2ZbTn4Rc9WvXpL3dHsY6fJ", "type": "Refer", "targetType": "Scheduler" } },
    "createdAt": "2026-09-03T00:00:02.503Z",
    "updatedBy": { "sys": { "id": "7kQm2ZbTn4Rc9WvXpL3dHsY6fJ", "type": "Refer", "targetType": "Scheduler" } },
    "updatedAt": "2026-09-03T00:00:02.503Z"
  }
}

所有值都在 sys 中，没有主体属性。没有值的键会从响应中省略（上面的示例中没有 error）。

没有 scheduler 字段。 是哪个 Scheduler 留下的记录，由 sys.createdBy 指向，其 targetType 为 "Scheduler"。sys.updatedBy 也是同一个 Scheduler。

也没有 startedAt、endedAt、result 以及耗时字段。 一次执行耗时多久，以及 Script 返回的值，都在具有相同 requestId 的 ScriptLog 中（sys.durationMs、sys.value、sys.statusCode）。字段构成在 Script 资源与端点 中介绍。

一次执行会留下两条日志。 一条是这个精简的 SchedulerLog，另一条是承载该次执行本身的 ScriptLog（ScriptLog 的 sys.trigger 指向这个 Scheduler）。两者以相同的 requestId 关联在一起。

记录在执行结束后写入一次，之后不再改变。成功的执行在 1 小时后消失，失败的执行在 3 天后消失。 响应中没有承载过期时间的字段，时间一到记录就会消失。需要保留更久的值，请在 Script 中保存为 Content。

错误

以下是处理 Scheduler 时会遇到的错误码。所有资源共通的错误码，请参见通用错误。

API

以下所有端点的基准 URL 为 https://cma.weegloo.com/v1，Authorization 请求头中需要用于认证 CMA 的 Bearer 令牌。Scheduler 没有 sys.version，因此修改时不发送 X-Weegloo-Version 请求头。

相关文档

• Script：Scheduler 执行的资源。介绍其定义结构和 statement 种类。
• Webhook：通过事件而非时刻来执行 Script 的资源。
• SpaceRole：包含 SETTING_SCHEDULER 设置权限和 Script 的 Execute 权限的角色。
• Scheduler 概念：这是做什么用的功能，以及在控制台中的操作方法。