物联网开发平台
有奖捉虫：办公协同&微信生态&物联网文档专题 HOT
文档中心 > 物联网开发平台 > 应用端开发指南 > 应用端 API > 长连接通信 > 设备状态推送

设备状态推送

最近更新时间：2023-07-17 18:02:12

我的收藏

本页目录：

1. 接口描述

接口请求域名：wss://iot.cloud.tencent.com/iotstudio_v2_weapp_1
设备状态推送用于在小程序或 App 实时获取用户绑定设备的上下线状态、设备上报的属性与事件以及设备行为执行结果。需要成功调用注册设备监听接口，通过监听 WebSocket 的 OnMessage 获取设备状态与属性值的实时推送，若获取到的 event.data.push 为 true，则代表该条消息为设备状态变更的主动推送。

2. 输入参数

名称
类型
描述
push
Boolean
该条消息为设备状态变更的主动推送。
action
String
固定为 DeviceChange，代表设备状态变更。
params
String
返回设备信息，详细说明见 消息类型说明。

3. 输出参数

名称
类型
描述
RequestId
String
请求 ID。

4. 示例

应用端 ws 订阅设备状态变化

请求示例
  ws.onmessage = (event) => {
    let data;
    try {
      data = JSON.parse(event.data);
    } catch (e) {
      console.log(`onMessage parse event.data error: ${event.data}`);
      return;
    }

    if (data.push) {
      this.emit('push', data);
    } else if (typeof data.reqId !== 'undefined' && this.requestHandlerMap.has(data.reqId)) {
      this.requestHandlerMap.get(data.reqId)(null, data);
    }
  };
输入参数示例：
{
	"action": "DeviceChange",
	"params": {
		"Time": "2023-07-13T14:19:48+08:00",
		"Type": "Property",
		"SubType": "Report",
		"Topic": "$thing/up/property/productId/deviceName",
		"Payload": "ey******iOjQwfX0=",
		"Seq": 1689229188406,
		"DeviceId": "productId/deviceName"
	},
	"push": true
}
输出示例: 成功
{
	"Response": {
		"RequestId": "up03"
	}
}

5. params 参数说明

参数名称
参数类型
说明
Time
String
时间，UTC 格式，如： 2023-07-13T14:19:48+08:00。
Type
String
消息类型，详见 Type 类型说明。
SubType
String
消息子类型，详见 SubType 类型说明。
Topic
String
消息 Topic，.
可登录 物联网开发平台控制台 进入目标产品开发页，选择设备开发 > Topic 列表来查看。
Payload
String
消息体 base64 编码内容。详见 Payload 说明。
Seq
Int64
序列号。
DeviceId
String
设备 ID，产品 ID/deviceName 格式。

Type 类型说明

Type 类型
描述
StatusChange
设备状态变化消息，包括设备上线与下线消息通知。
Shadow
影子消息。
Property
属性消息。
Template
物模型消息。
Event
事件消息。
Action
行为消息。
UserDefined
用户自定义。

SubType 说明

SubType 类型
描述
Online
设备上线。
Offline
设备下线。
Report
设备上报。
Push
服务端推送到设备。

Payload 说明

Payload 是消息体 base64 编码后字符串。示例如下：
消息体：
 {
	"method": "control",
	"clientToken": "12345678",
	"params": {
		"switch": 0
	}
}
base64编码：
"Payload": "eyJtZXRob2QiOiJjb250cm9sIiwiY2xpZW50VG9rZW4iOiIxMjM0NTY3OCIsInBhcmFtcyI6eyJzd2l0Y2giOjB9fQ=="

Template 消息示例

物模型消息 Topic 为空，Payload 是消息 base64 编码后内容。
 {
	"action": "DeviceChange",
	"params": {
		"Time": "2023-07-13T15:00:11+08:00",
		"Type": "Template",
		"SubType": "Push",
		"Topic": "",
		"Payload": "eyJtZXRob2QiOiJjb250cm9sIiwiY2xpZW50VG9rZW4iOiIxMjM0NTY3OCIsInBhcmFtcyI6eyJzd2l0Y2giOjB9fQ==",
		"Seq": 1689231611907,
		"DeviceId": "productId/deviceName"
	},
	"push": true
}
Payload base64 解码消息体
详细说明见 物模型。
 {
	"method": "control",
	"clientToken": "12345678",
	"params": {
		"switch": 0
	}
}

Event 消息示例

  {
    "Time": "2019-04-11T20:42:36+08:00",
    "Type": "Event",
    "SubType": "Report",
    "Topic": "$thing/up/event/US4CJ11DIK/LIAO",
    "Payload": "ewogICAgICAgICJtZXRob2QiOiAiZXZlbnRfcG9zdCIsCiAgICAgICAgInZlcnNpb24iOiAiMS4wIiwKICAgICAgICAiZXZlbnRJZCI6ICJsb3dfdm9sdGFnZSIsCiAgICAgICAgInBhcmFtcyI6IHsKICAgICAgICAgICAgInZvbHRhZ2UiOiAyLjI3ODA4MQogICAgICAgIH0sCiAgICAgICAgImNsaWVudFRva2VuIjogImNsaWVudFRva2VuLTU1OSJ9",
    "Seq": 300,
    "DeviceId": "US4CJ11DIK/LIAO"
  }
Payload base64 解码消息体
  {
    "method": "event_post",
    "version": "1.0",
    "eventId": "low_voltage",
    "params": {
      "voltage": 2.278081
    },
    "clientToken": "clientToken-559"
  }

属性消息示例

  {
    "Time": "2019-10-30T10:41:00+08:00",
    "Type": "Property",
    "SubType": "Report",
    "Topic": "$thing/up/property/WTJTZX0MF2/device_property001",
    "Payload": "eyJ0aW1lc3RhbXAiOiAwLCAicGFyYW1zIjogeyJicmlnaHRuZXNzIjogNTl9LCAibWV0aG9kIjogInJlcG9ydCIsICJjbGllbnRUb2tlbiI6ICJ0bTIwMTkxMDMwMTA0MDUzXzEifQ==",
    "Seq": 6,
    "DeviceId": "WTJTZX0MF2/device_property001"
  }
Payload base64 解码消息体
  {
    "method": "report",
    "params": {
      "timestamp": 0,
      "params": {
        "brightness": 59
      },
      "method": "report",
      "clientToken": "tm20191030104053_1"
    }
  }

StatusChange 消息示例

设备上线消息。
  {
    "Time": "2019-03-28T15:17:33+08:00",
    "Type": "StatusChange",
    "SubType": "Online",
    "Topic": "",
    "Payload": "",
    "Seq": 6
  }
设备下线。
  {
    "Time": "2019-03-28T15:17:33+08:00",
    "Type": "StatusChange",
    "SubType": "Offline",
    "Topic": "",
    "Payload": "",
    "Seq": 7
  }

Action 行为示例

Action 消息推送示例
  {
    "Time": "2021-05-13T21:34:05+08:00",
    "Type": "Action",
    "SubType": "Push",
    "Topic": "",
    "Payload": "eyJtZXRob2QiOiJhY3Rpb24iLCJjbGllbnRUb2tlbiI6IjEzNjk0NzQ5Mzo6cmVxXzEiLCJhY3Rpb25JZCI6ImxpZ2h0X2JsaW5rIiwidGltZXN0YW1wIjoxNjIwOTEyODQ1LCJwYXJhbXMiOnsiY29sb3IiOjEsInRpbWUiOjYsInRvdGFsX3RpbWUiOjYwfX0K",
    "Seq": 1620912845,
    "DeviceId": "0CPSFIRP28/testble"
  }
Payload base64 解码消息体
  {
    "method": "action",
    "clientToken": "136947493::req_1",
    "actionId": "light_blink",
    "timestamp": 1620912845,
    "params": {
      "color": 1,
      "time": 6,
      "total_time": 60
    }
  }
Action 消息 report 示例
  {
    "Time": "2021-05-13T21:34:05+08:00",
    "Type": "Action",
    "SubType": "Report",
    "Topic": "",
    "Payload": "eyJtZXRob2QiOiJhY3Rpb25fcmVwbHkiLCJjbGllbnRUb2tlbiI6IjEzNjk0NzQ5Mzo6cmVxXzEiLCJjb2RlIjowLCJzdGF0dXMiOiJzdWNjIiwicmVzcG9uc2UiOnsicmVzdWx0IjogMX19",
    "Seq": 1620912845,
    "DeviceId": "0CPSFIRP28/testble"
  }
Payload base64 解码消息体
  {
    "method": "action_reply",
    "clientToken": "136947493::req_1",
    "code": 0,
    "status": "succ",
    "response": {
      "result": 1
    }
  }


中国站