AqaraLink 开发者平台入门：从零到第一次调用
AqaraLink 开发者平台入门：文档列出的步骤、三种授权模式、虚拟账户、App Key 和设备接入途径。
开发者与集成商
Matter、Zigbee 还是厂商 API：选择智能家居集成策略
简要回答 — 没有唯一正确的路线，因为三者解决的是不同的问题。Matter 带来跨厂商的互操作性，以及日后离开某个生态的自由。Zigbee 带来可靠的低功耗 mesh 网络，以及在断网时仍能继续运行的规则。厂商 API 带来只有该厂商才开放的能力，即 Aqara 自己的门锁、摄像头、红外和本地自动化。对大多数马来西亚项目而言，诚实的答案是分而治之：客户可能会更换的设备用 Matter，本地控制的主干用 Zigbee，只有在没有通用方案时才用厂商 API。具体到 Aqara，Matter 需要一个控制器，例如先在 Aqara Home 中设置好的 Hub M3，而 SDK 中的 Matter 子设备必须先通过 Aqara Matter 网关，使用 Magic Pair 连接，然后才能配置或控制。
选择网关一文说明该买哪款网关，Aqara 的 Matter 支持一文说明如何设置 Matter 控制器。两篇都不涉及架构决策，而这正是本文的用途。
决策要看的是故障，不是功能
每一种集成策略，其实都是对一个问题的回答：当厂商、云端或你自己的服务器消失时，还有什么能继续工作？ 这个角度胜过功能对照表，因为功能会变，而故障模式不会。
- 如果答案必须是“灯仍然能亮”，你需要本地执行，也就是网关加 mesh 协议。
- 如果答案必须是“两年后我可以换厂商”，你需要一个不受厂商控制的互操作标准。
- 如果答案必须是“我需要 Aqara 门锁的特定行为”，你需要 Aqara 的 API，并接受这种依赖。
团队常犯的错误是选了演示效果最好的路线。演示效果最好的通常是厂商 API，因为它的集成最漂亮、能力最强。但它也会让你客户的楼宇依赖一个你无法控制的对象。
三条路线，实话实说
| Matter | Zigbee | 厂商 API | |
|---|---|---|---|
| 主要价值 | 跨厂商的互操作性 | 可靠的低功耗 mesh、本地执行 | 标准没有开放的能力 |
| 谁掌控规范 | Connectivity Standards Alliance，不是某个厂商 | Connectivity Standards Alliance（前身是 Zigbee Alliance），不是某个厂商 | 厂商 |
| 无网络时能否运行 | 能，一旦在控制器上完成调试 | 能，这是默认情况 | 一般不能 |
| 每台设备的开发工作量 | 较高：调试、多管理员、多生态 | mesh 较低；网关仍需调试 | 起步最低，维护最高 |
| 生态广度 | 在增长，而且天生跨厂商 | 传感器种类广，但以网关为核心 | 恰好是一家厂商的产品目录 |
| 锁定程度 | 设备层低，控制器层较高 | 中等，与网关厂商绑定 | 高，而且这正是重点 |
| 你要放弃的 | 厂商专有的附加功能 | 跨厂商的覆盖 | 可移植性 |
Matter：退路
Matter 的价值不在功能，而在于它让你可以离开。一个在 Matter 控制器上完成调试的 Matter 配件，由该控制器控制，配件并不绑定于设置它的那个 App。如果你的客户不再使用 Aqara，设备不会变成废铁。
工程成本是真实的，而且出在调试环节，不在 API。你必须把控制器、fabric 和多管理员的机制都弄对。Aqara 支持的 Matter 设备类型清单涵盖照明和执行器：开关灯、可调光灯、色温灯和增强彩色灯；开关插件和可调光插件；壁装开关控制和壁装调光负载控制。这个范围是实实在在的，值得对照你的设备清单核实，而不要想当然。
让人栽跟头的 Aqara 事实：
- Matter 配件（包括 Thread 上的 Matter）需要一个 Matter 控制器，例如先在 Aqara Home 中设置好的 Hub M3。 Aqara 的 Matter 支持详细说明了顺序。要在配对之前完成设置，而不是之后。
- Zigbee 设备可以接入 Hub M3 或 Panel Hub S1 Plus，因为 S1 Plus 本身就是 Zigbee 网关。这是 Aqara 产品线里最常见的困惑来源：S1 Plus 是 Zigbee 网关，不是 Matter 控制器。Matter 配件通过 Hub M3 这样的 Matter 控制器添加，之后可以从 S1 Plus 控制。
- 在 SDK 中，Matter 子设备无法直接配置和连接。 Matter 垂直品类 SDK 文档明确说明：必须先通过 Aqara Matter 网关，使用 Aqara 的私有协议 Magic Pair 连接，然后才能进行设备配置和控制。如果你在构建手机端的接入流程，这是你用户体验中的硬性顺序约束，而不是细节。
锁定方面的提醒：摆脱设备层不等于摆脱网关层。无论你把设备调试到哪个控制器上，那个控制器就成为你客户所依赖的东西。Matter 降低了锁定的一个维度，而不是全部。
Zigbee：持续可用的路线
Aqara 以 Zigbee 为先，一个网关最多可控制 128 台相关设备。Zigbee 对集成商的价值不在协议本身，而在于规则在设备单元内运行。走廊的感应灯不在乎光纤是否在线，而灯光需要数据中心才能运作的智能家居，其单点故障并不在你的建筑里。
本地执行是决定性因素，这也是为什么自动化和场景的决策应放在网关上，而不只是放在你的云端。平台文档宣传了本地化的多设备自动化，用于稳定的场景控制，并以离家模式和在家模式为例。
每台设备的工程量较低，总量较高。mesh 本身简单，调试、摆放和路由却不简单。三层店屋里最远端只有一个中继器的子设备，是现场问题，不是协议问题，任何 API 决策都解决不了。
厂商 API：能做到别人做不到的事的路线
Aqara 平台自称支持多协议：Zigbee、Wi-Fi、Thread、Bluetooth、Ethernet、IR、Matter、BACnet、KNX、DALI 和 Modbus。在开发者一侧，云端 HTTP API 涵盖设备状态查询、远程控制和联动配置，并通过消息推送实现设备的实时上报。App SDK 套件涵盖设备配对、设备控制、红外遥控、摄像头和门锁产品线。
需要 Aqara 专有行为时，就走这条路：红外学习和红外虚拟子设备、门锁产品线、摄像头预览和回放、Aqara Home 生态体验。这些明天都不会进入某个通用标准，假装它们会，正是集成项目卡住的原因。
代价你已经知道：你客户的楼宇现在依赖一家厂商的路线图、一家厂商的云端和一家厂商的定价。Aqara IoT Solution Platform 针对的正是这种情况：房地产、楼宇、酒店、校园和养老护理，提供批量接入和运营工具。它行之有效，因为这是有意选择锁定以换取能力。
实际如何选择
| 你的需求 | 路线 |
|---|---|
| 客户两年后可能更换厂商 | Matter，适用于客户付费的任何设备 |
| 断网时灯光和门锁必须能工作 | Zigbee，规则放在网关上 |
| 服务式公寓中由红外控制的空调 | 厂商 API：没有哪个标准能合理覆盖 |
| 以 Apple Home 为控制器的跨厂商楼宇 | Matter |
| 住宅楼栋中的 Aqara 门锁 | 厂商 API，接受这种依赖，并在合同中约定支持 |
| 传感器密集的占用分析 | Zigbee 加厂商 API 获取数据 |
| 永远不会离开该生态的客户 | 全程使用厂商 API，并在合同中写明 |
要避免的故障模式是向客户宣称为厂商中立、实际却是单一厂商的方案。如果物业经理被告知日后可以更换厂商，结果每台设备都只能用 Aqara，那是你自己造成、也无法挽回的商务问题。如果 Matter 是你的退出策略，关键的设备就必须真的是 Matter。
顺序，项目失败的地方
顺序没有商量余地，每个项目都一样：
- 按设备类别决定协议策略，而不是按项目。 “Zigbee 作为主干，Matter 用于可更换的照明，厂商 API 用于门锁和红外。”
- 先调试控制器。 对 Aqara 而言，就是在配对任何 Matter 配件之前，先在 Aqara Home 中设置好 Hub M3 这样的 Matter 控制器。
- 按 mesh 覆盖来摆放网关，不要按外观。 然后在调试其余设备之前，先验证最远的角落。
- 把安全和逃生相关的关键规则放在网关上，而不只是在你的云端。
- 然后才接入厂商 API 层，用于标准路线确实做不到的事。
- 写下哪些设备依赖厂商，并把这份清单连同维护合同一起交给客户。
