设备影子（联通用户专用）

更新时间：2025-02-26 GMT+08:00

非联通用户请查看设备接入服务。

概述

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

设备影子上有desired区和report区。

desired区用于存储对设备属性的配置，即期望值。当需要修改设备的服务属性值时，可修改设备影子的desired属性值，设备在线时，desired属性值立即同步到设备。如果设备不在线，待设备上线或上报数据时，desired属性值同步到设备。
report区用于存储设备最新上报的设备属性值，即上报值。当设备上报数据时，平台刷新report属性值为设备上报的设备属性值。

说明：

物联网平台仅支持对LWM2M协议的设备提供设备影子功能，对于希望通过设备影子修改的属性，在定义Profile文件时，需遵循LWM2M协议中定义的属性，且属性类型为“W”。LWM2M标准规范参见《OMA-TS-LightweightM2M-V1_0_2-20180209-A.pdf》。

应用场景

适合采用LWM2M协议的设备，特别是资源受限低功耗设备，长期处于休眠状态的场景。

查询设备最新上报数据和设备最新在线状态：
- 当在控制台上查询设备上报数据时，由于设备可能长时间处于离线状态或因网络不稳定掉线，而无法获取到最新数据。通过设备影子机制，设备影子中始终保持设备最新上报的数据和设备当前状态，控制台上只需要查询设备影子中存储的数据，即可获取设备最新上报的数据和设备状态。
- 很多应用服务器频繁的查询设备在线状态，由于设备处理能力有限，频繁查询会损耗设备性能。使用设备影子机制，设备只需要主动同步状态给设备影子一次，多个应用程序请求设备影子获取设备状态，即可获取设备最新状态，从而将应用程序和设备解耦。
修改设备属性值：用户通过设备配置更新功能修改设备的属性值，由于设备可能长时间处于离线状态，修改设备属性值的操作不能及时下发给设备。在这种情况下，物联网平台可以将修改设备的属性信息存储在设备影子中，待设备上线后，将修改的设备属性值同步给设备，从而完成设备属性值的修改。

业务流程

修改设备属性值

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

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

Method: PUT
request:
https://server:port/iocm/app/shadow/v1.5.0/devices/devices/{deviceId}?appId={appId}
Header:
app_key: ******
Authorization: Bearer ******
Content-Type: application/json
Body: 
{
  "serviceDesireds": [
    {
      "serviceId": "Temperature",
      "desired": {
        "targetTemperature": 35
      }
    }
  ]
}

物联网平台修改desired属性值。
物联网平台返回响应消息。
物联网平台判断设备上线或上报数据。
物联网平台将设备属性同步到设备。
设备返回响应消息。
当设备上报数据时，物联网平台修改report属性值为设备上报的设备属性值。

查询设备属性值

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

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

Method: GET
request:
https://server:port/iocm/app/shadow/v1.5.0/devices/{deviceId}
Header:
app_key: ******
Authorization: Bearer ******
Content-Type: application/json

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

response:
Status Code: 200 OK
Content-Type: application/json
Body:
{
  "deviceId": "******",
  "gatewayId": "******",
  "nodeType": "******",
  "createTime": "******",
  "lastModifiedTime": "******",
  "deviceInfo": "******""services": [
    {
      "serviceId": "******",
      "reportedProps": "******",
      "desiredProps": "******",
      "eventTime": "******",
      "serviceType": "******"
    },
  ]
}