产品动态
设备影子数据流
设备影子 Topic
设备影子充当中介，支持设备和用户应用程序查看和更新设备状态。设备、用户应用程序、设备影子三者之间通过两个特殊的 Topic 来实现通信：
**
$shadow/operation/${productId}/${deviceName}**：用于发布（上行）消息，可实现对设备影子数据的 get/update 操作。**
$shadow/operation/result/${productId}/${deviceName}**：用于订阅（下行）消息，影子服务端通过此 Topic 发送应答和推送消息。说明：
以上主题均为设备创建时由系统默认创建，设备 SDK 内部会自动订阅上述主题。
设备获取影子状态
如果设备想要获取设备影子最近的状态时，需要向
$shadow/operation/${productId}/${deviceName} 主题发布 get 消息。SDK 会提供 API 发送 get 消息，get 消息使用特定的 JSON 字符串格式：{"type": "get","clientToken": "clientToken"}
说明：
clientToken 是用于唯一标识会话业务的 TOKEN ，由请求端生成，应答端原样传回。
例如：空调设备，可以通过 SDK 提供的 API 向
$shadow/operation/ABC1234567/AirConditioner 发送 get 消息，获取最新的设备参数。设备影子服务端通过向
$shadow/operation/result/${productId}/${deviceName} 主题发布消息进行响应，通过 JSON 数据返回设备影子所有数据内容，SDK 会通过相应的回调函数通知业务层。影子服务端通过向
$shadow/operation/result/ABC1234567/AirConditioner 发送下列数据来响应空调设备的 get 请求。示例代码如下：{"type": "get","result": 0,"timestamp": 1514967088,"clientToken": "clientToken","payload": {"state": {"reported": {"temperature": 27},"desired": {"temperature": 25},"delta": {"temperature": 25}},"metadata": {"reported": {"temperature": {"timestamp": 1514967066}},"desired": {"temperature": {"timestamp": 1514967076}},"delta": {"temperature": {"timestamp": 1514967076}}},"version": 1,"timestamp": 1514967076}}
如果设备影子文档中有 desired 部分，则设备影子服务会自动生成相应的 delta 部分。如果没有 desired 部分，则没有 desired 和 delta 部分的内容。
说明：
设备影子服务 不存储 delta 消息。
设备更新影子
设备通过向
$shadow/operation/${productId}/${deviceName} 主题发送 update 消息，告知设备影子服务端其当前状态。SDK 提供相应的 API 发送 update 消息，业务层只需指定 reported 字段的内容。消息内容使用特定的 JSON 字符串格式。空调设备向
$shadow/operation/ABC1234567/AirConditioner 发送 update 消息以报告设备当前的设备状态。示例代码如下：{"type": "update","state": {"reported": {"temperature": 27}},"version": 1,"clientToken": "clientToken"}
当设备影子服务端收到此消息时，首先判断消息中的 version 是否与设备影子服务端中的 version 一致。如果一致，则设备影子服务端执行更新设备影子流程。
影子服务端向空调设备应答消息。示例代码如下：
{"type": "update","result": 0,"timestamp": 1514967066,"clientToken": "clientToken","payload": {"state": {"reported": {"temperature": 27}},"metadata": {"reported": {"temperature": {"timestamp": 1514967066}}},"version": 2,"timestamp": 1514967066}}
如果消息中的 version 与设备影子服务端的 version 不一致，则设备影子服务向
$shadow/operation/result/ABC1234567/AirConditioner 发送以下消息进行回应。{"type": "update","result": 5005,"timestamp": 1514967066,"clientToken": "clientToken","payload": {"state": {"reported": {"temperature": 27,"mode": "cool"}},"metadata": {"reported": {"temperature": {"timestamp": 1514967066},"mode": {"timestamp": 1514967050}}},"version": 2,"timestamp": 1514967066}}
此时 payload 中的内容将返回完整的设备影子文档内容。
应用程序更新影子
用户应用程序通过 HTTP RESTful API 修改设备影子 desired 字段。
用户应用程序通过 HTTP RESTful API 修改空调运行参数。示例代码如下：
{"type": "update","state": {"desired": {"temperature": 25}},"version": 2,"clientToken": "clientToken"}
当设备影子服务端收到此消息后，首先判断消息中的 version 是否与设备影子服务端中的 version 一致。如果一致，则执行更新设备影子流程，并通过 HTTP RESTful API 给应用程序应答 JSON 消息。
{"type": "update","result": 0,"timestamp": 1514967076,"clientToken": "clientToken","payload": {"state": {"desired": {"temperature": 25}},"metadata": {"desired": {"temperature": {"timestamp": 1514967076}}},"version": 3,"timestamp": 1514967076}}
另外，影子服务端通过向
$shadow/operation/result/ABC1234567/AirConditioner 发送 delta 消息。{"type": "delta","timestamp": 1514967076,"payload": {"state": {"temperature": 25},"metadata": {"temperature": {"timestamp": 1514967076}},"version": 3,"timestamp": 1514967076}}
SDK 通过相应的回调函数通知业务层消息已收到。
设备应答 delta 消息
当设备收到 delta 消息后，业务层可以将 desired 字段内容置空并发送给设备影子服务端，表示设备已经 响应 本次 delta 消息，方式是通过向
$shadow/operation/${productId}/${deviceName} 主题发送消息。例如：空调调整温度后，向
$shadow/operation/ABC1234567/AirConditioner 发送消息：{"type": "update","state": {"desired": null},"version": 3,"clientToken": "clientToken"}
SDK 提供相应的 API 发送上述消息。当设备影子服务端收到该消息后，会将 desired 字段内容清除，防止由于 reported 与 desired 中属性值不同引起的重复下发。
影子服务端收到消息后，通过向:
$shadow/operation/result/${productId}/${deviceName} 发送应答消息。例如：影子服务端收到空调的
"desired":null 消息后，通过向 $shadow/operation/result/ABC1234567/AirConditioner 发送更新设备影子文档成功的消息。{"type": "update","result": 0,"timestamp": 1514967086,"clientToken": "clientToken","payload": {"state": {"reported": {"temperature": 25},"desired": null},"metadata": {"reported": {"temperature": {"timestamp": 1514967086}},"desired": {"temperature": {"timestamp": 1514967086}}},"version": 4,"timestamp": 1514967086}}
如果设备 reported 某些属性字段为 null，则代表要将设备影子中相应的字段删除。update 成功时，返回的 payload 内容中，字段仅包含对此次更新字段的相关内容。
如果设备 update 时携带上的 version 值小于服务端上保存的 version 值，则代表设备上的数据是旧的。此时服务端将发送失败消息，其中的返回码（ result 字段）会明确告知 SDK 本次 update 失败，原因是 version 版本过低，同时在 payload 中携带最新的内容一同下发给设备端。
文档反馈