OneNET 平台 API 交互开发完全教程与避坑指南

OneNET 平台 API 交互开发完全教程与避坑指南

本文档旨在记录基于中国移动 OneNET 平台（新版物模型架构）进行物联网应用开发时的完整流程。从核心概念理解、鉴权 Token 的生成原理、使用 ApiFox 进行联调测试，到最终的避坑指南，为你提供一条完整的从云端到 App 端的开发路径。

第一章：核心概念与准备工作

在与 OneNET 平台进行 API 交互前，必须明确以下三个层级的核心标识参数，它们决定了你要控制或查询的目标是谁。

1. user_id(用户 ID)：代表你的 OneNET 账号，拥有最高权限。
2. product_id(产品 ID)：代表一类设备的集合（如“智能鱼缸系列”）。在“产品开发”页面获取。
3. device_name(设备名称)：具体的某一台硬件设备（如“鱼缸01号”）。在“设备列表”页面获取。

此外，还需要identifier(标识符)，它在“功能定义/物模型”中定义，代表设备的某个具体属性（如temp代表温度，pump代表水泵）。

第二章：鉴权机制与 Token 生成 (Authorization)

OneNET 所有 API 请求都必须在 HTTP Header 中携带Authorization字段进行安全校验。这个字段的值就是一个Token。

1. Token 的组成

Token 的格式通常如下：version=2018-10-31&res=products%2FTblw5uXZIK&et=1999999999&method=md5&sign=xxx...xxx

• version: 签名版本，固定为 2018-10-31 等。
• et: 过期时间 (Expiration Time) 的时间戳。如1999999999代表 2033年。
• method: 加密方法（如 md5, sha1）。
• sign: 根据你的 AccessKey 计算出的签名字符串。
• res: 资源标识 (Resource) —— 这是最重要的参数，决定了该 Token 的权限范围！

2. 生成 Token 时不同xxx_id的区别 (res参数的区别)

在生成 Token 时，你可以选