三、影子设备

设备影子概览

物联网平台提供设备影子功能，用于缓存设备上报的状态数据和应用程序下发的指令信息。设备在线时，可以直接获取物联网平台指令；设备离线后，再次上线可以主动拉取物联网平台指令。本文主要介绍设备影子的应用场景和使用方法。

什么是设备影子

设备影子是一个JSON文档，用于存储设备上报状态数据和应用程序期望状态信息。JSON数据格式的详细说明，请参见设备影子JSON详解。

每个设备有且只有一个设备影子，设备可以通过MQTT获取和设置设备影子来同步状态，该同步可以是影子同步给设备，也可以是设备同步给影子。

应用场景

在以下场景中，您可选择使用设备影子功能，获取设备上报数据和应用程序期望数据。

应用程序请求获取设备状态。

场景描述：

设备网络不稳定，设备频繁上下线，无法正常响应应用程序的请求。设备网络稳定，同时响应多个应用程序的请求，即使响应的结果一样，设备本身处理能力有限，也会无法负载多次请求。使用设备影子机制，设备状态变更，只需同步状态给设备影子一次，应用程序请求获取设备状态，不论应用程序请求数量，和设备是否联网在线，都可从设备影子中获取设备当前状态，实现应用程序与设备解耦。

应用程序获取设备影子中状态的流程图如下，其中数据流转过程，请参见设备主动上报状态。

应用程序下发指令给设备，变更设备状态。

场景描述：设备处于下线状态，或设备网络不稳定，设备频繁上下线，应用程序发送控制指令给设备，设备不在线，指令就会发送失败。

使用设备影子机制，可以将应用程序下发的指令，携带时间戳存储到设备影子中。设备再上线时，获取设备影子中指令，并根据时间戳确定是否执行。

应用程序更新设备状态的流程图如下，其中数据流转过程，请参见应用程序改变设备状态、设备主动获取影子内容、设备主动删除影子属性。

设备影子JSON详解

设备影子JSON文档示例：

{
    "state": {
        "desired": {
            "color": "RED", 
            "sequence": [
                "RED", 
                "GREEN", 
                "BLUE"
            ]
        }, 
        "reported": {
            "color": "GREEN"
        }
    }, 
    "metadata": {
        "desired": {
            "color": {
                "timestamp": 1469564492
            }, 
            "sequence": {
                "timestamp": 1469564492
            }
        }, 
        "reported": {
            "color": {
                "timestamp": 1469564492
            }
        }
    }, 
    "timestamp": 1469564492, 
    "version": 1
}

JSON属性描述，如下表所示。

属性	描述
desired	设备的预期状态。仅当设备影子文档具有预期状态时，才包含desired部分。应用程序向desired部分写入数据，更新事物的状态，而无需直接连接到该设备。
reported	设备的报告状态。设备可以在reported部分写入数据，报告其最新状态。应用程序可以通过读取该参数值，获取设备的状态。 JSON文档中也可以不包含reported部分，没有reported部分的文档同样为有效影子JSON文档。
metadata	当用户更新设备状态文档后，设备影子服务会自动更新metadata的值。设备状态的元数据的信息包含以 Epoch 时间表示的每个属性的时间戳，用来获取准确的更新时间。
timestamp	影子文档的最新更新时间。
version	用户主动更新版本号时，设备影子会检查请求中的version值是否大于当前版本号。如果大于当前版本号，则更新设备影子，并将version值更新到请求的版本中，反之则会拒绝更新设备影子。该参数更新后，版本号会递增，用于确保正在更新的文档为最新版本。 version参数为long型。为防止参数溢出，您可以手动传入-1将版本号重置为0。

设备影子支持数组。更新数组时必须全量更新，不能只更新数组的某一部分。

更新数组数据示例：初始状态：

{
    "reported" : { 
        "colors" : [
            "RED", 
            "GREEN",
            "BLUE" 
        ]
    }
}

更新：

{
    "reported" : {
        "colors" : [
            "RED"
        ] 
    }
}

最终状态：

{
    "reported" : {
        "colors" : [
            "RED"
        ] 
    }
}

设备影子数据流

设备影子数据通过Topic进行流转，主要包括设备上报状态到设备影子、应用程序更改设备状态、设备离线再上线后主动获取设备影子信息，和设备端请求删除设备影子中的属性信息。本文介绍设备影子Topic及其数据格式。

设备影子Topic

物联网平台已为每个设备预定义了两个Topic，用于实现设备影子数据流转。

/shadow/update/${YourProductKey}/${YourDeviceName}

设备和应用程序发布消息到此Topic。物联网平台收到该Topic的消息后，将消息中的状态更新到设备影子中。

/shadow/get/${YourProductKey}/${YourDeviceName}

设备影子更新状态到该Topic，设备订阅此Topic获取最新消息。

使用示例

本文以灯泡设备为例，说明设备、设备影子以及应用程序之间的通信，主要介绍设备主动上报状态、应用程序改变设备状态、设备主动获取影子内容，和设备主动删除影子属性。

示例中，产品的ProductKey是a1PbRCF****；设备名称DeviceName是lightbulb。设备以QoS=1发布消息和订阅两个设备影子Topic。

设备主动上报状态

设备在线时，主动上报设备状态到影子，应用程序主动获取设备影子状态。

数据流转过程如下图所示。

当灯泡lightbulb上线时，使用Topic /shadow/update/a1PbRCF****/lightbulb上报最新状态到影子。发送的JSON消息格式：

{
    "method": "update", 
    "state": {
        "reported": {
            "color": "red"
        }
    }, 
    "version": 1
}

上报参数说明参数说明 method 表示设备或者应用程序请求设备影子时的操作类型。当执行更新操作时，method为必填字段，设置为update。

state 表示设备发送给设备影子的状态信息。 reported为必填字段，状态信息会同步更新到设备影子的reported部分。

version 表示设备影子检查请求中的版本信息。只有当新版本大于当前版本时，设备影子才会接收设备端的请求，并更新设备影子版本。

如果version设置为-1时，表示清空设备影子数据，设备影子会接收设备端的请求，并将设备影子版本更新为0。

2.设备影子接收到灯泡上报的状态数据后，更新影子文档。

{
    "state": {
        "reported": {
            "color": "red"
        }
    }, 
    "metadata": {
        "reported": {
            "color": {
                "timestamp": 1469564492
            }
        }
    }, 
    "timestamp": 1469564492, 
    "version": 1
}

影子文件更新后，设备影子会返回结果给设备（灯泡），即发送消息到设备订阅的Topic /shadow/get/a1PbRCF****/lightbulb中。

若更新成功，发送到该Topic中的消息为：

{
    "method": "reply", 
    "payload": {
        "status": "success", 
        "version": 1
    }, 
    "timestamp": 1469564576
}

若更新失败，发送到该Topic中的消息为：

  {
    "method": "reply", 
    "payload": {
        "status": "error", 
        "content": {
            "errorcode": "${errorcode}", 
            "errormessage": "${errormessage}"
        }
    }, 
    "timestamp": 1469564576
}

表 2. 错误码说明

errorCode	errorMessage
400	不正确的JSON格式。
401	影子数据缺少method信息。
402	影子数据缺少state字段。
403	影子数据中version值不是数字。
404	影子数据缺少reported字段。
405	影子数据中 reported属性字段为空。
406	影子数据中 method是无效的方法。
407	影子内容为空。
408	影子数据中reported属性个数超过128个。
409	影子版本冲突。
500	服务端处理异常。