tencent cloud

设备影子文档是服务器端为设备缓存的一份状态和配置数据。它以 JSON 文本形式存储，由以下部分组成：

state

reported
设备自身上报的状态。设备可以向本文档部分写入数据，以报告其新状态。应用程序可以读取本文档部分，以获取设备的状态。

desired
设备预期的状态。应用程序通过 HTTP RESTful API 向本文档写入数据更新设备状态，设备 SDK 通过注册相关属性和回调，设备影子服务同步影子数据到设备。

metadata

设备影子的元数据信息，包括 state 部分每个属性项的最后更新时间等。

version

设备影子文档的版本号，每次设备影子文档更新之后，版本号都会递增。版本号由腾讯云后台维护，这可以确保设备的数据与设备影子的数据保持一致。

timestamp

设备影子文档的最后一次更新时间。设备影子文档示例如下：

{
"state": {
 "reported": {
  "attr_name1": "value1"
 },
 "desired": {
  "attr_name2": "value2"
 }
},
"metadata": {
 "reported": {
  "attr_name1": {
   "timestamp": 123456789
  }
 },
 "desired": {
  "attr_name2": {
   "timestamp": 123456789
  }
 }
},
"version": 1,
"timestamp": 123456789
}

空白部分

当设备影子文档为空时，此时获取到设备影子文档示例如下：

{
"state":{},
"metadata":{},
"version":0
}

当设备影子文档具有预期状态时，才会有 desired 部分，reported 部分可以为空，例如：

{
"state": {
 "desired": {
  "attr_name2": "value2"
 }
},
"metadata": {
 "desired": {
  "attr_name2": {
   "timestamp": 123456789
  }
 }
},
"version": 1,
"timestamp": 123456789
}

当设备更新状态成功之后，需要上报最新的状态，并将 desired 部分从文档中删除。要想将 desired 部分从文档中删除，需要将 desired 部分置为 null，例如：

{
"state": {
"reported": {
 "attr_name1": "new_value1",
 "attr_name2": "new_value2"
},
"desired": null
},
"version": 1
}

数组

设备影子文档支持数组，不支持针对数组某个元素进行更新，只能更新整个数组，并且数组元素不能有空值。