为设备群安排计划
活动(campaign) 按计划向某个实体组中的设备发送命令,并为它尝试过的每台设备保留记录。路灯照明正是 它的设计场景:让每盏灯在各自的日落时调暗、在各自的日出时恢复,跳过公共假日,并在第二天早晨知道哪些灯 没有执行以及原因。
一个活动由三部分组成:
- 触发器,说明何时触发:cron 表达式、日历日期,或太阳;
- 一个或多个步骤,每个步骤是一条命令,可带载荷,并可在触发后延迟执行;
- 目标,即一个设备实体组。
每次触发器触发时,平台会规划一个周期(cycle)。一个周期为每台设备的每个步骤包含一个元素,元素 是跟踪与重试的单位。在底层,每一组到期的元素会成为一个普通的命令批次,因此 每台设备都会依据其能力契约校验、按其维护窗口暂缓、沿命令生命周期被跟踪,并 按生存时间到期,与其他任何命令完全一致。请先阅读这两篇指南;本篇只介绍计划新增的部分。
活动位于 command-delivery 端点 https://<your-host>/api/command-delivery/graphql。创建、启停和删除活动
以及重试失败项需要 command:write,读取需要 command:read。所有操作还需要 device:read,因为活动指向
一个组,其跟踪会列出组内设备。仅限于租户部分范围的成员不能使用活动。
创建活动
mutation {
createCampaign(request: {
token: "dusk-dim"
name: "Dim at dusk"
trigger: "{\"kind\":\"SOLAR\",\"zone\":\"Europe/Berlin\",\"event\":\"SUNSET\",\"offsetMinutes\":-15}"
steps: [
{ type: "COMMAND", name: "setLevel", payload: "{\"level\":40}" }
{ type: "COMMAND", name: "setLevel", payload: "{\"level\":20}", delaySeconds: 21600 }
]
groupToken: "city-streetlights"
}) {
campaign { token enabled plannedThrough lastError }
rejection { code reason }
}
}
无法接受的定义会以 rejection 返回,而不是错误。代码包括 CAMPAIGN_TRIGGER_INVALID、
CAMPAIGN_STEPS_INVALID、CAMPAIGN_STEP_UNSUPPORTED、CAMPAIGN_TARGET_INVALID、
CAMPAIGN_FIELD_INVALID、TOKEN_IN_USE,以及单条命令被拒绝时使用的载荷和命令名称代码。
| 字段 | 含义 |
|---|---|
token | 在租户内唯一。 |
name | 可选,最多 128 个字符。 |
trigger | 一个 JSON 文档,见下文。 |
steps | 一到十个步骤。步骤为 COMMAND,带 name、可选的 JSON payload,以及触发后 0 到 86400 的 delaySeconds。 |
groupToken | 目标实体组,最多 128 个字符。动态组可以选择某个区域的设备。 |
maxLatenessSeconds | 已规划的命令最多还能晚发多久,1 到 86400。默认 900。 |
expiresInSeconds | 每条命令的生存时间,1 到 604800,从创建时起算。默认 3600。它决定命令可以为不可达的设备或维护窗口等待多久,因此可能长于 maxLatenessSeconds;后者限制的是调度器何时发送,而不是设备何时收到。如果迟到的送达比不送达更糟,请把它设短。 |
enabled | 是否一开始就启用。默认 true。 |
新建的活动不会发送任何在其创建之前就已到期的内容。太阳触发器的规划从前一个本地午夜开始,以便远在西边的
灯具仍能得到它的傍晚;这段时间里已经过去的部分会被记录为 SKIPPED,原因为 PREDATES_CAMPAIGN,绝不会发送。
修改活动
本版本没有更新操作。要修改活动的触发器、步骤、目标或上限,请删除它并重新创建;旧活动删除后,令牌即可再次 使用。由于新活动不会发送在其创建之前到期的内容,在黄昏后不久重新创建活动不会让灯再调暗一次。
ARTIFACT 步骤类型属于词汇表,但本版本不执行;它会以 CAMPAIGN_STEP_UNSUPPORTED 被拒绝,而不是被忽略。
若要按计划推出更新,请使用分批发布。
触发器
每个触发器都需要在 zone 中给出 IANA 时区。空时区或 Local 会被拒绝:跟随主机的计划会在 pod 迁移时跟着
移动。
Cron
{"kind":"CRON","zone":"America/New_York","cron":"30 18 * * *"}
五个字段:分、时、日、月、星期。每个字段接受 *、数字、a-b、*/n、a-b/n 及逗号列表。星期取值 0 到 7,
0 和 7 都表示星期日。当两个日字段都有限制时,满足任一即匹配。名称、?、L 和 @daily 会被拒绝。
日历
{"kind":"CALENDAR","zone":"Europe/London","dates":["2026-12-24","2026-12-31"],"times":["07:00","17:30"]}
在列出的每个日期的每个时间触发,按该时区计算。
太阳
{"kind":"SOLAR","zone":"Europe/Berlin","event":"SUNSET","offsetMinutes":-15}
在 SUNSET 或 SUNRISE 加上 offsetMinutes(负数表示提前)时触发,针对每台设备依据其自身的安装位置
单独计算。因此同一个触发器在每盏灯上触发的时刻都不同,一座城市的灯会随太阳依次调暗。
安装位置即设备的安装位置记录,通过 setInstalledPosition 变更或设备批量导入的安装位置列写入:
mutation {
setInstalledPosition(family: DEVICE, token: "lamp-0001",
position: { latitude: 52.52, longitude: 13.40, source: SURVEY }) { latitude longitude }
}
请在灯具调试投运时设置。它刻意不是最近一次上报的位置:灯不会移动,接收机故障的灯也不应在错误的日落时刻 调暗。该计算在大约北纬与南纬 60 度之间精度约为两分钟。
太阳事件不涉及时区,因为太阳并不知道时区。这里的时区只用来指明日期和假日所属的公历日。
两类设备会被记录为跳过,而不是被猜测:
- 没有安装位置的设备记为
NO_SITE; - 当天太阳不升起或不落下的设备(极圈以内)记为
POLAR_DAY或POLAR_NIGHT。
如果活动带有太阳触发器而设备位置完全无法读取,规划会失败,原因显示在活动的 lastError 中;不会发送任何内容。
假日
任何触发器都可以带 holidays,即该时区中不触发的本地日期列表:
{"kind":"SOLAR","zone":"Europe/Berlin","event":"SUNSET","holidays":["2026-12-24","2026-12-25"]}
假日会抑制一次触发,绝不会把它挪到其他日子。
夏令时
cron 或日历中的时间是该时区的挂钟时间。在每年两个存在歧义的日子里:
- 落在春季跳变空档内的时间,在时钟跳变的那一刻触发一次;
- 在秋季回拨的那个小时内出现两次的时间,仅在其第一次出现时触发。
维护窗口
活动本身没有窗口。它创建的每条命令都经过与其他命令相同的关卡:发往其设备类型设有
维护窗口的设备的破坏性命令会被暂缓,直到窗口开启;若窗口要到命令过期之后才
开启,则直接拒绝。被暂缓的命令在周期计数中算作 waiting。请把 expiresInSeconds 设得足够长,以覆盖你愿意
允许的等待时间。
延迟或宕机时会怎样
调度器在每个副本中每 15 秒运行一次,没有主节点;无论有多少副本在运行或重启,一台设备只会被下发一次命令: 每个元素的认领是数据库中的比较并设置操作,它所创建的批次带有由其元素派生的令牌,因此接手已宕机副本工作的 副本是重放该批次而不是重复创建。
超过迟到上限的命令绝不会发送。一个到期后未在 maxLatenessSeconds 内被认领的元素(发生了宕机,或活动
被关闭)会被标记为 SKIPPED,原因为 MISSED。午夜才发出的调暗命令比不发更糟,所以活动绝不会补发。
活动也不会集中发送积压。当同一设备的同一步骤有多次触发同时到期时(例如宕机之后、迟到上限很长的每小时活动),
只发送最新的一次,较早的会被记录为 SKIPPED,原因为 SUPERSEDED。设备只收到一条命令,而不是每个错过的
小时一条。
关闭活动会停止规划与发送。重新启用后从那一刻开始:关闭期间到期的内容会被记录为 SKIPPED,原因为
DISABLED,不会发送。删除活动会取消所有已规划但尚未发送的内容,标记为 SKIPPED,原因为
CANCELLED;已创建的命令不受影响,而在活动被删除时正在发送的元素会依据该命令记录,而不是记为已取消。
租户的未送达命令上限依然适用。如果一个非常大的设备群在同一时刻到期,超出上限的
设备会被记录为 REFUSED,原因为 HELD_CEILING_EXCEEDED,并可以重试。
跟踪一个周期
query {
campaignCycles(campaignToken: "dusk-dim", limit: 3) {
key day resolved
counts { pending dispatched refused skipped succeeded inFlight waiting failed unknown }
}
}
counts 回答第二天早晨的问题。前五个数字按活动的状态统计元素:pending、claimed、dispatched、
refused、skipped。其余数字统计已下发元素背后的命令:succeeded、inFlight(其中因窗口而 waiting
的数量)、failed(未成功结束且可以安全重发)以及 unknown(可能已经执行)。
要查看设备,可按状态分页浏览元素:
query {
campaignElements(campaignToken: "dusk-dim", cycleKey: "d2026-06-21", status: "SKIPPED", limit: 200) {
id deviceToken step dueAt status reason commandStatus commandOutcome
}
}
把最后一个 id 作为 afterId 传入即可获取下一页。
重试失败项
mutation {
retryCampaignFailed(campaignToken: "dusk-dim", cycleKey: "d2026-06-21", includeUnknown: false) {
batches retried held
}
}
这会把该周期中未成功的元素交给平台的批次重试,因此它的安全保障同样适用:命令仍在
进行中或已成功的设备绝不会收到第二份副本;结果未知的设备只有在你传入 includeUnknown: true(并已确认执行
两次无害)时才会收到。被批次拒绝的元素也会被重试。held 统计因重发不安全而被保持不动的元素。
一个元素只重试一次。如果重试本身失败,请通过批次 API 重试那个批次。
限制
- 一个周期最多规划 100,000 台设备。
- 周期中的设备是该周期被规划时(最早在触发前 36 小时)组内的成员。周期首次到期时会重新读取该组,此后已离开
组的设备会被记录为
SKIPPED,原因为NOT_IN_GROUP,而不会收到命令。如果当时无法读取该组,周期会等到 能够读取时才发送(若耗时超过迟到上限,则记为MISSED)。在周期规划之后加入组的设备不会被加入该周期, 而是进入下一个被规划的周期。 - 已结束的周期及其元素保留 30 天。
- 目标是一个实体组。不支持直接以区域为目标;请使用选择该区域设备的动态组。
- 步骤是一条命令。本版本不执行更新步骤。