Aqara 自动化与场景 API：正确建模规则的方法

简要回答 — 在 Aqara 自动化与场景 API 中，场景和自动化是不同的对象，创建接口也不同。场景是由你调用的一组动作；config.scene.create 接受名称、可选的位置，以及一个有序的动作列表，每个动作可带可选的延时。自动化是会自行触发的“触发条件/条件/动作”规则；config.linkage.create 接受条件、AND/OR 关系和动作。从 API 的角度看，这两种对象都不会自动成为“本地”或“云端”，但平台文档确实宣传了本地化的多设备自动化，用于稳定的场景控制，你的关键规则应该由这项能力来承载。

如果你读过我们的 AqaraLink 开发者平台概览，就知道有这些模块。本文讲的是建模决策，大多数集成缺陷都出在这里：团队在需要自动化的地方建了场景，或者生成了四十个自动化，而四个场景就够了。

它们不是同一种对象，差别也不只是表面上的

关于联动配置规则的附录页面对两者都有定义，而且定义刻意区分开：

• 自动化（Automation）：用户自定义条件和动作。触发条件满足时，设定的动作自动执行。
• 场景（Scene）：用户自定义要执行的动作。手动触发场景时，设定的动作被执行。
• 多条件（Multiple-conditions）：第三种对象，让用户自定义触发条件，支持多种 AND/OR 组合。

API 也体现了这一点。config.scene.create 有 name、可选的 positionId 和一个 action 数组。config.linkage.create 有 name、可选的 positionId、一个 conditions 对象和一个 actions 对象。场景创建接口里没有条件字段。这种区别是结构性的，不是界面上的习惯。

由此立刻得出两点结论：

场景是有序、刻意的；自动化是有状态、有条件的。 场景动作带有 delayTime，delayTimeUnit 为 1 表示秒、2 表示分钟，延时范围为 0 至 59 秒或 0 至 59 分钟。这种排序原语属于场景模型，因为场景就是一段脚本。自动化建模的是一个判断条件，所以它的条件带有 beginTime 和 endTime，即一个时间窗口，而不是错开的时间间隔。

你的服务器需要知道这个区别，因为事件会告诉它。 消息推送格式定义了不同的事件类型：自动化对应 linkage_created 和 linkage_deleted，场景对应 scene_created 和 scene_deleted，多条件对应 event_created / event_deleted。如果你的集成把三者都合并成“一条规则”，当用户问走廊的灯为什么亮了，你就答不上来。

在构建任何东西之前，先弄清楚有哪些可能

两个创建调用都不是靠猜的地方。文档首先把两者都指向两个查询接口：

• query.ifttt.trigger：查询某个物模型（object model）支持的自动触发条件配置，包括条件名称和参数。你传入关心的模型。
• query.ifttt.action：动作侧的对应接口。

物模型本身可以在控制台的 Device Resources 页面查询。所以正确的顺序是：阅读模型，查询它支持的触发条件，查询它支持的动作，然后组合。

还有第二条创建路径值得了解，因为它能解锁系统预设未覆盖的属性。文档描述了创建联动的两种方式：通过物模型找到的系统定义的 actionDefinition 或 triggerDefinition，或者直接自定义设备属性。自定义属性路径使用固定的参数值，triggerDefinitionId 为 TD.custom_1，paramId 为 PD.custom.trigger，实际的判断内容以 JSON 数组字符串的形式携带资源 id、值和运算符。

对于条件集合，relation 字段是整数：0 表示 AND，1 表示 OR，默认为 0。这是个小细节，影响却很大：本该同时要求门传感器和时间窗口的自动化，如果默认值放错了地方，任一条件满足就会触发，而且它会通过你手写的每一项测试。

场景还是自动化：决策规则

底层规则：如果是人来按，它就是场景。如果是传感器或时钟引发的，它就是自动化。 大多数糟糕的集成把这一点搞反了，结果是自动化互相重复，而场景的动作顺序里塞进了逻辑。

本地执行，以及它对你的云端意味着什么

平台自己的能力列表宣传了本地智能自动化：“支持本地化的多设备自动化，实现稳定的场景控制”，并以离家模式和在家模式为例。Aqara 以 Zigbee 为先，网关是本地控制器；整个 mesh 网络的意义就在于规则在设备里运行，而不是在另一个国家的数据中心里运行。

这是架构上的事实，不是销售话术，它应该改变你的设计：

• 关键规则应放在你的服务器宕机时仍能运行的地方。 走廊感应灯、水阀关闭、门未关好，这些即使你的云端也保存了一份，也值得放在网关上。
• 你的云端不应是安全动作的唯一途径。 如果你的集成价值是“我们给自动化加了逻辑”，那么对这类设备来说，你做出来的东西严格来说比本地规则更差。
• 跨住宅、跨租户或历史性的事项，云端仍然是正确的位置。 占用分析、能耗报告、全场所范围的模式切换，这些没有本地对应物，正是 API 物有所值的地方。

陷阱是在两个地方重复同一条规则。如果一条规则既在网关上又在你的云端，就会重复触发，而找出原因的调试过程真的很痛苦。为每条规则选定一个执行位置，并记录下来。

避免自动化数量爆炸

这是让演示在第三个月之后失败的模式。每个边界情况都变成一个新的自动化，用户的列表从八项变成四百项，没有一项是他们能理清的。

事件类型说明了风险的规模：linkage_created、linkage_deleted、scene_created、scene_deleted、event_created、event_deleted 都会推送到你的服务器。如果用户在 Aqara Home App 里创建规则，无论是不是你的系统创建的，你的系统都会知道。你的界面将是一个从两个方向被编辑的空间的镜像。

四个保持数量可控的做法：

用模板，不要生成。 提供一套固定的合理自动化目录，让用户开启，而不是在运行时组合任意规则。目录可以审核，四百条用户生成的规则则无法审核。

开放条件，不要开放完整的规则语法。 组合爆炸发生在触发侧。如果你的产品只在少数设备上提供“当走廊检测到有人移动时”这样的选项，你就限定了范围。

优先用一个场景加一个状态变量，而不是 N 个自动化。 把“晚安”做成一个场景，再加一个监视你 App 自身状态的自动化，胜过六个针对六种设备组合的自动化。

对账，不要累积。 因为创建和删除事件都会推送，你可以保有准确的清单。定期完整读取联动和场景对象并做差异比较。网关上存在、但不在你目录中的规则，是有人手工创建的规则，把它显示出来，不要悄悄接管。

值得预先防范的故障模式

删除了规则下的设备。 条件和动作都引用 subjectId 和一个模型。引用了已解绑设备的规则将不会触发，而文档没有描述墓碑（tombstone）状态。执行场景之前，先检查被引用的设备。

延时单位造成的排序错误。 delayTimeUnit 为 1 是秒，2 是分钟。用错单位建出的场景不会报错，只是耗时比任何人预期的长得多，读起来就是“自动化坏了”。

位置默认值。 两个创建调用都把空的 positionId 当作默认位置。如果你的产品支持多物业或多楼层，未设置位置会悄悄把规则归到错误的空间。

条件关系默认值。 上文已述，这是最先该写单元测试的一项。