# 设备侧获取平台的设备影子数据
#### 功能介绍
用于设备向平台获取设备影子数据。用户可以通过应用服务器或物联网控制台配置设备影子预期数据，设备上线时订阅该topic，可以获取到平台设备影子数据，以此来同步设备属性期望值，从而完成设备属性值的修改。
简单交互逻辑介绍如下：
① 应用调用"配置设备影子预期数据"接口或在控制台配置设备影子数据；
② 设备侧（已完成关联Topic订阅）主动上报请求，获取平台的设备影子数据；
③ 平台响应设备请求，返回设备影子数据；
④ 设备侧解析属性期望值，并完成设备属性值修改。
#### Topic
上行: $oc/devices/{device_id}/sys/shadow/get/request_id={request_id}
下行: $oc/devices/{device_id}/sys/shadow/get/response/request_id={request_id}
![](https://support.huaweicloud.com/devg-ocsmartcampus/public_sys-resources/note_3.0-zh-cn.png)
- {request_id}用于唯一标识这次请求。设备侧发起的消息带该参数时，需要保证设备侧该参数值的唯一性，可以用递增的数字或者UUID来实现。
- 设备侧上行请求参数中携带唯一标识，该唯一标识会在下行topic中request_id携带给设备以标记唯一请求链。
- 订阅下行Topic时建议使用通配符"#"来替代"request_id={request_id}"即为：$oc/devices/{device_id}/sys/shadow/get/response/#。
 
#### 上行请求参数说明
| 字段名              | 必选/可选 | 类型     | 参数描述                                                                                                                                                                  |
|:---|:---|:---|:---|
| object_device_id | 可选    | String | **参数解释：** 需要获取设备影子的目标设备ID。                   |
| service_id       | 可选    | String | **参数解释：** 需要获取设备影子的设备服务ID，不带的话查询所有服务ID的设备影子数据。 |
   
#### 下行响应参数说明
| 字段名              | 必选/可选 | 类型                 | 参数描述                                                                                                                                            |
|:---|:---|:---|:---|
| object_device_id | 必选    | String             | **参数解释：** 设备影子的目标设备ID。 |
| shadow           | 可选    | List\<ShadowData\> | **参数解释：** 服务影子数据。      |
   
ShadowData结构定义：
| 字段名        | 必选/可选 | 类型             | 参数描述                                                                                                                                                                                                                  |
|:---|:---|:---|:---|
| service_id | 必选    | String         | **参数解释：** 设备的服务ID，由创建的[产品模型](https://support.huaweicloud.com/devg-iothub/iot_02_0005.html)确定。 |
| desired    | 可选    | PropertiesData | **参数解释：** 设备影子desired区的属性列表。                                                                 |
| reported   | 可选    | PropertiesData | **参数解释：** 设备影子reported区的属性列表。                                                                |
| version    | 可选    | Integer        | **参数解释：** 设备影子版本信息。                                                                          |
   
PropertiesData结构定义：
| 字段名        | 必选/可选 | 类型     | 参数描述                                                                                                                                                                                        |
|:---|:---|:---|:---|
| properties | 必选    | Object | **参数解释：** 设备服务的属性列表，具体字段在设备关联的产品模型里定义，可以设置多个字段。                      |
| event_time | 可选    | String | **参数解释：** 设备属性数据的UTC时间（格式：yyyyMMdd'T'HHmmss'Z'），如：20161219T114920Z。 |
   
#### 上行请求示例
```
Topic: $oc/devices/{device_id}/sys/shadow/get/request_id={request_id} 
数据格式：  
{
"object_device_id": "40fe3542-f4cc-4b6a-98c3-61a49ba1acd4",
"service_id": "WaterMeter"
}
```
 #### 下行响应示例
```
Topic：$oc/devices/{device_id}/sys/shadow/get/response/request_id={request_id}
数据格式：  
{
  "object_device_id": "40fe3542-f4cc-4b6a-98c3-61a49ba1acd4",
  "shadow": [
    {
      "service_id": "WaterMeter",
      "desired": {
        "properties": {
          "temperature": "60"
        },
        "event_time": "20151212T121212Z"
      },
      "reported": {
        "properties": {
          "temperature": "60"
        },
        "event_time": "20151212T121212Z"
      },
      "version": 1
    }
  ]
}
```