AWS IoT
开发人员指南
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。请点击 Amazon AWS 入门,可查看中国地区的具体差异

事物影子文档

Thing Shadows 服务遵守 JSON 规范下的所有规则。值、对象和数组均存储在事物影子文档中。

文档属性

事物影子文档具有以下属性:

state
desired

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

reported

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

metadata

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

timestamp

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

clientToken

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

version

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

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

事物影子的版本控制

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

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

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

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

客户端令牌

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

示例文档

以下为事物影子文档示例:

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