AqaraLink 开发者平台入门：从零到第一次调用

简要回答 — 文档记载的路径共六步：注册开发者账户、创建项目（获得 appId 和密钥）、选择授权模式、接入设备、调用 API，最后配置消息推送和 IP 白名单。授权方式的选择会影响之后的一切。Aqara 账户绑定真实用户的 Aqara Home 设备。项目授权适用于通过 Implementation Tool 接入的 B 端场所。虚拟账户为你自己的终端用户创建一个 Aqara 账户，这样你的 App 不会让他们注册两次，而且该虚拟账户不能在 Aqara Home 中使用，只能通过 SDK 使用。

我们的 AqaraLink 开发者平台概览介绍了平台是什么以及有哪些模块。本文讲的是在其上开发的第一周：操作顺序，以及第一周就必须选定的分支。

文档实际列出的六个步骤

opendoc.aqara.com 上的英文开发者文档，以固定顺序列出了云端集成流程。请严格照做，其中有两个步骤依赖前一步创建的配置。

1. 注册并登录 Aqara 开发者平台。
2. 创建应用和密钥。 新建项目 → 填写 Project Name、Industry Type、Introduction → 保存。项目会显示为 pending review（待审核）；审核通过后状态变为 approved（已通过），即可查看项目详情。appId 分配给该项目，审核通过时会生成一个默认密钥，可在 Project Details → Key Management 中查看，也可以在那里添加更多。
3. 授权管理。 共三种模式，见下文。
4. 添加设备。 三种途径，“根据开发者的需求和授权类型”选择。
5. API 管理。 查询设备信息、控制设备、配置联动。
6. 消息推送配置，以及可选的 IP 设置。

清单中有两点常被忽略，日后会造成麻烦。第一，项目在审核通过之前无法使用。第二，用户和设备数据在项目之间是隔离的，但同一位用户可以被授权给多个项目。因此，为每个客户各建一个项目，并不能在任何实质意义上隔离租户，只会让你要轮换的凭证成倍增加。

第 3 步才是真正的决定：选哪种授权模式

这是分岔点。阅读它成本很低，但等你的接入用户体验写好之后再改，代价很高。

“在 Aqara Home 中可见”这一行，正是虚拟账户模式的关键所在，而加粗的限制正是让团队栽跟头的地方。

虚拟账户：它是什么，不是什么

文档对动机的说明很直白。如果开发者已经有自己的账户体系，想把 Aqara 设备纳入自己的 IoT 生态，又不希望终端用户感觉到有两套账户，就在自己的 App 中集成 Aqara 设备 SDK，并把设备绑定到指定的虚拟账户。虚拟账户的定义是：通过接口创建的虚拟 Aqara 账户，用户可以通过开放 SDK 或 implementation tool 将设备绑定到该账户下。

对为客户做项目的集成商而言：

• 身份由你掌握。 你的 accountId 是你自己创建的字符串，保证在 appId 下唯一，是一切的根。你的客户不需要创建 Aqara 账户，也不需要知道它的存在。平台会返回 openId，即虚拟用户的唯一标识，这是你的后端保存并在之后每次调用中使用的句柄。
• Token 有效期由你设定。 config.auth.createAccount 接受一个可选的布尔参数 needAccessToken：false 只返回 openId，true 则同时返回 accessToken、refreshToken 和 expiresIn。可选参数 accessTokenValidity 默认为 7 天，可设为 1 至 24 小时或 1 至 30 天。刷新令牌的有效期为访问令牌过期时间再加 30 天。
• 虚拟账户不能在 Aqara Home App 中使用。 如果你的终端用户同时也使用 Aqara Home，他们将看不到你绑定的设备。要尽早决定这是否可以接受，因为技术支持无法撤销这一点。

文档记载的流程概貌

第 1 步：创建虚拟账户：

`` { "intent": "config.auth.createAccount", "data": { "accountId": "18900001234", "remark": "lumi-1" } } ``

第 2 步：请求授权码，虚拟账户的 accountType 为 2。授权码有效期为 10 分钟。 第 3 步：用 config.auth.getToken 兑换，得到 accessToken、refreshToken、expiresIn 和 openId。

真实 Aqara 账户的路径，从真实账户出发，流程相同：config.auth.getAuthCode，accountType 为 0，授权码有效期 10 分钟，然后调用 config.auth.getToken，其访问令牌默认为 7 天。项目授权是相同的兑换流程，accountType 为 1，授权码来自 IoT Solution Platform 控制台。config.auth.refreshToken 负责续期，三种方式返回令牌的规则相同：刷新令牌的有效期是访问令牌过期时间加 30 天，这是被遗忘的刷新令牌能存在多久的硬性上限。

在硬编码之前，请对照线上的授权管理页面核实当前的参数名和账户类型值。文档的版本与你的集成是分开管理的。

每个请求都要签名，这一步不能跳过

调用发往 https://${domain}/v3.0/open/api，其中 domain 是服务器区域。文档列出了已部署的区域，包括中国大陆、美国、韩国、俄罗斯、欧洲和新加坡，各自有独立的 API 域名和时区，在项目中选择。必需的请求头：Appid、Keyid（你的应用的密钥）、Nonce（随机字符串，每个请求都不同）和 Time。接口需要时才带上 Accesstoken。

签名规则，已对照签名规则页面核实：把请求头参数按 ASCII 排序，拼接成 Accesstoken=xxx&Appid=xxx&Keyid=xxx&Nonce=xxx&Time=xxx，把 Appkey 直接附加在该字符串之后，将结果转为小写，然后做 MD5，32 位。这就是你的 Sign 请求头。

文档中有一个例外：部分接口不需要 Accesstoken，此时 Accesstoken 不参与签名。弄错会产生错误码 106 Invalid sign，而 107 Illegal appKey 则针对你尚未激活的密钥。

第 4 步：三种接入途径，而不是一种

不带界面的 SDK 比大家想象的要窄：它只用于添加网关设备，子设备再通过 write.device.openConnect 接口添加。带界面的 SDK 提供 Aqara 风格的页面，可以直接使用，也可以重新设计样式。对于 Zigbee，接入是由网关驱动的：你的 App 调用云端 HTTP API 让网关进入配对模式，由网关发现并绑定周围的设备。文档里有一句坦率的说明：开发者平台上没有公布 App SDK 的下载链接，页面指引有需求的开发者联系 Lumi 的海外业务团队。在规划开发冲刺之前，先规划好这次沟通。

单个住宅还是整个场所：范围界定的决定

对于客户的一个住宅，你需要一个项目、一份 IP 白名单，以及为少量设备准备的 Implementation Tool 或 SDK。对于整个场所，你使用的是 Aqara IoT Solution Platform 上的项目授权，由 Implementation Tool 负责批量添加，并用项目授权码兑换令牌。

范围界定的问题不是“有多少台设备”，而是“合同结束时，设备归谁的身份持有”。在虚拟账户下，客户的设备位于你创建的账户中，客户离开时，整个场所必须迁移，而不是直接停用。在项目授权下，整个场所位于你的项目之内，设备随空间设计一起存在。写下谁可以触发令牌刷新，因为这个人实际上控制着设备。

首次运行检查清单

• [ ] 项目状态显示 approved，而不是 pending review
• [ ] 已记录 appId，默认密钥可在 Key Management 中看到
• [ ] 已选定服务器区域；已记下 API 域名和时区
• [ ] IP 白名单已填写：它默认是空的，所以在你限制之前，任何 IP 都可以调用你的接口
• [ ] 已选定授权模式并写下来
• [ ] 已确认你的 HTTP 客户端生成的 Nonce 不会重复
• [ ] 已配置消息推送签名，或有意不启用
• [ ] 已进行设备调试：授权账户下的真实设备，或你自己添加的虚拟设备（先网关，后子设备）