跳至主要内容

Topic 与报文约定

大约 4 分钟

Topic 与报文约定

本文定义设备与平台之间的 Topic 规则与 JSON 报文格式。

变量约定

变量含义
{pk}productKey
{dn}deviceName
{id}设备生成的消息 ID（字符串），回复时原样带回
{block}自定义模块标识，默认模块为空
{identifier}物模型属性/事件/服务标识
{messageId}平台 RRPC 调用生成的 18 位随机 ID

报文公共字段

上行统一 JSON 信封（字段大小写敏感）：

字段类型必填说明
idstring建议消息唯一 ID，回复中原样返回；缺失时回复的 id 为字符串 "null"
versionstring否协议版本，一般 "1.0"，平台当前不校验
sys.ackint否1 需要平台回复，0 不回复；属性/事件/诊断默认 0，日志与日志配置默认 1
paramsobject/array是业务数据
methodstring建议与阿里云 IoT 对齐，便于排查；平台按 Topic 分发，method 内容不参与判定

下行回复公共字段：id、code、message、data。

重要：属性/事件上报的 code:200 只代表「平台已收到并可解析 JSON」，不代表数据校验通过。 回复在下发前就已按 200 组装，具体属性的 TSL 校验结果只写入该设备的云端日志。

Topic 总表

上行（设备发布）

用途Topic平台匹配方式QoS 建议
属性上报/sys/{pk}/{dn}/thing/event/property/post全等0/1
事件上报/sys/{pk}/{dn}/thing/event/{identifier}/post前缀 /sys/{pk}/{dn}/thing/event/ 且以 /post 结尾1
事件上报（自定义模块）/sys/{pk}/{dn}/thing/event/{block}:{identifier}/post同上1
属性设置回复/sys/{pk}/{dn}/thing/service/property/set_reply全等1
服务调用回复（推荐）/ext/rrpc/{messageId}/sys/{pk}/{dn}/thing/service/{identifier}Topic 含 /ext/rrpc/1
服务调用回复（兼容）/sys/{pk}/{dn}/rrpc/response/{messageId}Topic 含 /rrpc/response/1
网络诊断/sys/{pk}/{dn}/_thing/diag/post全等0/1
本地日志上报/sys/{pk}/{dn}/thing/log/post全等1
获取日志配置/sys/{pk}/{dn}/thing/config/log/get全等1
信号强度上报/{pk}/{dn}/signal/report以 signal/report 结尾0
位置上报/{pk}/{dn}/location/upload以 location/upload 结尾0/1
OTA 版本上报/ota/device/inform/{pk}/{dn}全等1
OTA 进度上报/ota/device/progress/{pk}/{dn}全等1
OTA 主动获取固件/sys/{pk}/{dn}/thing/ota/firmware/get全等1
OTA 拉取固件（遗留）/{pk}/{dn}/firmware/pull以 firmware/pull 结尾，回复通道未接通，勿用—
影子上报/查询/删除/shadow/update/{pk}/{dn}全等1
自定义 Topic/{pk}/{dn}/user/{topicShortName}不解析业务，仅入库原始记录0/1

注意：批量属性 /sys/{pk}/{dn}/thing/event/property/batch/post 与历史属性 .../property/history/post 当前未实现，且会被上面的事件分支按「事件」处理（identifier 解析为 property/batch 等），请勿使用。

下行（设备订阅）

用途TopicQoS触发条件
属性设置/sys/{pk}/{dn}/thing/service/property/set0后台下发
服务调用（异步）/sys/{pk}/{dn}/thing/service/{identifier} 或 …/{block}:{identifier}0后台异步调用
服务调用（同步 RRPC）/ext/rrpc/{messageId}/sys/{pk}/{dn}/thing/service/{identifier}0后台同步调用
属性上报回复/sys/{pk}/{dn}/thing/event/property/post_reply1sys.ack=1
事件上报回复/sys/{pk}/{dn}/thing/event/{block:identifier}/post_reply1sys.ack=1
诊断回复/sys/{pk}/{dn}/_thing/diag/post_reply1sys.ack=1
日志上报回复/sys/{pk}/{dn}/thing/log/post_reply1默认需要回复
日志配置回复/sys/{pk}/{dn}/thing/config/log/get_reply1默认需要回复
日志配置下发/sys/{pk}/{dn}/thing/config/log/push1后台开关本地日志
影子回复/期望下发/shadow/get/{pk}/{dn}1影子请求或后台修改影子
OTA 升级指令（批量）/ota/device/upgrade/{pk}/{dn}1批次推送/设备查询
OTA 固件信息回复/sys/{pk}/{dn}/thing/ota/firmware/get_reply1设备主动查询
简易升级指令（遗留）/{pk}/{dn}/firmware/upgrade0勿用，见已知限制
固件拉取回复（遗留）/{pk}/{dn}/firmware/pull/reply0勿用
自定义 Topic 下发/{pk}/{dn}/user/{topicShortName}0后台自定义发布

设备必须自行订阅

平台侧的自动订阅逻辑（autoSubscribe）已整体停用，设备连接后必须自己 SUBSCRIBE 需要的下行 Topic，否则收不到任何设置、服务调用与 OTA 指令。

推荐订阅清单（QoS 填 1，按实际裁剪）：

/sys/{pk}/{dn}/thing/service/property/set
/sys/{pk}/{dn}/thing/service/+
/ext/rrpc/+/sys/{pk}/{dn}/thing/service/+
/sys/{pk}/{dn}/thing/event/+/post_reply
/sys/{pk}/{dn}/_thing/diag/post_reply
/sys/{pk}/{dn}/thing/log/post_reply
/sys/{pk}/{dn}/thing/config/log/get_reply
/sys/{pk}/{dn}/thing/config/log/push
/sys/{pk}/{dn}/thing/ota/firmware/get_reply
/ota/device/upgrade/{pk}/{dn}
/shadow/get/{pk}/{dn}
/{pk}/{dn}/user/+

注意事项：

  • + 只匹配一层。/sys/{pk}/{dn}/thing/service/+ 匹配不到 …/thing/service/property/set（多一层），所以属性设置必须单独订阅。
  • {block}:{identifier} 中的 : 属于同一层，+ 可以匹配。
  • 不要订阅 /sys/{pk}/{dn}/#，否则设备会收到自己发布的上行消息形成回环。
  • 每次重连（cleanSession=true）都要重新订阅。

QoS 与可靠性

  • 平台下行属性设置、服务调用、自定义下发使用 QoS0：不重发、不保证送达。设备需按 id 做幂等，并建议在业务侧超时重试或主动读取影子。
  • 平台下行回复类、OTA 类、影子类使用 QoS1。设备需按 id 去重。
  • 设备上行建议事件、日志、OTA 用 QoS1；属性高频上报可用 QoS0 以省流量。
  • 平台不会替设备缓存离线期间的 QoS0 消息；离线期间的关键配置请通过影子（设备影子）同步。
小李子科技