物联网通信
有奖捉虫：办公协同&微信生态&物联网文档专题 HOT
文档中心 > 物联网通信 > 开发者手册 > 设备影子 > 设备影子数据流

设备影子数据流

最近更新时间：2023-07-11 11:30:13

我的收藏

本页目录：

设备影子 Topic

设备影子充当中介，支持设备和用户应用程序查看设备状态和更新设备配置。设备、用户应用程序、设备影子三者之间通过两个特殊的 Topic 来实现通信：
$shadow/operation/${productId}/${deviceName}：用于发布（上行）消息，可实现对设备影子数据的 get/update 操作。
$shadow/operation/result/${productId}/${deviceName}：用于订阅（下行）消息，影子服务端通过此 Topic 发送应答和推送消息。
说明：
以上主题均为设备创建时由系统默认创建，设备 SDK 内部会自动订阅上述主题。




设备获取影子

如果设备想要获取设备影子最近的数据时，需要向$shadow/operation/${productId}/${deviceName}主题发布 get 消息，报文格式如下：
{
	"type": "get",
	"clientToken": 8480
}
说明：
clientToken 是用于唯一标识会话业务的 TOKEN ，由设备端生成，物联网通信平台原样传回。
物联网通信平台接收请求后，通过向$shadow/operation/result/${productId}/${deviceName}主题发布消息进行响应，格式如下：
{
	"clientToken": "8480",
	"payload": {
		"state": {
			"delta": {
				"alarmvalue": "50"
			},
			"desired": {
				"alarmvalue": "50"
			},
			"reported": {
				"temperature": 32
			}
		},
		"timestamp": 1678783950012,
		"version": 14
	},
	"result": 0,
	"timestamp": 1678783991,
	"type": "get"
}
如果设备影子文档中有 desired 部分，则物联网通信平台会自动生成相应的 delta 部分。如果没有 desired 部分，则没有 desired 和 delta 部分的内容。

设备更新影子

说明：
消息中的 version 需与平台上保持一致，如果不确定，version 可传0进行不校验 version 更新。
设备通过向$shadow/operation/${productId}/${deviceName}主题发送 update 消息，更新设备影子数据，格式如下：
{
	"type": "update",
	"state": {
		"reported": {
			"temperature": 35
		}
	},
	"version": 0,
	"clientToken": 5551
}
当物联网通信平台收到此消息时，首先判断消息中的 version 是否与设备影子服务端中的 version 一致。如果一致，则设备影子服务端执行更新设备影子流程。
物联网通信平台接收请求后，通过向$shadow/operation/result/${productId}/${deviceName}主题发布消息进行响应，此时 payload 中的内容字段仅包含对此次更新字段的相关内容，格式如下：
{
	"clientToken": "5551",
	"payload": {
		"state": {
			"reported": {
				"temperature": 35
			}
		},
		"timestamp": 1678785359634,
		"version": 15
	},
	"result": 0,
	"timestamp": 1678785359634,
	"type": "update"
}

如果消息中的 version 与设备影子服务端的 version 不一致，则物联网通信平台向 $shadow/operation/result/ABC1234567/AirConditioner发送以下消息进行回应，此时 payload 中的内容将返回完整的设备影子文档内容。
{
	"clientToken": "8734",
	"payload": {
		"state": {
			"desired": {
				"alarmvalue": "50"
			},
			"reported": {
				"temperature": 35
			}
		},
		"timestamp": 1678785359634,
		"version": 15
	},
	"result": 5005,
	"timestamp": 1678785670967,
	"type": "update"
}

如果设备想删除设备影子服务端 reported 中某些字段，可在 update 时，把这些字段内容置为 null，格式如下：
{
	"type": "update",
	"state": {
		"reported": {
			"temperature": null
		}
	},
	"version": 0,
	"clientToken": 6584
}

应用程序更新影子

说明：
消息中的 version 需与平台上保持一致，如果不确定，version 可传0进行不校验 version 更新。
用户应用程序通过 更新设备影子 云API 修改设备影子 desired 字段，进行修改影子数据，进行预配置设备。
当物联网通信平台收到此云API请求后，首先判断请求中 version 是否与设备影子服务端中的 version 一致。如果一致，则执行更新设备影子流程，并响应此云API请求。
应用程序成功修改设备影子 desired 字段后，如果设备此时处于在线状态，物联网通信平台会通过$shadow/operation/result/ABC1234567/AirConditioner向设备发送 delta 消息，设备收到设备影子更新的内容；如果设备此时处于离线状态，上线后，可通过设备获取影子获取 desired 字段内容。
{
	"payload": {
		"state": {
			"alarmvalue": "50"
		},
		"timestamp": 1678786529510,
		"version": 17
	},
	"timestamp": 1678786529510,
	"type": "delta"
}

当设备收到 delta 消息后，设备通过上报 desired 字段为null的消息，清空设备影子服务端 desired 字段内容，方式是通过向$shadow/operation/${productId}/${deviceName}主题发送消息，格式如下：
{
	"type": "update",
	"state": {
		"desired": null
	},
	"version": 0,
	"clientToken": 5686
}

错误码

错误码
描述
5000
参数不完整
5001
影子不存在
5004
非法请求参数
5005
版本不匹配
5007
DB 错误
5008
版本冲突
5009
非法 Topic
5010
影子更新失败
5011
文档大小超过限制
5100
内部错误

中国站