Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

教程：安装设备软件开发包并运行 Device Shadow 示例应用程序

本部分介绍如何安装所需的软件和 Amazon IoTDevice SDK for Python，并运行 shadow.py示例应用程序来编辑影子文档并控制影子的状态。

在运行本教程之前：

您必须已设置好您的 Amazon Web Services 账户，配置好您的 Raspberry Pi 设备，并已创建 Amazon IoT事物和策略，授予设备发布和订阅 MQTT 预留的 Device Shadow 服务主题的权限。有关更多信息，请参阅 教程：准备 Raspberry Pi 运行影子应用程序。

您必须还安装了 Git、Python 和 Amazon IoTDevice SDK for Python。本教程基于教程 连接 Raspberry Pi 或其他设备中介绍的概念执行。如果您尚未尝试该教程，我们建议您按照该教程中描述的步骤安装证书文件和 Device SDK，然后返回本教程运行 shadow.py示例应用程序。

完成本教程需要大约 20 分钟。

步骤 1：运行 shadow.py 示例应用程序

在运行 shadow.py示例应用程序前，除了安装的证书文件的名称和位置之外，还需要以下信息。

在影子文档中输入值并观察更新

您可以在终端中输入值来指定 desired值，该值还会更新 reported值。假设您在终端中输入颜色 yellow。reported 值也会更新为颜色 yellow。下面显示了终端中显示的消息：

Enter desired value:
yellow
Changed local shadow value to 'yellow'.
Updating reported shadow value to 'yellow'...
Update request published.
Finished updating reported shadow value to 'yellow'.

发布此更新请求时，Amazon IoT 将为事物资源创建一个默认的经典影子。您可以在 Amazon IoT控制台中观察您发布到 reported和 desired中的值，方法是查看您创建的事物资源的影子文档（例如 My_light_bulb)。要查看影子文档中的更新：

影子文档应类似于以下内容，显示为颜色 yellow设置的 reported和 desired值。您可以在文档的 Shadow state（影子状态）部分看到这些值。

{
"desired": {
  "welcome": "aws-iot",
  "color": "yellow"
},
"reported": {
  "welcome": "aws-iot",
  "color": "yellow"
}
}

您还可以看到 Metadata（元数据）部分，其中包含请求的时间戳信息和版本号。

您可以使用状态文档版本来确保正在更新的设备影子文档为最新版本。如果您发送另一个更新请求，则版本号将增加 1。当您为更新请求提供版本时，如果状态文档的当前版本与提供的版本不符，该服务将显示 HTTP 409 冲突响应代码并拒绝请求。

{
"metadata": {
  "desired": {
    "welcome": {
      "timestamp": 1620156892
    },
    "color": {
      "timestamp": 1620156893
    }
  },
  "reported": {
    "welcome": {
      "timestamp": 1620156892
    },
    "color": {
      "timestamp": 1620156893
    }
  }
},
"version": 10
}        

要了解有关影子文档的详细信息并观察状态信息的更改，请继续阅读下一教程 教程：示例应用程序及 MQTT 测试客户端与 Device Shadow 交互，如本教程的 步骤 4：查看结果和后续步骤部分所述。或者，您也可以在下一部分中了解 shadow.py示例代码以及它如何使用 MQTT 协议。

步骤 2：查看 shadow.py 设备软件开发包示例应用

本部分将回顾本教程中适用的来自 Amazon IoTDevice SDK v2 for Python 中的 shadow.py示例应用程序。在这里，我们将回顾它如何使用 MQTT 和采用 WSS 协议的 MQTT 来连接到 Amazon IoT Core。Amazon 公共运行时 (Amazon-CRT) 库提供低级通信协议支持，并包含在 Amazon IoTDevice SDK v2 for Python 中。

虽然本教程使用 MQTT 和 采用 WSS 的 MQTT，Amazon IoT 支持发布 HTTPS 请求的设备。有关从设备发送 HTTP 消息的 Python 程序示例，请参阅使用 Python 的 requests库的 HTTPS 代码示例。

有关如何对设备通信使用何种协议作出明智决定的信息，请查看 为设备通信选择协议。

MQTT

shadow.py 示例在 mqtt_connection_builder 中调用 mtls_from_path（此处显示）以使用 MQTT 协议建立与 Amazon IoT Core 的连接。mtls_from_path 使用 X.509 证书和 TLS v1.2 对设备进行身份验证。Amazon-CRT 库处理该连接的较低级别的详细信息。

mqtt_connection = mqtt_connection_builder.mtls_from_path(
  endpoint=args.endpoint,
  cert_filepath=args.cert,
  pri_key_filepath=args.key,
  ca_filepath=args.ca_file,
  client_bootstrap=client_bootstrap,
  on_connection_interrupted=on_connection_interrupted,
  on_connection_resumed=on_connection_resumed,
  client_id=args.client_id,
  clean_session=False,
  keep_alive_secs=6
)

shadow.py 示例还调用 mqtt_connection_builder中的 websockets_with_default_aws_signing以使用采用 WSS 的 MQTT 协议与 Amazon IoT Core建立连接。采用 WSS 的 MQTT 也使用与 MQTT 相同的参数，并采用以下附加参数：

订阅影子主题和活动

shadow.py 示例尝试建立连接并等待完全连接。如果未连接，命令将排队。连接后，示例将订阅增量事件并更新和获取消息，并发布服务质量 (QoS) 级别为 1 的消息 (mqtt.QoS.AT_LEAST_ONCE)。

当设备订阅 QoS 级别 1 的消息时，消息代理会保存该设备订阅的消息，直到这些消息可以发送到设备。消息代理会重新发送消息，直至收到设备发出的 PUBACK响应。

有关 MQTT 协议的更多信息，请参阅 查看 MQTT 协议和 MQTT。

有关本教程中如何使用 MQTT、采用 WSS 的 MQTT、持久性会话和 QoS 级别的详细信息，请参阅 查看 pubsub.py Device SDK 示例应用程序。

步骤 3：借助 shadow.py示例应用程序排查问题

当您运行 shadow.py示例应用程序时，您应该看到终端中显示的一些消息以及输入 desired值的提示。如果程序抛出错误，那么请调试以解决错误，您可以从检查系统是否运行了正确的命令开始。

在某些情况下，错误消息可能会指示连接问题，并且看起来类似于：Host name was invalid for dns resolution 或者 Connection was closed unexpectedly。在这种情况下，以下是您可以检查的几个事项：

步骤 4：查看结果和后续步骤

后续步骤

您现在可以运行 shadow.py示例应用程序，并使用 Device Shadow 控制状态。您可以在 Amazon IoT控制台中观察并更新影子文档，并观察示例应用程序相应的增量事件。使用 MQTT 测试客户端，您可以订阅预留影子主题并在运行示例程序时观察主题收到的消息。有关如何使用该教程的更多信息，请参阅 教程：示例应用程序及 MQTT 测试客户端与 Device Shadow 交互。