与影子交互 - AWS IoT Core
协议支持请求和报告状态更新影子检索影子文档删除影子数据

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

与影子交互

本主题介绍了 AWS IoT 为处理影子而提供的三种方法的关联消息。这些方法包括：

UPDATE

创建影子（如果不存在），或使用消息正文中提供的状态信息更新现有影子的内容。 AWS IoT 记录每次更新的时间戳，以指示上次更新状态的时间。当影子的状态发生变化时， AWS IoT 会向所有MQTT订阅者发送带有desired和reported状态差异的/delta消息。收到 /delta 消息的设备或应用程序可以根据该差异执行操作。例如，设备可以将其状态更新为所需的状态，或者应用程序可以更新其 UI 以反映设备的状态变化。

GET

检索包含影子的完整状态的当前影子文档，包括元数据。

DELETE

删除设备影子及其内容。

您无法还原已删除的设备影子文档，但可以创建具有已删除设备影子文档的名称的新设备影子。如果您创建的设备影子文档与过去48小时内删除的文档同名，新设备影子文档的版本号和已删除文档的版本号相同。如果设备影子文档已删除超过 48 小时，具有相同名称的新设备影子文档的版本号为 0。

协议支持

AWS IoT 支持MQTT和RESTAPI超出与阴影交互的HTTPS协议。 AWS IoT 为MQTT发布和订阅操作提供了一组保留的请求和响应主题。设备和应用程序应在发布请求主题之前订阅响应主题，以获取有关如何 AWS IoT 处理请求的信息。有关更多信息，请参阅Device Shadow MQTT 话题 和Device Shadow REST API。

请求和报告状态

在使用 AWS IoT and shadows 设计物联网解决方案时，应确定将请求更改的应用程序或设备以及将实施变更的应用程序或设备。通常，设备实施更改并向影子报告更改，而应用程序和服务响应并请求影子中的更改。您的解决方案可能有所不同，但本主题中的示例假定客户端应用程序或服务请求影子中的更改，而设备执行更改并向影子报告更改。

更新影子

您的应用程序或服务可以通过使用UpdateThingShadowAPI或发布到/update主题来更新影子的状态。更新仅影响请求中指定的字段。

在客户端请求状态更改时更新影子

当客户端使用MQTT协议请求在影子中更改状态时

  1. 客户端应具有当前影子文档，以便它可以确定要更改的属性。有关如何获取当前影子文档的信息，请参阅 /get 操作。

  2. 客户订阅了以下MQTT主题：

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    • $aws/things/thingName/shadow/name/shadowName/update/documents

  3. 客户端使用包含影子的所需状态的状态文档发布 $aws/things/thingName/shadow/name/shadowName/update 请求主题。只需在文档中包含要更改的属性。以下是具有所需状态的文档的示例。

    {
  "state": {
    "desired": {
      "color": {
        "r": 10
      },
      "engine": "ON"
    }
  }
}

  4. 如果更新请求有效，则在影子中 AWS IoT 更新所需的状态并发布有关以下主题的消息：

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    /update/accepted 消息包含一个 /accepted 响应状态文档 影子文档，而 /update/delta 消息包含一个 /delta 响应状态文档 影子文档。

  5. 如果更新请求无效，则 AWS IoT 发布带有$aws/things/thingName/shadow/name/shadowName/update/rejected主题的消息以及描述错误的错误响应文档影子文档。

当客户端通过使用 shadow 请求更改状态时 API

  1. 客户端UpdateThingShadowAPI使用请求状态文档状态文档作为其消息正文来调用。

  2. 如果请求有效，则 AWS IoT 返回HTTP成功响应代码和/accepted 响应状态文档影子文档作为其响应消息正文。

    AWS IoT 还将向该$aws/things/thingName/shadow/name/shadowName/update/delta主题发布一条MQTT消息，其中包含订阅该文档的任何设备或客户端的/delta 响应状态文档影子文档。

  3. 如果请求无效，则 AWS IoT 返回HTTP错误响应代码 a 错误响应文档 作为其响应消息正文。

当设备在 /update/delta 主题上收到 /desired 状态时，它将在设备中进行所需的更改。然后，它向 /update 主题发送一条消息，以向影子报告其当前状态。

在设备报告其当前状态时更新影子

当设备使用MQTT协议向影子报告其当前状态时

  1. 在更新影子之前，设备应订阅以下MQTT主题：

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    • $aws/things/thingName/shadow/name/shadowName/update/documents

  2. 设备向 $aws/things/thingName/shadow/name/shadowName/update 主题发布一条消息以报告其当前状态，例如，在该示例中。

    {
    "state": {
        "reported" : {
            "color" : { "r" : 10 },
            "engine" : "ON"
        }
    }
}

  3. 如果 AWS IoT 接受更新，则会向$aws/things/thingName/shadow/name/shadowName/update/accepted主题发布带有/accepted 响应状态文档影子文档的消息。

  4. 如果更新请求无效，则 AWS IoT 发布带有$aws/things/thingName/shadow/name/shadowName/update/rejected主题的消息以及描述错误的错误响应文档影子文档。

当设备使用向影子报告其当前状态时 API

  1. 设备UpdateThingShadowAPI使用请求状态文档状态文档作为其消息正文来调用。

  2. 如果请求有效，则 AWS IoT 更新影子并返回以/accepted 响应状态文档影子文档作为其响应消息正文的HTTP成功响应代码。

    AWS IoT 还将向该$aws/things/thingName/shadow/name/shadowName/update/delta主题发布一条MQTT消息，其中包含订阅该文档的任何设备或客户端的/delta 响应状态文档影子文档。

  3. 如果请求无效，则 AWS IoT 返回HTTP错误响应代码 a 错误响应文档 作为其响应消息正文。

乐观锁

您可以使用状态文档版本来确保正在更新的设备的影子文档为最新版本。当您向版本提供更新请求时，如果状态文档的当前版本与提供的版本不匹配，则服务会拒绝该请求，并返回 HTTP 409 冲突响应代码。冲突响应代码也可能出现在任何修改API过的内容上ThingShadow，包括DeleteThingShadow。

例如：

初始文档：

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

更新：（版本不匹配；该请求将被拒绝）

{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 9
}

结果：

{
  "code": 409,
  "message": "Version conflict",
  "clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}

更新：（版本匹配；请求将被接受）

{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 10
}

最终状态：

{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 11
}

检索影子文档

您可以使用GetThingShadowAPI或通过订阅和发布/get主题来检索影子文档。这会检索完整的影子文档，包括 desired 和 reported 状态之间的任何增量。无论设备还是客户端发出请求，该任务的流程都是相同的。

使用MQTT协议检索影子文档

  1. 在更新影子之前，设备或客户端应订阅以下MQTT主题：

    • $aws/things/thingName/shadow/name/shadowName/get/accepted

    • $aws/things/thingName/shadow/name/shadowName/get/rejected

  2. 设备或客户端使用空消息正文向 $aws/things/thingName/shadow/name/shadowName/get 主题发布一条消息。

  3. 如果请求成功，则向$aws/things/thingName/shadow/name/shadowName/get/accepted主题 AWS IoT 发布一条消息，消息正文/accepted 响应状态文档中包含一个。

  4. 如果请求无效，则向$aws/things/thingName/shadow/name/shadowName/get/rejected主题 AWS IoT 发布一条消息，并在消息正文错误响应文档中加上。

使用检索卷影文档 REST API

  1. 设备或客户端GetThingShadowAPI使用空消息正文调用。

  2. 如果请求有效，则 AWS IoT 返回以/accepted 响应状态文档影子文档作为其响应消息正文的HTTP成功响应代码。

  3. 如果请求无效，则 AWS IoT 返回HTTP错误响应代码 a 错误响应文档 作为其响应消息正文。

删除影子数据

可以使用两种方法删除影子数据：您可以在影子文档中删除特定的属性，也可以完全删除影子。

  • 要从影子中删除特定的属性，请更新影子，但将您要删除的属性的值设置为 null。将从影子文档中删除值为 null 的字段。

  • 要删除整个阴影，请使用DeleteThingShadowAPI或发布到/delete主题。

注意

删除阴影不会立即将其版本号重置为零。将在 48 小时后重置为零。

从影子文档中删除属性

使用MQTT协议从影子中删除属性

  1. 设备或客户端应具有当前影子文档，以便它可以确定要更改的属性。有关如何获取当前影子文档的信息，请参阅 检索影子文档。

  2. 设备或客户端订阅了以下MQTT主题：

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

  3. 设备或客户端使用将 null 值分配给要删除的影子属性的状态文档以发布 $aws/things/thingName/shadow/name/shadowName/update 请求主题。只需在文档中包含要更改的属性。以下是删除 engine 属性的文档的示例。

    {
  "state": {
    "desired": {
      "engine": null
    }
  }
}

  4. 如果更新请求有效，则 AWS IoT 删除影子中的指定属性，并发布带有$aws/things/thingName/shadow/name/shadowName/update/accepted主题的消息，消息正文中包含/accepted 响应状态文档影子文档。

  5. 如果更新请求无效，则 AWS IoT 发布带有$aws/things/thingName/shadow/name/shadowName/update/rejected主题的消息以及描述错误的错误响应文档影子文档。

要从阴影中删除属性，请使用 REST API

  1. 设备或客户端UpdateThingShadowAPI使用 a 调用请求状态文档，为要删除的影子的属性赋null值。仅在文档中包含要删除的属性。以下是删除 engine 属性的文档的示例。

    {
  "state": {
    "desired": {
      "engine": null
    }
  }
}

  2. 如果请求有效，则 AWS IoT 返回HTTP成功响应代码和/accepted 响应状态文档影子文档作为其响应消息正文。

  3. 如果请求无效，则 AWS IoT 返回HTTP错误响应代码 a 错误响应文档 作为其响应消息正文。

删除影子

以下是删除设备影子时的一些注意事项。

  • 将设备的影子状态设置为 null 并不会删除影子。在下次更新时，影子版本将会增加。

  • 删除设备的影子并不会删除事物对象。删除事物对象并不会删除相应设备的影子。

  • 删除阴影不会立即将其版本号重置为零。将在 48 小时后重置为零。

使用MQTT协议删除阴影

  1. 设备或客户端订阅了以下MQTT主题：

    • $aws/things/thingName/shadow/name/shadowName/delete/accepted

    • $aws/things/thingName/shadow/name/shadowName/delete/rejected

  2. 设备或客户端使用空消息缓冲区发布 $aws/things/thingName/shadow/name/shadowName/delete。

  3. 如果删除请求有效，则 AWS IoT 删除影子并在消息正文中发布带有$aws/things/thingName/shadow/name/shadowName/delete/accepted主题和缩写/accepted 响应状态文档影子文档的消息。以下是接受的删除消息的示例：

    {
  "version": 4,
  "timestamp": 1591057529
}

  4. 如果更新请求无效，则 AWS IoT 发布带有$aws/things/thingName/shadow/name/shadowName/delete/rejected主题的消息以及描述错误的错误响应文档影子文档。

要删除阴影，请使用 REST API

  1. 设备或客户端DeleteThingShadowAPI使用空消息缓冲区调用。

  2. 如果请求有效，则在消息正文中 AWS IoT 返回HTTP成功响应代码/accepted 响应状态文档和缩写的/accepted 响应状态文档影子文档。以下是接受的删除消息的示例：

    {
  "version": 4,
  "timestamp": 1591057529
}

  3. 如果请求无效，则 AWS IoT 返回HTTP错误响应代码 a 错误响应文档 作为其响应消息正文。