翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# デバイスがオフラインになっている間にデバイスの状態をデバイスシャドウで保持する
これらのチュートリアルでは、 AWS IoT Device Shadow サービスを使用してデバイスの状態情報を保存および更新する方法を示します。JSON ドキュメントである Shadow ドキュメントは、デバイス、ローカルアプリケーション、またはサービスによって発行されたメッセージに基づいて、デバイスの状態の変化を示します。このチュートリアルでは、Shadow ドキュメントが電球の色の変化を示します。これらのチュートリアルでは、デバイスがインターネットから切断されている場合でもシャドウがこの情報を保存し、オンラインに戻ってこの情報をリクエストしたときに最新の状態情報をデバイスに返す方法も示しています。
ここに示されている順序でこれらのチュートリアルを試すことをお勧めします。この順序は、作成が必要な AWS IoT リソースと必要なハードウェアのセットアップから始まります。これは、概念を段階的に学ぶのにも役立ちます。これらのチュートリアルでは、 で使用する Raspberry Pi デバイスを設定して接続する方法を示します AWS IoT。必要なハードウェアがない場合は、選択したデバイスに適応させるか、[Amazon EC2 で仮想デバイスを作成](creating-a-virtual-thing.md)して、これらのチュートリアルに従うことができます。
**チュートリアルのシナリオの概要**
これらのチュートリアルのシナリオは、電球の色を変更し、そのデータを予約済みのシャドウトピックに発行するローカルアプリケーションまたはサービスです。これらのチュートリアルは、[インタラクティブな開始方法のチュートリアル](interactive-demo.md)で説明されている Device Shadow 機能に似ており、Raspberry Pi デバイスに実装されています。このセクションのチュートリアルでは、名前付きのシャドウまたは複数のデバイスに対応する方法を示しつつ、単一のクラシックシャドウに焦点を当てます。
以下のチュートリアルは、 AWS IoT Device Shadow サービスの使用方法を学ぶのに役立ちます。
+
**[チュートリアル: シャドウアプリケーションを実行するための Raspberry Pi の準備](create-resources-shadow.md)**
このチュートリアルでは、 に接続するための Raspberry Pi デバイスを設定する方法を示します AWS IoT。また、 AWS IoT ポリシードキュメントとモノのリソースを作成し、証明書をダウンロードして、そのモノのリソースにポリシーをアタッチします。このチュートリアルの完了には 30 分ほどかかります。
+
**[チュートリアル: Device SDK のインストールと Device Shadows のサンプルアプリケーションの実行](lightbulb-shadow-application.md)**
このチュートリアルでは、必要なツール、ソフトウェア、 AWS IoT Device SDK for Python をインストールし、サンプルシャドウアプリケーションを実行する方法を示します。このチュートリアルは、[Raspberry Pi または他のデバイスを接続する](connecting-to-existing-device.md) に示されている概念に基づいており、完了までに 20 分かかります。
+
**[チュートリアル: サンプルアプリケーションと MQTT テストクライアントを使用した Device Shadow とのやり取り](interact-lights-device-shadows.md)**
このチュートリアルでは、`shadow.py`サンプルアプリケーションと**AWS IoT コンソール**を使用して、 AWS IoT Device Shadows と電球の状態の変化との相互作用を観察する方法を示します。このチュートリアルでは、MQTT メッセージを Device Shadow の予約済みトピックに送信する方法も示しています。このチュートリアルの完了には 45 分間を要する場合があります。
**AWS IoT Device Shadow の概要**
Device Shadow は、 AWS IoT レジストリで作成した[モノのリソース](iot-thing-management.md)によって管理されるデバイスの永続的な仮想表現です。Shadow ドキュメントは、デバイスの現在の状態の情報を保存および取得するために使用される JSON または JavaScript 表記のドキュメントです。シャドウを使用すれば、デバイスがインターネットに接続されているかどうかにかかわらず、MQTT トピックまたは HTTP REST API を介してデバイスの状態を取得および設定できます。
シャドウのドキュメントには、デバイスの状態の次の側面を説明する `state` プロパティが含まれています。
+ `desired`: アプリケーションは、`desired` オブジェクトを更新することによって、デバイスプロパティの必要な状態を指定します。
+ `reported`: デバイスは、`reported` オブジェクト内の現在の状態を報告します。
+ `delta`: `delta` オブジェクト内の目的の状態と報告された状態 AWS IoT の違いを報告します。
これは、Shadow 状態ドキュメントの例です。
```
{
"state": {
"desired": {
"color": "green"
},
"reported": {
"color": "blue"
},
"delta": {
"color": "green"
}
}
}
```
デバイスの Shadow ドキュメントを更新するには、[予約済みの MQTT トピック](reserved-topics.md#reserved-topics-shadow)、HTTP で `GET`、`UPDATE`、および `DELETE` オペレーションをサポートする [Device Shadow REST API](device-shadow-rest-api.md)、ならびに [AWS IoT CLI](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot-data/index.html) を使用できます。
前の例で、`desired` 色を `yellow` に変更したいとします。これを行うには、[UpdateThingShadow](device-shadow-rest-api.md#API_UpdateThingShadow) API にリクエストを送信するか、[Update](device-shadow-mqtt.md#update-pub-sub-topic) トピック `$aws/things/THING_NAME/shadow/update` にメッセージを発行します。
```
{
"state": {
"desired": {
"color": yellow
}
}
}
```
更新は、リクエストで指定したフィールドにのみ反映されます。Device Shadow が正常に更新されると、 は`delta`トピック に新しい`desired`状態 AWS IoT を発行します`$aws/things/THING_NAME/shadow/delta`。この場合の Shadow ドキュメントは次のようになります。
```
{
"state": {
"desired": {
"color": yellow
},
"reported": {
"color": green
},
"delta": {
"color": yellow
}
}
}
```
次に、次の JSON メッセージ`$aws/things/THING_NAME/shadow/update`を含む `Update`トピックを使用して、新しい状態が AWS IoT Device 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 サービスの使用の詳細については、「[AWS IoT Device Shadow サービス](iot-device-shadows.md)」を参照してください。
デバイス、アプリケーション、およびサービスでの Device Shadow の使用の詳細については、[デバイスでのシャドウの使用](device-shadow-comms-device.md) および [アプリとサービスでのシャドウの使用](device-shadow-comms-app.md) を参照してください。
AWS IoT シャドウの操作については、「」を参照してください[シャドウとの相互作用](device-shadow-data-flow.md)。
MQTT の予約済みトピックおよび HTTP REST API については、[Device Shadow MQTT トピック](device-shadow-mqtt.md) および [Device Shadow の REST API](device-shadow-rest-api.md) を参照してください。
# チュートリアル: シャドウアプリケーションを実行するための Raspberry Pi の準備
このチュートリアルでは、Raspberry Pi デバイスをセットアップして設定し、デバイスが MQTT メッセージを接続および交換するために必要な AWS IoT リソースを作成する方法を示します。
**注記**
[Amazon EC2 を使用して仮想デバイスを作成する](creating-a-virtual-thing.md) する予定がある場合は、このページをスキップして [デバイスを設定する](configure-device.md) に進むことができます。仮想のモノを作成するときに、これらのリソースを作成します。Raspberry Pi の代わりに別のデバイスを使用したい場合は、選択したデバイスに合わせてこれらのチュートリアルに従ってみてください。
**このチュートリアルの学習内容は次のとおりです。**
+ Raspberry Pi デバイスを設定し、 で使用するように設定します AWS IoT。
+ デバイスが サービスとやり取り AWS IoT することを許可する AWS IoT ポリシードキュメントを作成します。
+ X.509 デバイス証明書にモノ AWS IoT のリソースを作成し、ポリシードキュメントをアタッチします。
モノは、 AWS IoT レジストリ内のデバイスの仮想表現です。証明書はデバイスを AWS IoT Core に認証し、ポリシードキュメントはデバイスを操作することを許可します AWS IoT。
**このチュートリアルを実行する方法**
Device Shadows の `shadow.py` サンプルアプリケーションを実行するには、 AWS IoTに接続する Raspberry Pi デバイスが必要です。ここに示されている順序でこのチュートリアルに従うことをお勧めします。この順序では、最初に Raspberry Pi とその付属内容を設定してから、ポリシーを作成し、作成したモノのリソースにポリシーをアタッチします。その後、Raspberry Pi でサポートされているグラフィカルユーザーインターフェイス (GUI) を使用してデバイスのウェブブラウザで AWS IoT コンソールを開くことで、このチュートリアルに従うことができます。これにより、接続のために証明書を Raspberry Pi に直接ダウンロードしやすくなります AWS IoT。
**このチュートリアルを開始する前に、以下の要件を満たしていることを確認してください。**
+ AWS アカウント。アカウントをお持ちではない場合、続行する前に、[セットアップ AWS アカウント](setting-up.md) に記載されている手順を完了してください。このチュートリアルを完了するには、 AWS アカウント と AWS IoT コンソールが必要です。
+ Raspberry Pi とその必要な付属内容。次が必要になります。
+ [Raspberry Pi 3 モデル B](https://www.raspberrypi.com/products/) 以降の最新のモデル。このチュートリアルは、Raspberry Pi の以前のバージョンでも機能する可能性がありますが、テストはしていません。
+ [Raspberry Pi OS (32 ビット)](https://www.raspberrypi.com/software/operating-systems/)または、それ以降。Raspberry Pi OS の最新バージョンを使用することをお勧めします。以前のバージョンの OS でも動作する可能性がありますが、テストはしていません。
+ イーサネットまたは Wi-Fi 接続。
+ キーボード、マウス、モニタ、ケーブル、および電源。
このチュートリアルの完了には 30 分ほどかかります。
## ステップ 1: Raspberry Pi デバイスをセットアップおよび設定する
このセクションでは、 で使用する Raspberry Pi デバイスを設定します AWS IoT。
**重要**
これらの指示を他のデバイスやオペレーティングシステムに合わせて適用するのが難しい場合があります。これらの指示を解釈してご利用のデバイスに適用するには、そのデバイスを十分に理解する必要があります。問題が発生した場合は、[Amazon EC2 を使用して仮想デバイスを作成する](creating-a-virtual-thing.md) または [Windows または Linux の PC または Mac を AWS IoT デバイスとして使用する](using-laptop-as-device.md) など、他のデバイスオプションのいずれかを代替策として試してください。
Raspberry Pi を設定して、オペレーティングシステム (OS) を起動し、インターネットに接続し、コマンドラインインターフェイスで Raspberry Pi とインタラクションできるようにする必要があります。Raspberry Pi でサポートされているグラフィカルユーザーインターフェイス (GUI) を使用して AWS IoT コンソールを開き、このチュートリアルの残りの部分を実行することもできます。
**Raspberry Pi をセットアップするには**
1. SD カードを Raspberry Pi の MicroSD カードスロットに挿入します。一部の SD カードには、ボードの起動後に OS をインストールするためのメニューを表示するインストールマネージャーがプリロードされています。Raspberry Pi イメージャーを使用して、カードに OS をインストールすることもできます。
1. Raspberry Pi の HDMI ポートに接続する HDMI ケーブルに、HDMI TV またはモニターを接続します。
1. キーボードとマウスを Raspberry Pi の USB ポートに接続し、電源アダプタをつないでボードを起動します。
Raspberry Pi の起動後、SD カードにインストールマネージャーがプリロードされている場合は、オペレーティングシステムをインストールするためのメニューが表示されます。OS のインストールに問題がある場合は、次の手順を試すことができます。Raspberry Pi のセットアップの詳細については、「[Raspberry Pi のセットアップ](https://projects.raspberrypi.org/en/projects/raspberry-pi-setting-up/)」を参照してください。
**Raspberry Pi のセットアップで問題が発生している場合は、以下の操作を実行します。**
+ ボードを起動する前に、SD カードを挿入したかどうかを確認してください。ボードを起動した後に SD カードを差し込むと、インストールメニューが表示されない場合があります。
+ テレビまたはモニタの電源が入っていて、正しい入力が選択されていることを確認してください。
+ Raspberry Pi と互換性のあるソフトウェアを使用していることを確認します。
Raspberry Pi OS をインストールして設定したら、Raspberry Pi のウェブブラウザを開き、 AWS IoT Core コンソールに移動して、このチュートリアルの残りのステップを続行します。
AWS IoT Core コンソールを開くことができる場合は、Raspberry Pi の準備が整い、 に進むことができます[チュートリアル: でのデバイスのプロビジョニング AWS IoT](shadow-provision-cloud.md)。
問題がある場合や、さらにサポートが必要な場合は、「[Getting help for your Raspberry Pi](https://projects.raspberrypi.org/en/projects/raspberry-pi-setting-up/5)」を参照してください。
# チュートリアル: でのデバイスのプロビジョニング AWS IoT
このセクションでは、チュートリアルで使用する AWS IoT Core リソースを作成します。
**Topics**
+ [ステップ 1: Device Shadow の AWS IoT ポリシーを作成する](#create-policy-shadow)
+ [ステップ 2: モノのリソースを作成し、ポリシーをモノにアタッチする](#create-thing-shadow)
+ [ステップ 3: 結果と次のステップを確認する](#resources-shadow-review)
## ステップ 1: Device Shadow の AWS IoT ポリシーを作成する
X.509 証明書 AWS IoT Core AWS IoT は、デバイスが Device Shadow サービスで使用される MQTT 予約トピックへのサブスクライブや発行などの AWS IoT オペレーションを実行できるようにする証明書にアタッチされます。デバイスは、接続してメッセージを送信するときに証明書を提示します AWS IoT Core。
この手順では、サンプルプログラムの実行に必要な AWS IoT オペレーションをデバイスが実行できるようにするポリシーを作成します。タスクの実行に必要なアクセス許可のみを付与するポリシーを作成することをお勧めします。最初に AWS IoT ポリシーを作成し、後で作成するデバイス証明書にアタッチします。
**AWS IoT ポリシーを作成するには**
1. 左のメニューで、[**Secure**] (安全性)、[**Policies**] (ポリシー) の順に選択します。アカウントに既存のポリシーがある場合は、**[作成]** を選択します。それ以外の場合は、**[ポリシーがまだありません]** ページで **[ポリシーの作成]** を選択します。
1. [**ポリシーの作成**] ページで、以下の手順を実行します。
1. **[名前]** フィールドに、ポリシーの名前 (**My\$1Device\$1Shadow\$1policy** など) を入力します。ポリシー名で個人を特定できる情報を使用しないでください。
1. ポリシードキュメントでは、MQTT 予約トピックを発行およびサブスクライブするアクセス許可をデバイスに付与する接続、サブスクライブ、受信、および発行アクションについて説明します。
以下のサンプルポリシーをコピーして、ポリシードキュメントに貼り付けます。`thingname` を、作成するモノの名前 ( など`My_light_bulb`)、 をサービスを使用している`region` AWS IoT リージョン、 をお客様の AWS アカウント 番号`account`に置き換えます。 AWS IoT ポリシーの詳細については、「」を参照してください[AWS IoT Core ポリシー](iot-policies.md)。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingname/shadow/get",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingname/shadow/update"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingname/shadow/get/accepted",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingname/shadow/get/rejected",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingname/shadow/update/accepted",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingname/shadow/update/rejected",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingname/shadow/update/delta"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingname/shadow/get/accepted",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingname/shadow/get/rejected",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingname/shadow/update/accepted",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingname/shadow/update/rejected",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingname/shadow/update/delta"
]
},
{
"Effect": "Allow",
"Action": "iot:Connect",
"Resource": "arn:aws:iot:us-east-1:123456789012:client/test-*"
}
]
}
```
## ステップ 2: モノのリソースを作成し、ポリシーをモノにアタッチする
に接続されたデバイスは、 AWS IoT レジストリ内の*モノのリソース*で表す AWS IoT ことができます。*モノのリソース*は、このチュートリアルの電球など、特定のデバイスまたは論理エンティティを表します。
でモノを作成する方法については AWS IoT、「」で説明されている手順に従ってください[モノのオブジェクトを作成する](create-iot-resources.md#create-aws-thing)。そのチュートリアルの手順に従うときに注意すべき重要な点がいくつかあります。
1. **[単一のモノを作成する]** を選択し、**[名前]** フィールドに、以前にポリシーを作成したときに指定した `thingname` と同じモノの名前 (例: `My_light_bulb`) を入力します。
モノを作成した後に名前を変更することはできません。`thingname` 以外の名前を付けた場合は、`thingname` という名前の新しいモノを作成し、古いモノを削除します。
**注記**
モノの名前で個人を特定できる情報を使用しないでください。モノの名前は、暗号化されていない通信やレポートに表示されることがあります。
1. **[証明書が作成されました\$1]** ページの各証明書ファイルを見つけやすい場所にダウンロードすることをお勧めします。サンプルアプリケーションを実行するには、これらのファイルをインストールする必要があります。
Raspberry Pi の `home` ディレクトリ内の `certs` サブディレクトリにファイルをダウンロードし、次の表に示されているように、各ファイルに簡素な名前を付けることをお勧めします。
**証明書ファイル名**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot/latest/developerguide/shadow-provision-cloud.html)
1. 証明書を有効にして接続を有効にしたら AWS IoT、**ポリシーをア**タッチを選択し、以前に作成したポリシー ( など**My\$1Device\$1Shadow\$1policy**) をモノにアタッチしていることを確認します。
モノを作成したら、モノのリソースが AWS IoT コンソールのモノのリストに表示されます。
## ステップ 3: 結果と次のステップを確認する
**このチュートリアルで学習した内容は次のとおりです。**
+ Raspberry Pi デバイスをセットアップおよび設定します。
+ デバイスが サービスとやり取り AWS IoT することを許可する AWS IoT ポリシードキュメントを作成します。
+ モノのリソースと関連する X.509 デバイス証明書を作成し、それにポリシードキュメントをアタッチします。
**次の手順**
AWS IoT デバイス SDK for Python をインストールし、`shadow.py`サンプルアプリケーションを実行し、Device Shadows を使用して状態を制御できるようになりました。このチュートリアルの実行方法の詳細については、[チュートリアル: Device SDK のインストールと Device Shadows のサンプルアプリケーションの実行](lightbulb-shadow-application.md) を参照してください。
# チュートリアル: Device SDK のインストールと Device Shadows のサンプルアプリケーションの実行
このセクションでは、必要なソフトウェアと AWS IoT Device SDK for Python をインストールし、`shadow.py`サンプルアプリケーションを実行して Shadow ドキュメントを編集し、シャドウの状態を制御する方法について説明します。
**このチュートリアルの学習内容は次のとおりです。**
+ インストールされているソフトウェアと AWS IoT Device SDK for Python を使用して、サンプルアプリケーションを実行します。
+ サンプルアプリケーションを使用して値を入力すると、どのように AWS IoT コンソールで目的の値が発行されるかについて説明します。
+ `shadow.py` サンプルアプリケーションと、MQTT プロトコルを使用してシャドウの状態を更新する方法を確認してください。
**このチュートリアルを実行する前に:**
をセットアップし AWS アカウント、Raspberry Pi デバイスを設定し、Device Shadow サービスの MQTT 予約済みトピックを発行およびサブスクライブするアクセス許可をデバイスに付与する AWS IoT モノとポリシーを作成しておく必要があります。詳細については、「[チュートリアル: シャドウアプリケーションを実行するための Raspberry Pi の準備](create-resources-shadow.md)」を参照してください。
Git、Python、および AWS IoT Device SDK for Python もインストールされている必要があります。このチュートリアルは、チュートリアル [Raspberry Pi または他のデバイスを接続する](connecting-to-existing-device.md) で提示された概念に基づいています。そのチュートリアルをまだ試していない場合は、そのチュートリアルで説明されている手順に従って証明書ファイルと Device SDK をインストールしてから、このチュートリアルに戻って `shadow.py` サンプルアプリケーションを実行することをお勧めします。
**Topics**
+ [ステップ 1: shadow.py サンプルアプリケーションを実行する](#run-sample-application-shadows)
+ [ステップ 2: shadow.py Device SDK サンプルアプリケーションを確認する](#review-shadow-sample-code)
+ [ステップ 3: `shadow.py` サンプルアプリケーションの問題をトラブルシューティングする](#shadow-sample-app-troubleshoot)
+ [ステップ 4: 結果と次のステップを確認する](#sample-app-shadow-review)
このチュートリアルの完了には 20 分ほどかかります。
## ステップ 1: shadow.py サンプルアプリケーションを実行する
`shadow.py` サンプルアプリケーションを実行する前に、インストールした証明書ファイルの名前と場所に加えて、次の情報が必要です。
**アプリケーションパラメータ値**
| Parameter | 値がある場所 |
| --- | --- |
| your-iot-thing-name | で前に作成した AWS IoT モノの名前[ステップ 2: モノのリソースを作成し、ポリシーをモノにアタッチする](shadow-provision-cloud.md#create-thing-shadow)。 この値を見つけるには、[AWS IoT コンソール](https://console.aws.amazon.com/iot/home)で [**Manage**] (管理) を選択し、[**Things**] (モノ) を選択します。 |
| your-iot-endpoint | *your-iot-endpoint* 値の形式は `endpoint_id-ats.iot.region.amazonaws.com` です (例: `a3qj468EXAMPLE-ats.iot.us-west-2.amazonaws.com`)。この値を検索するには: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/iot/latest/developerguide/lightbulb-shadow-application.html) |
**サンプルアプリケーションをインストールして実行する**
1. サンプルアプリディレクトリに移動します。
```
cd ~/aws-iot-device-sdk-python-v2/samples/service-clients
```
1. コマンドラインウィンドウで、示されているように *your-iot-endpoint* と *your-iot-thing-name* を置き換えて、このコマンドを実行します。
```
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
```
1. サンプルアプリケーションが次のようになっていることを観察します。
1. アカウントの AWS IoT サービスに接続します。
1. `Delta` イベントと `Update` および `Get` 応答をサブスクライブします。
1. ターミナルに必要な値を入力するように求められます。
1. 次のような出力を表示します。
```
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 contains reported value 'off'.
Enter desired value:
```
**注記**
`shadow.py` サンプルアプリケーションの実行に問題がある場合は、[ステップ 3: `shadow.py` サンプルアプリケーションの問題をトラブルシューティングする](#shadow-sample-app-troubleshoot) を確認してください。問題の修正に役立つ可能性のある追加情報を取得するには、コマンドラインに `--verbosity debug` パラメータを追加して、サンプルアプリケーションが実行内容に関する詳細メッセージを表示するようにします。
**値を入力し、Shadow ドキュメントの更新を観察する**
ターミナルに `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'.
```
この更新リクエストを発行すると、 はモノのリソースのデフォルトのクラシックシャドウ AWS IoT を作成します。 AWS IoT コンソールで `reported`および `desired`値に発行した更新リクエストを確認するには、作成したモノのリソースの Shadow ドキュメントを確認します (例: `My_light_bulb`)。Shadow ドキュメントで更新を表示するには、次の操作を行います。
1. AWS IoT コンソールで、**管理**を選択し、**モノ**を選択します。
1. 表示されるモノのリストで、作成したモノを選択し、[**Shadows**] (シャドウ) を選択してから、[**Classic Shadow**] (クラシックシャドウ) を選択します。
Shadow ドキュメントは次のようになり、色 `yellow` に設定された `reported` と `desired` の値が表示されます。これらの値は、ドキュメントの **[Shadow の状態]** のセクションに表示されます。
```
{
"desired": {
"welcome": "aws-iot",
"color": "yellow"
},
"reported": {
"welcome": "aws-iot",
"color": "yellow"
}
}
```
リクエストのタイムスタンプ情報とバージョン番号を含む **[メタデータ]** セクションも表示されます。
状態ドキュメントのバージョンを使用して、デバイスのシャドウのドキュメントの最新バージョンを更新していることを確認できます。別の更新リクエストを送信すると、バージョン番号が 1 ずつ増えます。更新リクエストでバージョンを渡したとき、そのバージョンと状態ドキュメントの現在のバージョンとが一致しない場合、サービスは HTTP 409 conflict レスポンスコードでリクエストを拒否します。
```
{
"metadata": {
"desired": {
"welcome": {
"timestamp": 1620156892
},
"color": {
"timestamp": 1620156893
}
},
"reported": {
"welcome": {
"timestamp": 1620156892
},
"color": {
"timestamp": 1620156893
}
}
},
"version": 10
}
```
Shadow ドキュメントについてさらに学び、状態情報の変化を観察するには、このチュートリアルの [ステップ 4: 結果と次のステップを確認する](#sample-app-shadow-review) セクションで説明されている次のチュートリアル [チュートリアル: サンプルアプリケーションと MQTT テストクライアントを使用した Device Shadow とのやり取り](interact-lights-device-shadows.md) に進んでください。必要に応じて、次のセクションで `shadow.py` サンプルコードとそれが MQTT プロトコルを使用する方法について学ぶこともできます。
## ステップ 2: shadow.py Device SDK サンプルアプリケーションを確認する
このセクションでは、このチュートリアルで使用されている **AWS IoT Device SDK v2 for Python** の `shadow.py` サンプルアプリケーションを確認します。ここでは、MQTT および MQTT over WSS プロトコル AWS IoT Core を使用して に接続する方法を確認します。[AWS 共通ランタイム (AWS-CRT)](https://github.com/awslabs/aws-crt-python#aws-crt-python) ライブラリは、低レベルの通信プロトコルサポートを提供し、 AWS IoT Device SDK v2 for Python に含まれています。
このチュートリアルでは MQTT と MQTT over WSS を使用していますが、 は HTTPS リクエストを発行するデバイス AWS IoT をサポートしています。デバイスから HTTP メッセージを送信する Python プログラムの例については、Python の `requests` ライブラリを使用した [HTTPS コード例](http.md#codeexample)を参照してください。
デバイス通信に使用するプロトコルについて十分な情報に基づいた決定を行う方法については、[デバイス通信用のアプリケーションプロトコルの選択](protocols.md#protocol-selection) を確認してください。
**MQTT**
`shadow.py` サンプルでは、[https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py](https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py) の `mtls_from_path` (以下に示されています) を呼び出して、MQTT プロトコルを使用して AWS IoT Core との接続を確立します。`mtls_from_path` では、X.509 証明書と TLS v1.2 を使用してデバイスを認証します。 AWS 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
)
```
+ `endpoint` は、コマンドラインから渡した AWS IoT エンドポイントであり、 でこのデバイスを一意に識別する ID `client_id`です AWS リージョン。
+ `cert_filepath`、`pri_key_filepath`、および `ca_filepath` は、デバイスの証明書とプライベートキーファイル、およびルート CA ファイルへのパスです。
+ `client_bootstrap` は、ソケット通信アクティビティを処理する共通のランタイムオブジェクトであり、`mqtt_connection_builder.mtls_from_path` の呼び出しの前にインスタンス化されます。
+ `on_connection_interrupted` および `on_connection_resumed` は、デバイスの接続が中断されて再開されるときに呼び出すコールバック関数です。
+ `clean_session` は、新しい永続セッションを開始するか、既存のセッションに再接続するか (存在する場合) です。`keep_alive_secs` は `CONNECT` リクエストで送信するキープアライブ値 (秒単位) です。この間隔で ping が自動的に送信されます。サーバーは、この値の 1.5 倍の時間が経過しても ping を受信しなかった場合、接続が失われたとみなします。
この `shadow.py` サンプルでは、WSS 経由で MQTT プロトコルを使用して AWS IoT Core との接続を確立するために [https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py](https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py) の `websockets_with_default_aws_signing` も呼び出します。MQTT over WSS も MQTT と同じパラメータを使用し、次の追加パラメータを受け取ります。
+ `region` は、 AWS 署名 V4 認証で使用される署名リージョンであり、認証に使用するために提供される AWS 認証情報`credentials_provider`です。リージョンはコマンドラインから渡され、`credentials_provider` オブジェクトは `mqtt_connection_builder.websockets_with_default_aws_signing` の呼び出しの直前にインスタンス化されます。
+ `websocket_proxy_options` は、プロキシホストを使用する場合の HTTP プロキシオプションです。`shadow.py` サンプルアプリケーションでは、この値は `mqtt_connection_builder.websockets_with_default_aws_signing` の呼び出しの直前にインスタンス化されます。
**Shadow トピックとイベントをサブスクライブする**
`shadow.py` サンプルは接続の確立を試み、完全に接続されるまで待機します。接続されていない場合、コマンドはキューに入れられます。接続されると、サンプルはデルタイベントをサブスクライブし、メッセージを更新および取得し、サービスの品質 (QoS) レベル 1 (`mqtt.QoS.AT_LEAST_ONCE`) でメッセージを発行します。
デバイスが QoS レベル 1 のメッセージをサブスクライブすると、メッセージブローカーは、デバイスに送信できるようになるまで、デバイスがサブスクライブしているメッセージを保存します。メッセージブローカーは、デバイスから `PUBACK` 応答を受信するまでメッセージを再送信します。
MQTT プロトコルの詳細については、[MQTT プロトコルを確認する](sdk-tutorials.md#sdk-tutorials-mqtt-review) および [MQTT](mqtt.md) を参照してください。
このチュートリアルで使用される MQTT、MQTT over WSS、永続セッション、および QoS レベルの詳細については、「[pubsub.py Device SDK サンプルアプリケーションを確認する](sdk-tutorials.md#sdk-tutorials-explore-sample)」を参照してください。
## ステップ 3: `shadow.py` サンプルアプリケーションの問題をトラブルシューティングする
`shadow.py` サンプルアプリケーションを実行すると、ターミナルにいくつかのメッセージが表示され、`desired` 値を入力するように求められます。プログラムがエラーをスローした場合、エラーをデバッグするには、まずシステムに対して正しいコマンドを実行したかどうかを確認します。
場合によっては、エラーメッセージは接続の問題を示し、`Host name was invalid for dns resolution` または `Connection was closed unexpectedly` のようになることがあります。このような場合、次のことを確認してみてください。
+
**コマンド内のエンドポイントアドレスを確認する**
サンプルアプリケーションを実行するために入力したコマンドの `endpoint` 引数 (例: `a3qEXAMPLEffp-ats.iot.us-west-2.amazonaws.com`) を確認し、**AWS IoT コンソール**でこの値を確認します。
正しい値を使用したかどうかを確認するには、次の手順に従います。
1. **AWS IoT コンソール**で、[**Manage**] (管理)、[**Things**] (モノ) の順に選択します。
1. サンプルアプリケーション用に作成したモノ (例: **My\$1light\$1bulb**) を選択してから、[**Interact**] (操作) を選択します。
モノの詳細ページで エンドポイントは、[**HTTPS**] セクションに表示されます。また、以下を記載したメッセージも表示されます: `This thing already appears to be connected.`。
+
**証明書の有効化を確認する**
証明書は、 を使用してデバイスを認証します AWS IoT Core。
証明書がアクティブかどうかを確認するには、次の手順に従います。
1. **AWS IoT コンソール**で、[**Manage**] (管理)、[**Things**] (モノ) の順に選択します。
1. サンプルアプリケーション用に作成したモノ (例: **My\$1light\$1bulb**) を選択してから、[**Security**] (セキュリティ) を選択します。
1. 証明書を選択し、証明書の詳細ページで [証明書の選択] を選択してから、証明書の詳細ページで **[アクション]** を選択します。
ドロップダウンリストで **[有効化]** が使用できず、**[無効化]** しか選択できない場合、証明書は有効です。そうでない場合は、**[有効化]** を選択し、サンプルプログラムを再実行します。
それでもプログラムが実行されない場合は、`certs` フォルダ内の証明書ファイル名を確認してください。
+
**モノのリソースにアタッチされているポリシーを確認する**
証明書がデバイスを認証している間、 AWS IoT ポリシーにより、デバイスは MQTT 予約済みトピックへのサブスクライブや発行などの AWS IoT オペレーションを実行できます。
正しいポリシーがアタッチされているかどうかを確認するには、次の手順に従います。
1. 前述したとおりに証明書を検索し、**[ポリシー]** を選択します。
1. 表示されたポリシーを選択し、デバイスに MQTT 予約トピックへ発行およびサブスクライブするためのアクセス許可を付与する `connect`、`subscribe`、`receive`、および `publish` アクションが説明されているかどうかを確認します。
サンプルポリシーについては、[ステップ 1: Device Shadow の AWS IoT ポリシーを作成する](shadow-provision-cloud.md#create-policy-shadow) を参照してください。
への接続に問題があることを示すエラーメッセージが表示された場合は AWS IoT、ポリシーに使用しているアクセス許可が原因である可能性があります。その場合は、 AWS IoT リソースへのフルアクセスを提供するポリシーから開始し、サンプルプログラムを再実行することをお勧めします。現在のポリシーを編集するか、現在のポリシーを選択して [**Detach**] (デタッチ) を選択し、フルアクセスを提供する別のポリシーを作成してモノのリソースにアタッチすることができます。後で、プログラムの実行に必要なアクションとポリシーのみにポリシーを制限できます。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:*"
],
"Resource": "*"
}
]
}
```
+
**Device SDK のインストールを確認する**
それでもプログラムが実行されない場合は、Device SDK を再インストールして、SDK のインストールが完了していて正しいことを確認できます。
## ステップ 4: 結果と次のステップを確認する
**このチュートリアルで学習した内容は次のとおりです。**
+ 必要なソフトウェア、ツール、および AWS IoT Device SDK for Python をインストールします。
+ サンプルアプリケーション `shadow.py` が、シャドウの現在の状態を取得および更新するために MQTT プロトコルを使用する方法を理解します。
+ Device Shadows のサンプルアプリケーションを実行し、 AWS IoT コンソールで Shadow ドキュメントの更新を確認します。また、プログラムの実行時に問題をトラブルシューティングし、エラーを修正する方法も学びました。
**次の手順**
これで、`shadow.py` サンプルアプリケーションを実行し、Device Shadow を使用して状態を制御できます。 AWS IoT コンソールで Shadow ドキュメントの更新を観察し、サンプルアプリケーションが応答するデルタイベントを観察できます。MQTT テストクライアントを使用して、予約済みのシャドウトピックにサブスクライブし、サンプルプログラムの実行時にトピックが受信するメッセージを観察できます。このチュートリアルの実行方法の詳細については、[チュートリアル: サンプルアプリケーションと MQTT テストクライアントを使用した Device Shadow とのやり取り](interact-lights-device-shadows.md) を参照してください。
# チュートリアル: サンプルアプリケーションと MQTT テストクライアントを使用した Device Shadow とのやり取り
`shadow.py` サンプルアプリケーションを操作するには、`desired` の値のためにターミナルに値を入力します。たとえば、トラフィックライトに似た色を指定してリクエストに AWS IoT 応答し、報告された値を更新できます。
**このチュートリアルの学習内容は次のとおりです。**
+ `shadow.py` サンプルアプリケーションを使用して、必要な状態を指定し、シャドウの現在の状態を更新します。
+ Shadow ドキュメントを編集して、デルタイベントと、`shadow.py` サンプルアプリケーションがそれにどのように応答するかを観察します。
+ MQTT テストクライアントを使用して、シャドウトピックをサブスクライブし、サンプルプログラムを実行するときに更新を確認します。
**このチュートリアルを実行する前に、以下の条件を満たす必要があります。**
をセットアップし AWS アカウント、Raspberry Pi デバイスを設定し、モノとポリシーを作成 AWS IoT しました。また、必要なソフトウェア、Device SDK、証明書ファイルをインストールし、ターミナルでサンプルプログラムを実行する必要があります。詳細については、前のチュートリアルの [チュートリアル: シャドウアプリケーションを実行するための Raspberry Pi の準備](create-resources-shadow.md) および [ステップ 1: shadow.py サンプルアプリケーションを実行する](lightbulb-shadow-application.md#run-sample-application-shadows) を参照してください。これらのチュートリアルをまだ完了していない場合は、完了する必要があります。
**Topics**
+ [ステップ 1: `shadow.py` サンプルアプリケーションを使用して、必要な値と報告された値を更新する](#update-desired-shadow-sample)
+ [ステップ 2: MQTT テストクライアントで `shadow.py` サンプルアプリケーションからのメッセージを表示する](#shadow-sample-view-msg)
+ [ステップ 3: Device Shadow インタラクションに関するエラーをトラブルシューティングする](#shadow-observe-messages-troubleshoot)
+ [ステップ 4: 結果と次のステップを確認する](#sample-shadow-review)
このチュートリアルの完了には 45 分ほどかかります。
## ステップ 1: `shadow.py` サンプルアプリケーションを使用して、必要な値と報告された値を更新する
前のチュートリアル では[ステップ 1: shadow.py サンプルアプリケーションを実行する](lightbulb-shadow-application.md#run-sample-application-shadows)、セクション で説明されているように目的の値を入力するときに、 AWS IoT コンソールで Shadow ドキュメントに発行されたメッセージを確認する方法を学習しました[チュートリアル: Device SDK のインストールと Device Shadows のサンプルアプリケーションの実行](lightbulb-shadow-application.md)。
前の例では、目的の色を `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`) を入力して、目的の状態を発行します。
1. `desired` 状態が `reported` 状態 (色 `green` など) と異なるため、デルタが発生し、デルタにサブスクライブしているアプリケーションがこのメッセージを受信します。
1. アプリケーションはメッセージに応答し、その状態を `desired` 値 `yellow` に更新します。
1. その後、アプリケーションはデバイスの状態 `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 コンソールでは、Shadow ドキュメントは `reported`フィールドと `desired`フィールド`green`の両方で に更新された値を反映し、バージョン番号は 1 ずつ増加します。例えば、以前のバージョン番号が 10 と表示されていた場合、現在のバージョン番号は 11 と表示されます。
**注記**
シャドウを削除しても、バージョン番号は 0 にリセットされません。更新リクエストを発行するか、同じ名前で別のシャドウを作成すると、シャドウバージョンが 1 ずつ増加することがわかります。
**Shadow ドキュメントを編集してデルタイベントを観察する**
`shadow.py` サンプルアプリケーションも `delta` イベントにサブスクライブしており、`desired` 値が変更されると応答します。例えば、`desired` 値を色 `red` に変更できます。これを行うには、 AWS IoT コンソールで、**編集**をクリックして Shadow ドキュメントを編集し、`desired`値を に設定しながら JSON `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: MQTT テストクライアントで `shadow.py` サンプルアプリケーションからのメッセージを表示する
**AWS IoT コンソール**で** MQTT テストクライアント**を使用して、 AWS アカウントで渡される MQTT メッセージをモニタリングできます。Device Shadow サービスで使用される予約済みの MQTT トピックにサブスクライブすることで、サンプルアプリケーションの実行時にトピックが受信するメッセージを観察できます。
MQTT テストクライアントをまだ使用していない場合は、[MQTT クライアントで AWS IoT MQTT メッセージを表示する](view-mqtt-messages.md) を確認できます。これは、**AWS IoT コンソール**で **MQTT テストクライアント**を使用して、メッセージブローカーを通過する MQTT メッセージを表示する方法を学ぶのに役立ちます。
1.
**MQTT テストクライアントを開く**
[AWS IoT コンソールの新しいウィンドウで MQTT テストクライアント](https://console.aws.amazon.com//iot/home#/test)を開きます。これにより、MQTT テストクライアントの設定を失うことなく、MQTT トピックによって受信されたメッセージを観察できます。MQTT テストクライアントからコンソールの別のページに移動すると、サブスクリプションまたはメッセージログは保持されません。チュートリアルのこのセクションでは、 AWS IoT モノの Shadow ドキュメントと MQTT テストクライアントを別々のウィンドウで開いて、Device Shadows とのやり取りをより簡単に観察できます。
1.
**MQTT 予約済み Shadow トピックをサブスクライブする**
MQTT テストクライアントを使用して、Device Shadow の MQTT 予約済みトピックの名前を入力し、サブスクライブして、`shadow.py` サンプルアプリケーションの実行時に更新を受け取ることができます。トピックにサブスクライブするには:
1. **AWS IoT コンソール**の **MQTT テストクライアント**で、[**Subscribe to a topic**] (トピックへサブスクライブする) を選択します。
1. [**Topic filter**] (トピックフィルター) のセクションで、**\$1aws/things/*thingname*/shadow/update/\$1** と入力します。ここで、`thingname` は以前に作成したモノのリソースの名前です (例: `My_light_bulb`)。
1. 追加の構成設定はデフォルト値のままにして、**[サブスクライブ]** を選択します。
トピックサブスクリプションで **\$1** ワイルドカードを使用すると、複数の MQTT トピックを同時にサブスクライブし、デバイスとその Shadow の間で交換されるすべてのメッセージを単一のウィンドウで観察できます。ワイルドカード文字とその使用の詳細については、「[MQTT トピック](topics.md)」を参照してください。
1.
**`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/service-clients
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 テストクライアントでは、トピック **\$1aws/things/*thingname*/shadow/get** および **\$1aws/things/*thingname*/shadow/get/accepted** の更新が表示されます。
報告された最新の色が `green` であるとします。以下は、**\$1aws/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
}
```
1. `yellow` など、ターミナルに `desired` 値を入力します。`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 テストクライアント]** の **[サブスクリプション]** で、次のトピックがメッセージを受信したことがわかります。
+ **\$1aws/things/*thingname*/shadow/update**: `desired` と `updated` 値の両方が色 `yellow` に変化することを示しています。
+ **\$1aws/things/*thingname*/shadow/update/accepted**: `desired` および `reported` 状態の現在の値、およびそれらのメタデータとバージョン情報を表示します。
+ **\$1aws/things/*thingname*/shadow/update/documents**: `desired` および `reported` 状態の以前の値と現在の値、およびそれらのメタデータとバージョン情報を表示します。
ドキュメント **\$1aws/things/*thingname*/shadow/update/documents** にも他の 2 つのトピックに含まれる情報が含まれているため、これで状態情報を確認できます。以前の状態は、`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
}
```
1. ここで、別の `desired` 値を入力すると、`reported` 値のさらなる変更と、これらのトピックで受信したメッセージの更新が表示されます。バージョン番号も 1 ずつ増分します。例えば、値 `green` を入力すると、以前の状態が値 `yellow` を報告し、現在の状態が値 `green` を報告します。
1.
**Shadow ドキュメントを編集してデルタイベントを観察する**
デルタトピックへの変更を観察するには、 AWS IoT コンソールで Shadow ドキュメントを編集します。例えば、`desired` 値を色 `red` に変更できます。これを行うには、 AWS IoT コンソールで**編集**を選択し、`desired`値を に設定したまま JSON で`reported`値を赤に設定します`green`。変更を保存する際はターミナルを開いたままにしておいてください。ターミナルに報告されたデルタメッセージが表示されます。
```
{
"desired": {
"welcome": "aws-iot",
"color": "red"
},
"reported": {
"welcome": "aws-iot",
"color": "green"
}
}
```
`shadow.py` サンプルアプリケーションはこの変更に応答し、デルタを示すメッセージをターミナルに表示します。MQTT テストクライアントでは、`update` トピックは、`desired` および `reported` 値の変更を示すメッセージを受け取ります。
また、トピック **\$1aws/things/*thingname*/shadow/update/delta** がメッセージを受信したこともわかります。メッセージを表示するには、**[サブスクリプション]** の下にリストされているこのトピックを選択します。
```
{
"version": 13,
"timestamp": 1617318480,
"state": {
"color": "red"
},
"metadata": {
"color": {
"timestamp": 1617318480
}
}
}
```
## ステップ 3: Device Shadow インタラクションに関するエラーをトラブルシューティングする
Shadow サンプルアプリケーションを実行すると、Device Shadow サービスとのインタラクションの観察に関する問題が発生する場合があります。
プログラムが正常に実行され、`desired` 値を入力するように求められた場合は、前述のように Shadow ドキュメントと MQTT テストクライアントを使用して、Device Shadow のインタラクションを観察できるはずです。ただし、インタラクションが表示されない場合は、次のことを確認できます。
+
**AWS IoT コンソールでモノの名前とそのシャドウを確認する**
Shadow ドキュメントにメッセージが表示されない場合は、コマンドを確認して、**AWS IoT コンソール**のモノの名前と一致していることを確認してください。モノのリソースを選択してから [**Shadows**] (シャドウ) を選択することで、クラシックシャドウがあるかどうかを確認することもできます。このチュートリアルは、主にクラシックシャドウとのインタラクションに焦点を当てています。
使用したデバイスがインターネットに接続されていることも確認できます。**AWS IoT コンソール**で、以前に作成したモノを選択してから、[**Interact**] (操作) を選択します。モノの詳細ページに、次を記載したメッセージが表示されます: `This thing already appears to be connected.`。
+
**サブスクライブした MQTT 予約済みトピックを確認する**
メッセージが MQTT テストクライアントに表示されない場合は、サブスクライブしたトピックの形式が正しいかどうかを確認してください。MQTT デバイスシャドウトピックの形式は **\$1aws/things/*thingname*/shadow/** であり、シャドウで実行するアクションに応じて、`update`、`get`、または `delete` がそれに続く場合があります。このチュートリアルでは、トピック **\$1aws/things/*thingname*/shadow/\$1** を使用しているため、テストクライアントの [**Topic filter**] (トピックフィルター) セクションでトピックをサブスクライブするときに、正しく入力したことを確認してください。
トピック名を入力するときは、*モノの名前*が前に作成した AWS IoT モノの名前と同じであることを確認します。追加の MQTT トピックにサブスクライブして、更新が正常に実行されたかどうかを確認することもできます。例えば、接続の問題をデバッグできるように、トピック **\$1aws/things/*thingname*/shadow/update/rejected** にサブスクライブして、更新リクエストが失敗したときにメッセージを受信します。予約されているトピックの詳細については、[シャドウトピック](reserved-topics.md#reserved-topics-shadow) および [Device Shadow MQTT トピック](device-shadow-mqtt.md) を参照してください。
## ステップ 4: 結果と次のステップを確認する
**このチュートリアルで学習した内容は次のとおりです。**
+ `shadow.py` サンプルアプリケーションを使用して、必要な状態を指定し、シャドウの現在の状態を更新します。
+ Shadow ドキュメントを編集して、デルタイベントと、`shadow.py` サンプルアプリケーションがそれにどのように応答するかを観察します。
+ MQTT テストクライアントを使用して、シャドウトピックをサブスクライブし、サンプルプログラムを実行するときに更新を確認します。
**次のステップ**
追加の MQTT 予約トピックにサブスクライブして、シャドウアプリケーションの更新を監視できます。例えば、トピック **\$1aws/things/*thingname*/shadow/update/accepted** のみをサブスクライブする場合、更新が正常に実行されると、現在の状態情報のみが表示されます。
追加のシャドウトピックにサブスクライブして、問題をデバッグしたり、Device Shadow のインタラクションの詳細を確認したり、Device Shadow のインタラクションに関する問題をデバッグしたりすることもできます。詳細については、「[シャドウトピック](reserved-topics.md#reserved-topics-shadow)」および「[Device Shadow MQTT トピック](device-shadow-mqtt.md)」を参照してください。
名前付きシャドウを使用するか、LED 用に Raspberry Pi に接続された追加のハードウェアを使用してアプリケーションを拡張し、ターミナルから送信されたメッセージを使用して状態の変化を観察することもできます。
Device Shadow サービス、デバイスでのサービスの使用、アプリケーションの使用、およびサービスの使用の詳細については、[AWS IoT Device Shadow サービス](iot-device-shadows.md)、[デバイスでのシャドウの使用](device-shadow-comms-device.md)、および [アプリとサービスでのシャドウの使用](device-shadow-comms-app.md) を参照してください。