AWS IoT
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 Amazon AWS 入门

Device Shadow 服务文档

Device Shadow 服务遵守 JSON 规范下的所有规则。值、对象和数组均存储在设备的影子文档中。

文档属性

设备的影子文档具有以下属性:

state
desired

事物的预期状态。应用程序可以向本文档部分写入数据来更新事物的状态,且无需直接连接到该事物。

reported

事物的报告状态。事物可以向本文档部分写入数据,以报告其新状态。应用程序可以读取本文档部分,以确定事物的状态。

metadata

有关存储在文档 state 部分的数据的信息,其中包括 state 部分中每个属性的时间戳(以 Epoch 时间表示),让您能够确定它们的更新时间。

timestamp

指明 AWS IoT 传输消息的时间。通过在消息中使用时间戳并对 desiredreported 部分中的不同属性使用时间戳,事物可以确定已更新项目的存在时间,即使它不具有内部时钟特性。

clientToken

特定于设备的字符串,让您能在 MQTT 环境中将响应与请求关联起来。

version

文档版本。文档每次更新时,此版本号都会递增。用于确保正在更新的文档为最新版本。

有关更多信息,请参阅 影子文档语法

Device Shadow 的版本控制

Device Shadow 服务支持对每个更新消息 (包括请求和响应) 实施版本控制,这意味着,设备的影子每次更新时,JSON 文档的版本都会递增。这可以确保两件事情:

  • 如果客户端尝试使用旧版本号覆盖影子,它将收到错误消息。客户端将被告知必须先进行重新同步,然后才能更新设备的影子。

  • 如果消息的版本比客户端存储的版本低,客户端则可决定不对该消息执行操作。

在有些情况下,客户端可以通过不提交版本来绕过版本匹配。

客户端令牌

收发基于 MQTT 的消息时,您可以使用客户端令牌,以验证请求和请求响应是否包含相同的客户端令牌。这可以确保响应与请求相互关联。

注意

客户端令牌不能超过 64 字节。超过 64 字节的客户端令牌将引发 400 (错误请求) 响应和 clientToken 无效 错误消息。

示例文档

以下为示例影子文档:

{ "state" : { "desired" : { "color" : "RED", "sequence" : [ "RED", "GREEN", "BLUE" ] }, "reported" : { "color" : "GREEN" } }, "metadata" : { "desired" : { "color" : { "timestamp" : 12345 }, "sequence" : { "timestamp" : 12345 } }, "reported" : { "color" : { "timestamp" : 12345 } } }, "version" : 10, "clientToken" : "UniqueClientToken", "timestamp": 123456789 }

空白部分

仅当影子文档具有预期状态时,它才包含 desired 部分。例如,以下文档为没有 desired 部分的有效状态文档:

{ "reported" : { "temp": 55 } }

reported 部分也可以为空:

{ "desired" : { "color" : "RED" } }

如果更新导致 desiredreported 部分为空,则该部分将从文档中删除。要从文档中删除 desired 部分 (例如,对设备更新状态做出响应),请将“desired”部分设置为 null

{ "state": { "reported": { "color": "red" }, "desired": null } }

影子文档也有可能不包含 desiredreported 部分。在此情况下,影子文档将为空。例如,以下文档也是一个有效文档:

{ }

数组

影子支持数组,但将其视为正常值进行处理,因为对数组的更新将替换整个数组。无法更新数组的某个部分。

初始状态:

{ "desired" : { "colors" : ["RED", "GREEN", "BLUE" ] } }

更新:

{ "desired" : { "colors" : ["RED"] } }

最终状态:

{ "desired" : { "colors" : ["RED"] } }

数组不能包含空值。例如,以下数组无效并将被拒绝。

{ "desired" : { "colors" : [ null, "RED", "GREEN" ] } }