使用自定义 Topic 通信
2025/10/12大约 2 分钟
使用自定义 Topic 通信
使用 MQTT 协议接入的设备与平台通过订阅 Topic 或向 Topic 发布消息的方式进行通信。Topic 分为系统 Topic(连接鉴权等内部使用)、物模型 Topic(见使用物模型通信)和自定义 Topic。自定义 Topic 由用户在控制台定义,用于传输任意格式的业务数据,平台不做物模型校验。
Topic 格式
自定义 Topic 的完整格式:
/{ProductKey}/{DeviceName}/user/{TopicShortName}其中 {TopicShortName} 为自定义 Topic 的后缀,需先在控制台配置,否则设备发布或平台下发时将报错 2012000000(自定义 Topic 未配置)。
操作步骤
1. 配置自定义 Topic
- 在 物联网 > 产品管理 列表中,单击目标产品进入产品详情。
- 在 Topic类列表 的 自定义Topic 页签中,单击 新增,输入自定义 Topic 后缀(TopicShortName),如
data/report,保存后该产品下所有设备均可使用。
2. 设备发布消息(上行)
设备向自定义 Topic 发布消息,params 内容为任意字符串(可以是 JSON 字符串),平台不做业务解析、不触发规则引擎、也不回复,仅记录原始报文。
示例:设备发布到 /{ProductKey}/{DeviceName}/user/data/report:
{ "temp": 23.6, "humi": 60 }发布后可在控制台设备详情的 消息记录 中看到原始报文,以及一条 code=200 的云端日志。
3. 平台下发消息(下行)
在控制台设备管理中选择目标设备进行自定义发布,平台向 /{ProductKey}/{DeviceName}/user/{TopicShortName} 发布(QoS 0),报文包装格式:
{
"id": "123456789012345678",
"timestamp": 1700000000000,
"messageContent": "{\"temp\":23.6,\"humi\":60}"
}注意
messageContent 是字符串类型(内容可能是 JSON 字符串),设备收到后需自行二次解析。
设备需提前订阅该 Topic(平台不自动订阅),并按 id 做幂等处理。
三类 Topic 对比
| 对比项 | 物模型 Topic | 自定义 Topic |
|---|---|---|
| 是否需要预先定义 | 需在物模型中定义属性/事件/服务 | 需在控制台配置 TopicShortName |
| 报文格式 | 统一 JSON 信封(id/version/sys/params/method) | 上行任意;下行包装在 messageContent 字符串中 |
| 数据校验 | 按物模型类型校验后入库属性/事件记录 | 不校验,仅记录原始报文 |
| 规则引擎 | 触发属性/事件规则 | 不触发 |
| 平台回复 | 可选(sys.ack=1) | 无 |
| 适用场景 | 结构化设备数据、告警、远程控制 | 自定义协议透传、二进制或私有格式数据 |
下一步
完成快速入门后,建议继续阅读 MQTT设备接入 章节,了解完整的接入协议、签名算法、设备影子、OTA 与故障排查。