MQTT 应用端订阅

约 1527 字大约 5 分钟

MQTT 应用端订阅

ThingsCloud 支持开放的 MQTT 应用端订阅服务，适用于您在自有软件应用或第三方应用中实时接收设备的最新消息。

您不仅可以在服务器上订阅设备消息，也可以在基于浏览器的 Web 应用中通过 Javascript 和 MQTT@Websocket 直接订阅设备实时消息，来实现 Web 页面实时更新设备数据，这在开发物联网数据可视化界面时发挥重要的作用。

提示

ThingsCloud 提供的 MQTT 应用端订阅服务，和设备的 MQTT 接入并不是同一个 MQTT 服务，请您使用专用的 MQTT 应用端订阅服务地址和主题。

MQTT 应用端订阅功能对企业版及以上付费版项目开放。

示例代码

示例代码展示了如何使用 ThingsCloud MQTT 应用端订阅服务，通过程序代码实现订阅设备实时消息的功能。

支持订阅哪些消息？

应用端通过 MQTT 应用端订阅可以获得的消息包括：

设备属性变化（包括属性上报、属性下发、云端属性更新）
设备事件上报
设备命令回复
设备自定义数据上报
设备告警/恢复
设备上线/断开

如何获得 MQTT 连接参数

在 项目 > 设置 > MQTT 应用端订阅 中，可以获得 MQTT 连接参数，包括：

参数	说明
MQTT 地址	包含服务器地址和端口号。采用 wss:// 连接方式，支持服务器端或网页端使用。
Username	使用 `ProjectViewKey`
Password	使用 `ProjectViewSecret`

MQTT 订阅主题

以下主题中的字段说明：

<ProjectViewKey>：项目内唯一，可在 项目 > MQTT 应用端订阅 中获得。
<DeviceViewToken>：每个设备唯一，可在设备详情页中获取，或通过项目 HTTP API 获取。
+：表示通配符的主题，可订阅项目中的所有设备。

订阅指定设备属性变化

<ProjectViewKey>/<DeviceViewToken>/attributes

订阅接收的消息为 JSON 格式，举例如下：

{
  "attributes": {   // 设备属性 JSON
    ...
  },
  "device": {   // 设备信息
    "id": "<id>",
    "name": "<name>"
  },
  "ts": <timestamp> // 消息发送时间，单位：毫秒
}

订阅项目内所有设备属性变化

<ProjectViewKey>/+/attributes

订阅接收的消息格式同上。

订阅指定设备事件上报

<ProjectViewKey>/<DeviceViewToken>/event/report

订阅接收的消息为 JSON 格式，举例如下：

{
  "event": {   // 设备事件 JSON
    "method": "<method>",   // 事件标识符
    "params": {   // 事件参数 JSON
      ...
    },
    "id": "<id>"   // 事件 ID
  },
  "device": {   // 设备信息
    "id": "<id>",
    "name": "<name>"
  },
  "ts": <timestamp> // 消息发送时间，单位：毫秒
}

订阅项目内所有设备事件上报

<ProjectViewKey>/+/event/report

订阅接收的消息格式同上。

订阅指定设备命令回复

<ProjectViewKey>/<DeviceViewToken>/command/reply

订阅接收的消息为 JSON 格式，举例如下：

{
  "command_reply": {   // 设备命令回复 JSON
    "method": "<method>",   // 命令标识符
    "params": {   // 回复参数 JSON
      ...
    },
    "id": "<id>"   // 命令 ID
  },
  "device": {   // 设备信息
    "id": "<id>",
    "name": "<name>"
  },
  "ts": <timestamp> // 消息发送时间，单位：毫秒
}

订阅项目内所有设备命令回复

<ProjectViewKey>/+/command/reply

订阅接收的消息格式同上。

订阅指定设备自定义数据上报

<ProjectViewKey>/<DeviceViewToken>/data

订阅接收的消息为 JSON 格式，以接收 HEX 16进制数据类型为例，举例如下：

{
  "data": {   // 设备自定义数据
    "custom_topic_identifier": "stream",    // 自定义数据流标识符
    "format_type": "hex",                   // 自定义数据流数据类型
    "topic": "data/stream",                 // 自定义数据流主题
    "msg": "010304010E01CA1BCB"             // 自定义数据内容
  },
  "device": {   // 设备信息
    "id": "<id>",
    "name": "<name>"
  },
  "ts": <timestamp> // 消息发送时间，单位：毫秒
}

以接收 JSON 格式的自定义数据流为例，举例如下：

{
  "data": {   // 设备自定义数据
    "custom_topic_identifier": "stream",    // 自定义数据流标识符
    "format_type": "json",                   // 自定义数据流数据类型
    "topic": "data/stream",                 // 自定义数据流主题
    "msg": {   // 自定义 JSON 数据内容
        ...
    }
  },
  "device": {   // 设备信息
    "id": "<id>",
    "name": "<name>"
  },
  "ts": <timestamp> // 消息发送时间，单位：毫秒
}

订阅项目内所有设备自定义数据上报

<ProjectViewKey>/+/data

订阅接收的消息格式同上。

订阅指定设备告警消息

<ProjectViewKey>/<DeviceViewToken>/alarm

包含设备告警触发和告警恢复的消息。

订阅接收的消息为 JSON 格式，举例如下：

{
  "rule": {     // 告警规则信息
    "id": "<id>",
    "name": "<name>"
  },
  "alarm": {    // 告警状态
    "ts": 1758617649865,    // 告警触发或恢复时间，单位：毫秒
    "status": 1,             // 当前告警状态，1 表示触发，0 表示恢复
    "level": 1              // 告警级别：1 普通告警，2 重要告警，3 紧急告警。告警恢复时无该字段。
  },
  "device": {   // 设备信息
    "id": "<id>",
    "name": "<name>"
  },
  "ts": <timestamp> // 消息发送时间，单位：毫秒
}

订阅项目内所有设备告警消息

<ProjectViewKey>/+/alarm

包含设备告警触发和告警恢复的消息。

订阅接收的消息格式同上。

订阅指定设备上线/断开通知

<ProjectViewKey>/<DeviceViewToken>/online

包含设备上线和断开的通知。

需要注意的是，若设备端非主动断开连接，平台不会发送断开通知。关于设备在线和离线状态的详细规则，请参考设备在线状态。

订阅接收的消息为 JSON 格式。

设备端连接到平台时，发送上线通知，举例如下：

{
  "online": {     // 设备上线
    "status": "online",
  },
  "device": {   // 设备信息
    "id": "<id>",
    "name": "<name>"
  },
  "ts": <timestamp> // 消息发送时间，单位：毫秒
}

设备端主动断开连接时，发送断开通知，举例如下：

{
  "online": {     // 设备断开
    "status": "offline",
  },
  "device": {   // 设备信息
    "id": "<id>",
    "name": "<name>"
  },
  "ts": <timestamp> // 消息发送时间，单位：毫秒
}

订阅项目内所有设备上线/断开通知

<ProjectViewKey>/+/online

包含设备上线和断开的通知。

订阅接收的消息格式同上。