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

# 在设备处于离线状态时使用设备影子保持设备状态
<a name="iot-shadows-tutorial"></a>

这些教程向您展示了 Amazon IoT 如何使用 Device Shadow 服务来存储和更新设备的状态信息。影子文档是 JSON 文档，根据设备、本地应用程序或服务发布的消息显示设备状态的更改。在本教程中，影子文档将显示灯泡颜色的变化。这些教程还显示影子如何存储此信息，即使设备与互联网断开连接，并在设备重新联机并请求此信息时将最新状态信息传递回设备。

我们建议您按照这里显示的顺序尝试这些教程，从需要创建的 Amazon IoT 资源以及必要的硬件设置开始，这也有助于您逐步学习这些概念。这些教程展示了如何配置和连接 Raspberry Pi 设备以供使用 Amazon IoT。如果您没有所需的硬件，您可以按照这些教程将它们适配于您选择的设备或[使用 Amazon EC2 创建虚拟设备](creating-a-virtual-thing.md)。

**教程场景概览**  
这些教程的场景是一个本地应用程序或服务，该应用程序或服务可更改灯泡的颜色，并将其数据发布到预留的影子主题。这些教程类似于[交互式入门教程](interactive-demo.md)中描述的 Device Shadow 功能，并在Raspberry Pi设备上实现。本部分中的教程侧重于单个经典影子，同时将展示如何容纳已命名的影子或多个设备。

以下教程将帮助您学习如何使用 Dev Amazon IoT ice Shadow 服务。
+ 

**[教程：准备 Raspberry Pi 运行影子应用程序](create-resources-shadow.md)**  
本教程介绍如何设置 Raspberry Pi 设备以进行连接 Amazon IoT。您还将创建 Amazon IoT 策略文档和事物资源，下载证书，然后将策略附加到该事物资源。完成本教程需要大约 30 分钟。
+ 

**[教程：安装设备软件开发包并运行 Device Shadow 示例应用程序](lightbulb-shadow-application.md)**  
本教程介绍如何安装所需的工具、软件和适用于 Python 的 Amazon IoT 设备 SDK，然后运行示例影子应用程序。本教程基于 [连接 Raspberry Pi 或其他设备](connecting-to-existing-device.md) 中介绍的概念所打造，完成需要 20 分钟。
+ 

**[教程：示例应用程序及 MQTT 测试客户端与 Device Shadow 交互](interact-lights-device-shadows.md)**  
本教程展示了如何使用`shadow.py`示例应用程序和**Amazon IoT 控制台**来观察 Amazon IoT 设备阴影与灯泡状态变化之间的相互作用。本教程还介绍了如何将 MQTT 消息发送到 Device Shadow 的预留主题。完成本教程需要大约 45 分钟。

**Amazon IoT Device Shadow 概述**  
Device Shadow 是设备的永久虚拟表示形式，由您在 Amazon IoT 注册表中创建[的事物资源](iot-thing-management.md)管理。Shadow 文档是一个 JSON 或 JavaScript 符号文档，用于存储和检索设备的当前状态信息。无论设备是否已连接到互联网，您都可以使用 shadow 通过 MQTT 主题或 HTTP RES APIs T 获取和设置设备的状态。

影子文档包含一个 `state` 属性，以描述设备状态的以下方面。
+ `desired`：应用程序更新 `desired` 对象以指定设备属性的所需状态。
+ `reported`：设备在 `reported` 对象中报告其当前状态。
+ `delta`： Amazon IoT 报告`delta`对象中所需状态和报告状态之间的差异。

以下为示例影子状态文档：

```
{
  "state": {
    "desired": {
      "color": "green"
      },
    "reported": {
      "color": "blue"
      },
    "delta": {
      "color": "green"
      }
   }
}
```

要更新设备的 Shadow 文档，您可以使用[保留的 MQTT 主题](reserved-topics.md#reserved-topics-shadow)、支持、、HTTP `DELETE` 操作 APIs的 Device Shado [w RES](device-shadow-rest-api.md) T 以及 [Amazon IoT CLI](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot-data/index.html)。`GET` `UPDATE`

在前面的示例中，假设您希望将 `desired` 颜色改为 `yellow`。要执行此操作，请将请求发送到 [UpdateThingShadow](device-shadow-rest-api.md#API_UpdateThingShadow) API 或将消息发布到[更新](device-shadow-mqtt.md#update-pub-sub-topic)主题，`$aws/things/THING_NAME/shadow/update`。

```
{
  "state": {
    "desired": {
      "color": yellow
    }
  }
}
```

更新仅影响请求中指定的字段。成功更新 Device Shadow 后，将新`desired`状态 Amazon IoT 发布到`delta`主题`$aws/things/THING_NAME/shadow/delta`。在这种情况下，影子文档如下所示：

```
{
  "state": {
    "desired": {
      "color": yellow
    },
    "reported": {
      "color": green
    },
    "delta": {
      "color": yellow
      }
  }
}
```

然后，使用`$aws/things/THING_NAME/shadow/update`带有以下 JSON 消息的`Update`主题向 Dev Amazon IoT ice Shadow 报告新状态：

```
{
  "state": {
    "reported": {
      "color": yellow
    }
  }
}
```

如果要获取当前状态信息，请将请求发送至 [GetThingShadow](device-shadow-rest-api.md#API_GetThingShadow) API 或将 MQTT 消息发布到 [Get](device-shadow-mqtt.md#get-pub-sub-topic)（获取）主题，`$aws/things/THING_NAME/shadow/get`。

有关使用 Device Shadow 服务的更多信息，请参阅 [Amazon IoT Device Shadow 服务](iot-device-shadows.md)。

有关在设备、应用程序和服务中使用 Device Shadow 的更多信息，请参阅 [在设备中使用影子](device-shadow-comms-device.md) 和 [在应用程序和服务中使用影子](device-shadow-comms-app.md)。

有关与 Amazon IoT 阴影交互的信息，请参见[与影子交互](device-shadow-data-flow.md)。

有关 MQTT 保留主题和 HTTP REST 的信息 APIs，请参阅[Device Shadow MQTT 主题](device-shadow-mqtt.md)和。[Device Shadow REST API](device-shadow-rest-api.md)