设备影子

概述

物联网平台支持创建设备的“影子”。设备影子是一个JSON文件，用于存储设备的在线状态、设备最近一次上报的设备属性值、应用服务器期望下发的配置。每个设备有且只有一个设备影子，设备可以获取和设置设备影子以此来同步设备属性值，这个同步可以是影子同步给设备，也可以是设备同步给影子。

应用场景

适合资源受限低功耗设备，长期处于休眠状态的场景。

• 查询设备最新上报数据和设备最新在线状态：

  • 当在控制台上查询设备上报数据时，由于设备可能长时间处于离线状态或因网络不稳定掉线，而无法获取到最新数据。通过设备影子机制，设备影子中始终保持设备最新上报的数据和设备当前状态，控制台上只需要查询设备影子中存储的数据，即可获取设备最新上报的数据和设备状态。

  • 很多应用服务器频繁地查询设备在线状态，由于设备处理能力有限，频繁查询会损耗设备性能。使用设备影子机制，设备只需要主动同步状态给设备影子一次，多个应用程序请求设备影子获取设备状态，即可获取设备最新状态，从而将应用程序和设备解耦。

• 修改设备属性值：用户通过“设备 > 设备详情 > 设备影子”修改设备的属性值。由于设备可能长时间处于离线状态，修改设备属性值的操作不能及时下发给设备。在这种情况下，物联网平台可以将修改设备的属性信息存储在设备影子中，待设备上线后，将修改的设备属性值同步给设备，从而完成设备属性值的修改。

业务流程

修改设备属性值

修改desired区属性值，如果设备在线，则设备影子直接同步设备属性值到设备，否则等待设备上线或上报数据时，再同步设备属性值到设备。

1. 用户通过控制台或应用服务器修改设备属性值。消息样例如下：

   PUT https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/shadow
   Content-Type: application/json
   X-Auth-Token: ********
   Instance-Id: ********
   
   {
     "shadow" : [ {
       "desired" : {
         "temperature" : "60"
       },
       "service_id" : "WaterMeter",
       "version" : 1
     } ]
   }

2. 物联网平台修改desired区属性值。
3. 物联网平台返回响应消息。
4. 物联网平台判断设备上线或上报数据。
5. 物联网平台将设备属性同步到设备。消息样例如下：

   Topic: $oc/devices/{device_id}/sys/properties/set/request_id={request_id} 
   数据格式：  
   {
       "object_device_id": "{object_device_id} ",
       "services": [
           {
               "service_id": "Temperature",
               "properties": {
                   "value": 57,
                   "value2": 60
               }
           },
           {
               "service_id": "Battery",
               "properties": {
                   "level": 80,
                   "level2": 90
               }
           }
       ]
   }

6. 设备返回响应消息。设备影子desired区的属性值发送给设备后，需要设备回响应表示已收到请求。消息样例如下：

   Topic：$oc/devices/{device_id}/sys/properties/set/response/request_id={request_id}
   数据格式：  
   {
       "result_code": 0,
       "result_desc": "success"
   }

7.设备上报数据，当设备进行属性上报时，平台会存储设备最新上报的设备属性值。

• 设备上报属性时，物联网平台修改设备影子reported区属性值为设备上报的设备属性值。消息样例如下：

Topic: $oc/devices/{device_id}/sys/properties/report   
数据格式：
{
    "services": [
        {
            "service_id": "Temperature",
            "properties": {
                "value": 57,
                "value2": 60
            },
            "event_time": "20151212T121212Z"
        },
        {
            "service_id": "Battery",
            "properties": {
                "level": 80,
                "level2": 90
            },
            "event_time": "20151212T121212Z"
        }
    ]
}

• 设备主动删除设备影子的reported区
  • 设备主动删除reported区service下的单个属性
    设备上报属性时，将属性设置为null，平台会将该属性从设备影子reported区删除，消息样例如下：

    Topic: $oc/devices/{device_id}/sys/properties/report  
    {
        "services": [
            {
                "service_id": "Temperature",
                "properties": {
                    "value": null,
                    "value2": 60
                },
                "event_time": "20151212T121212Z"
            }
        ]
    }

  • 设备主动删除影子reported区的service下的全部的属性
    设备上报属性时，将service对应的properties设置为{}时，平台会将reported区该service模块下所有属性从设备影子reported区删除，消息样例如下:

    Topic: $oc/devices/{device_id}/sys/properties/report 
    {
        "services": [
            {
                "service_id": "Temperature",
                "properties": {},
                "event_time": "20151212T121212Z"
            }
        ]
    }

查询设备属性值

设备影子保存的是设备最新的设备属性值，一旦设备属性值产生变化，设备会将设备属性值同步到设备影子。用户便可以及时获取查询结果，无需关注设备是否在线。

1. 用户通过控制台或应用服务器查询设备属性值。消息样例如下：

   GET https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/shadow
   Content-Type: application/json
   X-Auth-Token: ********
   Instance-Id: ********

2. 物联网平台返回desired属性值和report属性值，即期望值和上报值。消息样例如下：

   Status Code: 200 OK

   Content-Type: application/json
   
   {
     "device_id" : "********",
     "shadow" : [ {
       "desired" : {
         "properties" : {
           "temperature" : "60"
         },
         "event_time" : "20151212T121212Z"
       },
       "service_id" : "WaterMeter",
       "reported" : {
         "properties" : {
           "temperature" : "60"
         },
         "event_time" : "20151212T121212Z"
       },
       "version" : 1
     } ]
   }

查询、修改、删除设备影子

查询设备影子

方法1：应用服务器调用查询设备影子数据接口。

修改设备影子

方法1：应用服务器调用配置设备影子预期数据接口。

方法2：登录管理控制台，选择您的实例，单击实例卡片进入。在左侧导航栏选择“设备-所有设备”，在设备列表中单击具体的设备进入到设备的详情页面，在“设备影子”页面，单击“属性配置”，在弹出窗口中输入服务属性对应的期望值，单击"确定"完成设备影子的修改。

图2 设备影子-属性配置

删除设备影子

用户删除设备影子，平台将会将设备影子中的所有数据（包含上报值和期望值）清空。

图3 删除设备影子

相关API接口

查询设备影子数据

配置设备影子预期数据