Shadow 术语

Device Shadow 服务文档

Device Shadow 服务文档是由 Amazon Web Services (AWS) 云中的 Shadow 服务维护的 JSON 文档，用于存储和检索设备的当前状态信息。

示例文档：

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

Device Shadow 服务文档属性

设备的 Shadow 服务文档包含以下属性：

state

desired

设备（事物）的所需状态。应用程序可以写入文档的这一部分，以更新某个事物的状态，而无需直接连接到某个事物。如上所示的示例状态是“color”: “RED”。

reported

事物的报告状态是当前状态。事物写入文档的此部分以报告新状态。

metadata

有关 state 部分中存储的数据的信息，例如 state 部分中每个属性的时间戳（以纪元时间为单位）。这使您能够确定这些部分何时更新。

timestamp

表示消息由 AWS IoT 传输的时间。通过使用消息中的时间戳以及 desired 或 reported 部分中各属性的时间戳，即使更新项没有实现内部时钟，也可以确定其时间。

clientToken

该字符串是设备唯一的字符串，使您能够将响应与 MQTT 环境中的请求相关联。

version

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

Shadow Update

Shadow Update 操作可创建设备的影子（如果不存在），或更新设备的 Shadow 服务文档的内容。任何内容更改都存储有一个时间戳，以显示上次更新的时间。消息将发送给所有订阅者，其中 desired 与 reported 状态之间的差异（Delta）。接收这些消息的事物或应用程序可以根据 desired 和 reported 状态之间的差异执行操作。例如，设备可以将其状态更新到所需状态，或者应用程序可以更新其 UI 以显示设备状态的变化。

Shadow Get

Shadow Get 操作可检索存储在设备影子中的最新状态。例如，在启动时，设备连接到 AWS IoT Core，以检索配置数据和最后一个操作状态。此方法返回完整的 JSON 文档，包括元数据。

Shadow Delete

Shadow Delete 操作将删除设备的影子，包括其所有内容。这将从数据库中删除 JSON 文档。设备影子一经删除，无法还原，但可以创建新的设备影子（名称相同）。

Shadow Delta Callback

Shadow Delta 回调返回 Shadow Delta 状态，这是一个虚拟状态，包含 desired 和 reported 状态之间的差异。desired 部分中与 reported 部分不匹配的字段包含在 Delta 中。在 reported 部分且不在 desired 部分的字段不包含在 Delta 中。更新设备的影子会导致 Shadow 文档具有不同的 desired 和 reported 状态，此时会向主题 $aws/things/thing-name/shadow/update/delta 发布消息。

此消息仅包含设备 Shadow 文档中 desired 和 reported 部分之间的差异。收到此消息后，设备应决定是否进行请求的更改。在 Shadow 库中，可以通过注册 Shadow Delta Callback 回调来检索增量状态。

Shadow Updated Callback

每当成功更新影子时，Shadow Updated 回调就会从 AWS IoT 向此主题返回一个状态文档：

$aws/things/thingName/shadow/update/documents

JSON 文档将包含两个主节点：previous 和 current。在执行更新之前，previous 节点包含完整 Shadow 文档的内容，而成功更新之后，current 包含完整 Shadow 文档的内容。首次更新（创建）影子时，previous 节点包含 null。在 Shadow 库中，可以通过注册 Shadow Updated 回调来检索更新后的状态文档。