配置设备影子预期数据

功能介绍

应用服务器可调用此接口配置设备影子的预期属性（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 接口获取，接口返回的响应消息头中“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	参数说明：设备影子期望值结构体。

表4 ShadowDesired
参数	是否必选	参数类型	描述
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	参数说明：设备影子数据结构体。

表6 DeviceShadowData
参数	参数类型	描述
service_id	String	参数说明：设备命令所属的设备服务ID，在设备关联的产品模型中定义。取值范围：长度不超过64的字符串。
desired	DeviceShadowProperties object	参数说明：用户最近一次对设备下发的预期数据，Json格式，里面是一个个键值对，每个键都是产品模型中属性的参数名(property_name)。
reported	DeviceShadowProperties object	参数说明：设备最近一次上报的属性数据，Json格式，里面是一个个键值对，每个键都是产品模型中属性的参数名(property_name)。
version	Long	参数说明：设备影子的版本，携带该参数时平台会校验值必须等于当前影子版本，初始从0开始。

表7 DeviceShadowProperties
参数	参数类型	描述
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

{
  "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
  } ]
}