教程：示例应用程序及 MQTT 测试客户端与 Device Shadow 交互 - AWS IoT Core
步骤 1：使用 shadow.py示例应用程序更新所需值和报告值步骤 2：查看来自 shadow.py中 MQTT 测试客户端中示例应用程序的消息步骤 3：排除 Device Shadow 交互中的错误步骤 4：查看结果和后续步骤

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

教程：示例应用程序及 MQTT 测试客户端与 Device Shadow 交互

若要与 shadow.py示例应用程序交互，请在终端中为 desired值输入一个值。例如，您可以向请求指定类似于红绿灯的颜色和 AWS IoT响应，并更新报告的值。

在本教程中，您将学习如何：

  • 使用 shadow.py示例应用程序来指定所需的状态并更新影子的当前状态。

  • 编辑影子文档以观察增量事件以及 shadow.py示例应用程序如何响应。

  • 使用 MQTT 测试客户端订阅影子主题并在运行示例程序时观察更新。

运行本教程之前，您必须具有：

设置您的AWS 账户，配置您的 Raspberry Pi 设备，并创建 AWS IoT事物和策略。您还必须安装了所需的软件、Device SDK、证书文件，并在终端中运行示例程序。有关更多信息，请参阅教程 教程：准备 Raspberry Pi 运行影子应用程序和 步骤 1：运行 shadow.py 示例应用程序。如果您尚未完成这些教程，请先予完成。

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

步骤 1：使用 shadow.py示例应用程序更新所需值和报告值

在前面的教程 步骤 1：运行 shadow.py 示例应用程序中，您学习了在按照部分 教程：安装设备软件开发包并运行 Device Shadow 示例应用程序中所述输入必要数值后，如何在 AWS IoT控制台中观察发布到影子文档的消息。

在前面的示例中，我们将所需的颜色设置为 yellow。输入每个值后，终端将提示您输入另一个 desired值。如果您再次输入相同的值 (yellow)，应用程序会识别这一点，并提示您输入一个新的 desired值。

Enter desired value:
yellow
Local value is already 'yellow'.
Enter desired value:

现在，假设您输入了颜色 green。AWS IoT 响应请求，并将 reported值更新为 green。这就是当 desired状态不同于 reported状态时产生更新的方式，从而导致增量。

shadow.py 示例应用程序模拟 Device Shadow 交互：

  1. 在终端输入 desired值（例如 yellow）来发布所需的状态。

  2. 由于 desired状态不同于 reported状态（比如说颜色 green），则会产生增量，并且订阅增量的应用程序会收到此消息。

  3. 应用程序响应消息并将其状态更新为 desired值，yellow。

  4. 然后，应用程序会发布一条更新消息，其中包含设备状态的新报告值，yellow。

下面显示了终端中显示的消息，其展示了更新申请是如何发布的。

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

在 AWS IoT控制台中，影子文档将 reported和 desired字段更新后的值反映到 green，然后版本号会增加 1。例如，如果以前的版本号显示为 10，则当前版本号将显示为 11。

注意

删除影子不会将版本号重置为 0。当您发布更新请求或创建另一个具有相同名称的影子时，您将看到影子版本递增 1。

编辑影子文档以观察增量事件

shadow.py 示例应用程序也订阅 delta事件，并在 desired值出现更改时予以响应。例如，您可以将 desired值更改为颜色 red。为此，请在 AWS IoT控制台中，单击 Edit（编辑）以编辑 Shadow 文档，然后在 JSON 中将 desired设置为 red，同时将 reported值保留为 green。保存更改之前，请保持 Raspberry Pi 上的终端打开状态，因为当出现更改时，您会看到终端中显示的消息。

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

保存新值后，shadow.py 示例应用程序响应此更改，并在终端中显示指示增量的消息。然后，您应该看到以下消息出现在输入 desired值的提示下方。

Enter desired value:
Received shadow delta event.
Delta reports that desired value is 'red'. Changing local value...
Changed local shadow value to 'red'.
Updating reported shadow value to 'red'...
Finished updating reported shadow value to 'red'.
Enter desired value:
Update request published.
Finished updating reported shadow value to 'red'.

步骤 2：查看来自 shadow.py中 MQTT 测试客户端中示例应用程序的消息

您可以使用 AWS IoT控制台中的 MQTT 测试客户端来监控传递在 AWS 账户中的 MQTT 消息。通过订阅 Device Shadow 服务使用的保留 MQTT 主题，您可以观察在运行示例应用程序时主题收到的消息。

如果尚未使用 MQTT 测试客户端，您可以查看 通过 AWS IoT MQTT客户端查看MQTT消息。它可以帮助您了解如何使用 AWS IoT控制台中的 MQTT 测试客户端来查看通过消息代理时的 MQTT 消息。

  1. 打开 MQTT 测试客户端

    打开 AWS IoT控制台中的 MQTT 测试客户端，以便您可以观察 MQTT 主题收到的消息，而不会丢失 MQTT 测试客户端的配置。如果您让 MQTT 测试客户端进入控制台中的其它页面，则 MQTT 测试客户端不会保留任何订阅或消息日志。对于本教程的这一部分，您可以在单独的窗口中打开 AWS IoT事物的影子文档和 MQTT 测试客户端，以便更轻松地观察与 Device Shadow 的交互。

  2. 订阅 MQTT 预留的影子主题

    您可以使用 MQTT 测试客户端输入 Device Shadow 的 MQTT 预留主题的名称，并在运行 shadow.py示例应用程序时订阅它们以接收更新。要订阅主题：

    1. 在 AWS IoT控制台中的 MQTT 测试客户端中，选择 Subscribe to a topic（订阅主题）。

    2. 在 Topic filter（主题筛选条件）部分，输入：$aws/things/thingname/shadow/update/#。在这里，thingname 是您之前创建的事物资源的名称（例如，My_light_bulb）。

    3. 保留附加配置设置的默认值，然后选择 Subscribe（订阅）。

    通过使用 # 通配符，您可以同时订阅多个 MQTT 主题，并在单个窗口中观察设备与其影子之间交换的所有消息。有关通配符及其用法的更多信息，请参阅 MQTT话题。

  3. 运行 shadow.py示例程序和观察消息

    在 Raspberry Pi 的命令行窗口中，如果您已经断开程序的连接，请再次运行示例应用程序，并在 AWS IoT控制台中的 MQTT 测试客户端观察消息。

    1. 运行以下命令以重新启动示程序。将 your-iot-thing-name 和 your-iot-endpoint 替换为您早前创建的 AWS IoT事物名称（例如，My_light_bulb）以及与设备交互的端点名称。

      cd ~/aws-iot-device-sdk-python-v2/samples
python3 shadow.py --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key --endpoint your-iot-endpoint --thing_name your-iot-thing-name

      shadow.py 示例应用程序随后会开始运行并检索当前影子状态。如果已删除影子或清除当前状态，程序会将当前值设置为 off，然后提示您输入 desired 值。

      Connecting to a3qEXAMPLEffp-ats.iot.us-west-2.amazonaws.com with client ID 'test-0c8ae2ff-cc87-49d2-a82a-ae7ba1d0ca5a'...
Connected!
Subscribing to Delta events...
Subscribing to Update responses...
Subscribing to Get responses...
Requesting current shadow state...
Launching thread to read user input...
Finished getting initial shadow state.
Shadow document lacks 'color' property. Setting defaults...
Changed local shadow value to 'off'.
Updating reported shadow value to 'off'...
Update request published.
Finished updating reported shadow value to 'off'...
Enter desired value:

      另一方面，如果程序正在运行，并且您将程序重新启动，您将看到终端中报告的最新颜色值。在 MQTT 测试客户端中，您将看到主题 $aws/things/thingname/shadow/get 和 $aws/things/thingname/shadow/get/accepted 的更新。

      假设报告的最新颜色为 green。下面显示的是 $aws/things/thingname/shadow/get/accepted JSON 文件的内容。

      {
"state": {
  "desired": {
    "welcome": "aws-iot",
    "color": "green"
  },
  "reported": {
    "welcome": "aws-iot",
    "color": "green"
  }
},
"metadata": {
  "desired": {
    "welcome": {
      "timestamp": 1620156892
    },
    "color": {
      "timestamp": 1620161643
    }
  },
  "reported": {
    "welcome": {
      "timestamp": 1620156892
    },
    "color": {
      "timestamp": 1620161643
    }
  }
},
"version": 10,
"timestamp": 1620173908
}

    2. 在终端中输入 desired值，例如 yellow。shadow.py 示例应用程序响应并在终端中显示以下消息，这些消息显示了 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'.

      在 AWS IoT 控制台中的 MQTT 测试客户端中，您会在 Subscriptions（订阅）下看到以下主题收到一条消息：

      • $aws/things/thingname/shadow/update：显示两个 desired和 updated值更改为颜色 yellow。

      • $aws/things/thingname/shadow/update/accepted：显示 desired和 reported状态当前的值及其元数据和版本信息。

      • $aws/things/thingname/shadow/update/documents：显示 desired和 reported状态之前以及当前的值，及其元数据和版本信息。

      由于文档 $aws/things/thingname/shadow/update/documents 还包含其它两个主题中包含的信息，我们可以查看该文档以查看状态信息。上一个状态显示报告的值设置为 green、其元数据和版本信息，而当前的状态显示报告的值更新为 yellow。

      {
"previous": {
  "state": {
    "desired": {
      "welcome": "aws-iot",
      "color": "green"
    },
    "reported": {
      "welcome": "aws-iot",
      "color": "green"
    }
  },
  "metadata": {
    "desired": {
      "welcome": {
        "timestamp": 1617297888
      },
      "color": {
        "timestamp": 1617297898
      }
    },
    "reported": {
      "welcome": {
        "timestamp": 1617297888
      },
      "color": {
        "timestamp": 1617297898
      }
    }
  },
  "version": 10
},
"current": {
  "state": {
    "desired": {
      "welcome": "aws-iot",
      "color": "yellow"
    },
    "reported": {
      "welcome": "aws-iot",
      "color": "yellow"
    }
  },
  "metadata": {
    "desired": {
      "welcome": {
        "timestamp": 1617297888
      },
      "color": {
        "timestamp": 1617297904
      }
    },
    "reported": {
      "welcome": {
        "timestamp": 1617297888
      },
      "color": {
        "timestamp": 1617297904
      }
    }
  },
  "version": 11
},
"timestamp": 1617297904
}

    3. 现在，如果您输入另一个 desired值，您可以看到 reported值的进一步更改和这些主题收到的消息更新。版本号也会增加 1。例如，如果您输入值 green，之前的状态会报告值 yellow，而当前状态报告值 green。

  4. 编辑影子文档以观察增量事件

    要观察对增量主题的更改，请在 AWS IoT控制台编辑影子文档。例如，您可以将 desired值更改为颜色 red。为此，请在 AWS IoT控制台中，选择 Edit（编辑），然后在 JSON 中将 desired值设置为红色，同时保持 reported设置为 green。在保存更改之前，请保持终端处于开启状态，因为您将看到终端中报告的增量消息。

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

    shadow.py 示例应用程序响应此更改，并在终端中显示指示增量的消息。在 MQTT 测试客户端中，update 主题将收到一条消息，显示对 desired和 reported值的更改。

    您还可以看到主题 $aws/things/thingname/shadow/update/delta 收到一条消息。要查看消息，请选择该主题，其列于 Subscriptions（订阅）下方。

    {
"version": 13,
"timestamp": 1617318480,
"state": {
  "color": "red"
},
"metadata": {
  "color": {
    "timestamp": 1617318480
  }
}
}

步骤 3：排除 Device Shadow 交互中的错误

运行影子示例应用程序时，在观察与 Device Shadow 服务的交互过程中可能会遇到问题。

如果程序运行成功并提示您输入 desired值，您应该能够通过使用前述影子文档和 MQTT 测试客户端来观察 Device Shadow 交互。但是，如果您无法查看交互，可以检查以下事项：

  • 在 AWS IoT控制台中检查事物名称及其影子

    如果您在影子文档中没有看到这些消息，请查看该命令，并确保它与 AWS IoT控制台 中的事物名称相符。您还可以通过选择事物资源，然后选择 Shadows（影子）来查看您是否拥有经典影子。本教程主要侧重于与经典影子的交互。

    您还可以确认您使用的设备已连接到互联网。在 AWS IoT控制台，选择您之前创建的事物，然后选择 Interact（交互）。在事物详细信息页面上，您应该会在此处看到一条消息：This thing already appears to be connected.

  • 检查您订阅的 MQTT 预留主题

    如果在 MQTT 测试客户端中看不到消息，请检查您订阅的主题是否格式正确。MQTT Device Shadow 主题具有格式 $aws/things/thingname/shadow/ 并且可能有 update、get 或者 delete 跟随其后，具体取决于要对影子执行的操作。本教程使用主题 $aws/things/thingname/shadow/#，因此请确保您在测试客户端的 Topic filter（主题筛选条件）部分订阅主题时正确输入。

    输入主题名称时，请确保 thingname 的名称与您之前创建的 AWS IoT事物的名称相同。您还可以订阅其它 MQTT 主题，以查看是否已成功执行更新。例如，您可以订阅主题 $aws/things/thingname/shadow/update/rejected 以在更新请求失败时收到一条消息，让您能够调试连接问题。有关预留主题的更多信息，请参阅 影子主题和 Device Shadow MQTT 话题。

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

在本教程中，您学习了如何：

  • 使用 shadow.py示例应用程序来指定所需的状态并更新影子的当前状态。

  • 编辑影子文档以观察增量事件以及 shadow.py示例应用程序如何响应。

  • 使用 MQTT 测试客户端订阅影子主题并在运行示例程序时观察更新。

后续步骤

您可以订阅其它 MQTT 预留主题，以观察影子应用程序的更新。例如，如果您只订阅主题 $aws/things/thingname/shadow/update/accepted，则在成功执行更新时只能看到当前状态信息。

您还可以订阅其它影子主题以调试问题或了解有关 Device Shadow 交互的详细信息，还可以调试与 Device Shadow 交互有关的任何问题。有关更多信息，请参阅 影子主题和 Device Shadow MQTT 话题。

您还可以选择通过使用命名影子或使用为 LED 而连接到 Raspberry Pi 的附加硬件来扩展您的应用程序，并使用从终端发送的消息观察其状态的变化。

有关 Device Shadow 服务以及在设备、应用程序和服务中使用该服务的详细信息，请参阅 AWS IoT Device Shadow 服务、在设备中使用影子 和 在应用程序和服务中使用影子。