# 配置设备影子预期数据
#### 功能介绍
应用服务器可调用此接口配置设备影子的预期属性（desired区），当设备上线或者设备上报属性时把属性下发给设备。
设备影子介绍：
设备影子是一个用于存储和检索设备当前状态信息的JSON文档。
- 每个设备有且只有一个设备影子，由设备ID唯一标识
  
- 设备影子用于存储设备上报的(状态)属性和应用程序期望的设备(状态)属性
  
- 无论该设备是否在线，都可以通过该影子获取和设置设备的属性
  
- 设备上线或者设备上报属性时，如果desired区和reported区存在差异，则将差异部分下发给设备，配置的预期属性需在产品模型中定义且method具有可写属性"W"才可下发
  
- 该接口仅支持配置单个设备的设备影子的预期数据。
  
限制：
设备影子JSON文档中的key不允许特殊字符：点(.)、dollar符号($)、空char(十六进制的ASCII码为00)。如果包含了以上特殊字符则无法正常刷新影子文档。
#### URI
PUT /v1/iotfm/devices/{device_id}/shadow
表1路径参数 
| 参数        | 是否必选 | 参数类型   | 描述                                                                                                                                 |
|:---|:---|:---|:---|
| device_id | 是    | String | **参数说明**：下发属性的设备ID，用于唯一标识一个设备，在注册设备时由设施云平台分配获得。 **取值范围**：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 |
   
#### 请求参数
表2请求Header参数 
| 参数             | 是否必选 | 参数类型   | 描述                                                                                                                                                              |
|:---|:---|:---|:---|
| X-Auth-Token   | 是    | String | **参数说明** ：用户Token。通过调用 [生成Token](https://support.huaweicloud.com/api-ocsmartcampus/ocsmartcampus_06_0008.html) 接口获取，接口返回的响应消息头中"X-Subject-Token"就是需要获取的用户Token。 |
| X-Instance-Id  | 是    | String | **参数说明**：实例ID。通过访问智能设施云平台界面后获取，智能设施云平台资源均为实例级隔离，所有业务接口必须填写正确的实例ID才能被成功调用。 **取值范围**：长度8-36，只允许大小写字母、数字和-字符的组合。           |
| X-Root-Zone-Id | 否    | String | **参数说明**：项目ID。 **取值范围**：长度不超过24，只允许字母、数字的组合。                                                                            |
   
表3请求Body参数 
| 参数     | 是否必选 | 参数类型                                                                                                         | 描述                   |
|:---|:---|:---|:---|
| shadow | 否    | Array of [ShadowDesired] objects | **参数说明**：设备影子期望值结构体。 |
   
 表4ShadowDesired 
| 参数         | 是否必选 | 参数类型   | 描述                                                                                                                                                                                |
|:---|:---|:---|:---|
| service_id | 是    | String | **参数说明**：设备的服务ID，在设备关联的产品模型中定义。                                                                                                                                                   |
| desired    | 是    | Object | **参数说明**：设备影子期望属性数据，Json格式，里面是一个个键值对，每个键都是产品模型中属性的参数名(property_name)，目前如样例所示只支持一层结构；如果想要删除整个desired可以填写空Object(例如"desired":{})，如果想要删除某一个属性期望值可以将属性置位null(例如{"temperature":null})。 |
| version    | 否    | Long   | **参数说明**：设备影子的版本，携带该参数时平台会校验值必须等于当前影子版本，初始从0开始。                                                                                                                                   |
   
#### 响应参数
**状态码：200**
表5响应Body参数 
| 参数        | 参数类型                                                                                                                | 描述                                                                                                                                 |
|:---|:---|:---|
| device_id | String                                                                                                              | **参数说明**：下发属性的设备ID，用于唯一标识一个设备，在注册设备时由设施云平台分配获得。 **取值范围**：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 |
| shadow    | Array of [DeviceShadowData] objects | **参数说明**：设备影子数据结构体。                                                                                                                |
   
 表6DeviceShadowData 
| 参数         | 参数类型                                                                                                                  | 描述                                                                                                |
|:---|:---|:---|
| service_id | String                                                                                                                | **参数说明**：设备命令所属的设备服务ID，在设备关联的产品模型中定义。 **取值范围**：长度不超过64的字符串。 |
| desired    | [DeviceShadowProperties] object | **参数说明**：用户最近一次对设备下发的预期数据，Json格式，里面是一个个键值对，每个键都是产品模型中属性的参数名(property_name)。                       |
| reported   | [DeviceShadowProperties] object | **参数说明**：设备最近一次上报的属性数据，Json格式，里面是一个个键值对，每个键都是产品模型中属性的参数名(property_name)。                          |
| version    | Long                                                                                                                  | **参数说明**：设备影子的版本，携带该参数时平台会校验值必须等于当前影子版本，初始从0开始。                                                   |
   
 表7DeviceShadowProperties 
| 参数         | 参数类型   | 描述                                                                                                                                                                                                                |
|:---|:---|:---|
| properties | Object | **参数说明**：设备影子的属性数据，Json格式，里面是一个个键值对，每个键都是产品模型中属性的参数名(property_name)，目前如样例所示只支持一层结构。 **注意**：JSON结构的key当前不支持特殊字符：点(.)、dollar符号($)、空char(十六进制的ASCII码为00)，key为以上特殊字符无法正常刷新设备影子。 |
| event_time | String | **参数说明**：事件操作时间，格式为："yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"。                                                                                                                                                               |
   
**状态码：400**
表8响应Body参数 
| 参数         | 参数类型   | 描述                                                                    |
|:---|:---|:---|
| error_code | String | **参数说明**：错误码。 **取值范围**：长度8-36。  |
| error_msg  | String | **参数说明**：错误描述。 **取值范围**：长度2-512。 |
   
#### 请求示例
配置设备影子预期数据。
```
PUT https://{endpoint}/v1/iotfm/devices/16087212bc75410c9ad77163b4cf6aba/shadow
{
  "shadow" : [ {
    "service_id" : "WaterMeter",
    "desired" : {
      "properties" : {
        "temperature" : "60"
      }
    },
    "version" : 1
  } ]
}
```
#### 响应示例
**状态码：200**
OK
```
{
  "device_id" : "16087212bc75410c9ad77163b4cf6aba",
  "shadow" : [ {
    "service_id" : "WaterMeter",
    "desired" : {
      "properties" : {
        "temperature" : "60"
      },
      "event_time" : "2022-12-26T01:52:49.999Z"
    },
    "reported" : {
      "properties" : {
        "temperature" : "59"
      },
      "event_time" : "2022-12-26T01:52:49.999Z"
    },
    "version" : 1
  } ]
}
```
#### 状态码
| 状态码 | 描述                    |
|:---|:---|
| 200 | OK                    |
| 400 | Bad Request           |
| 403 | Forbidden             |
| 404 | Not Found             |
| 500 | Internal Server Error |