デバイスでのシャドウの使用

このセクションでは、デバイスが Device Shadow サービスと通信するのに推奨される方法である MQTT メッセージを使用したシャドウとの AWS IoT デバイス通信について説明します。

シャドウ通信は、MQTT のパブリッシュ/サブスクライブ通信モデルを使用して、リクエスト/レスポンスモデルをエミュレートします。すべてのシャドウアクションは、リクエストトピック、成功したレスポンストピック (accepted)、エラーレスポンストピック (rejected) で構成されます。

アプリとサービスで、デバイスが接続されているかどうかを判別できるようにする場合は、「デバイスが接続されていることの’検出」を参照してください。

重要

MQTT は発行/サブスクライブ通信モデルを使用するため、リクエストトピックを発行する前にレスポンストピックをサブスクライブする必要があります。そうでない場合、発行するリクエストに対するレスポンスを受信しない可能性があります。

AWS IoT Device SDK を使用して Device Shadow サービス API を呼び出す場合、これは自動的に処理されます。

このセクションの例では、この表で説明されているように、 が名前付きシャドウまたは名前のないシャドウを参照ShadowTopicPrefixできる トピックの省略形を使用します。

シャドウは、名前付き、または名前のないもの (クラシック) にすることができます。それぞれで使用されるトピックは、トピックのプレフィックスでのみ異なります。この表は、各シャドウタイプで使用されるトピックのプレフィックスを示しています。

ShadowTopicPrefix 値	シャドウタイプ
$aws/things/thingName/shadow	名前のない (クラシック) シャドウ
$aws/things/thingName/shadow/name/shadowName	名前付きシャドウ

重要

アプリまたはサービスによるシャドウの使用が一貫しており、デバイス内の対応する実装でサポートされていることを確認してください。たとえば、シャドウの作成、更新、削除方法を考えてみましょう。また、デバイスおよびシャドウを介してデバイスにアクセスするアプリまたはサービスでの更新の処理方法も考慮してください。デバイスの状態がどのように更新され、報告され、アプリやサービスがデバイスとそのシャドウとどのように相互作用するかを明確に設計する必要があります。

完全なトピックを作成するには、次の表に示すように、参照するシャドウのタイプの ShadowTopicPrefix を選択し、thingName と、shadowName (該当する場合) を対応する値に置き換え、トピックスタブに追加します。トピックでは大文字と小文字が区別されることに注意してください。

シャドウ用に予約されているトピックの詳細については、シャドウトピック を参照してください。

への最初の接続時にデバイスを初期化する AWS IoT

デバイスが に登録されると AWS IoT、サポートするシャドウのこれらの MQTT メッセージをサブスクライブする必要があります。

トピック	意味	このトピックの受信時にデバイスが実行するアクション
ShadowTopicPrefix/delete/accepted	delete リクエストが受け入れられ、シャドウ AWS IoT が削除されました。	更新の発行を停止するなど、削除されたシャドウに対応するために必要なアクション。
ShadowTopicPrefix/delete/rejected	delete リクエストは によって拒否 AWS IoT され、シャドウは削除されませんでした。メッセージ本文には、エラー情報が含まれています。	メッセージ本文内のエラーメッセージに応答します。
ShadowTopicPrefix/get/accepted	get リクエストは によって受け入れられ AWS IoT、メッセージ本文に現在のシャドウドキュメントが含まれています。	メッセージ本文内の状態ドキュメントを処理するために必要なアクション。
ShadowTopicPrefix/get/rejected	get リクエストは によって拒否され AWS IoT、メッセージ本文にエラー情報が含まれています。	メッセージ本文内のエラーメッセージに応答します。
ShadowTopicPrefix/update/accepted	update リクエストは によって受け入れられ AWS IoT、メッセージ本文に現在のシャドウドキュメントが含まれています。	メッセージ本文の更新されたデータがデバイスの状態と一致することを確認します。
ShadowTopicPrefix/update/rejected	update リクエストは によって拒否され AWS IoT、メッセージ本文にエラー情報が含まれています。	メッセージ本文内のエラーメッセージに応答します。
ShadowTopicPrefix/update/delta	シャドウドキュメントは へのリクエストによって更新され AWS IoT、メッセージ本文にはリクエストされた変更が含まれています。	メッセージ本文内の目的の状態と一致するようにデバイスの状態を更新します。
ShadowTopicPrefix/update/documents	シャドウの更新が最近完了し、メッセージ本文に現在のシャドウドキュメントが含まれています。	メッセージ本文の更新された状態が、デバイスの状態と一致することを確認します。

各シャドウの前の表のメッセージにサブスクライブした後、デバイスがサポートするシャドウがすでに作成されているかどうかをテストして、各シャドウに /get トピックを発行します。/get/accepted メッセージを受信すると、メッセージ本文にはシャドウドキュメントが含まれます。シャドウドキュメントは、デバイスがその状態を初期化するために使用できます。/get/rejected メッセージを受信した場合は、現在のデバイス状態の /update メッセージを発行してシャドウを作成する必要があります。

例えば、モノ My_IoT_Thing があるとします。クラシックシャドウや名前の付いたシャドウはありません。今予約済みトピック $aws/things/My_IoT_Thing/shadow/get に /get リクエストを発行する場合、モノにシャドウがないため $aws/things/My_IoT_Thing/shadow/get/rejected トピックのエラーが返されます。このエラーを解決するには、まず次のペイロードなど、現在のデバイス状態の $aws/things/My_IoT_Thing/shadow/update トピックを使用して /update メッセージを発行します。

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

これで モノのクラシックシャドウが作成され、$aws/things/My_IoT_Thing/shadow/update/accepted トピックへメッセージが発行されます。トピック $aws/things/My_IoT_Thing/shadow/get に発行する場合、デバイスの状態に関する $aws/things/My_IoT_Thing/shadow/get/accepted トピックを返します。

名前付きシャドウの場合、Get リクエストを使用する前に、最初に名前付きシャドウを作成するか、シャドウ名で更新を発行する必要があります。例えば、名前の付いたシャドウ namedShadow1 を作成するには、まず、デバイスの状態情報をトピック $aws/things/My_IoT_Thing/shadow/name/namedShadow1/update に発行します。状態情報を取得するには、名前付きシャドウ $aws/things/My_IoT_Thing/shadow/name/namedShadow1/get の /get リクエストを使用します。

デバイスが に接続されている間のメッセージの処理 AWS IoT

デバイスが に接続されている間は AWS IoT、/update/delta メッセージを受信でき、シャドウ内の変更とデバイスの状態が一致させる必要があります。

1. 受信したすべての /update/delta メッセージを読み取り、一致するようにデバイスの状態を同期します。

2. デバイスの状態が変更されるたびに、デバイスの現在の状態を含む reported メッセージ本文を含む /update メッセージを発行します。

デバイスが接続されている間は、これらのメッセージが表示されたら発行する必要があります。

表示	トピック	Payload
デバイスの状態が変更されました。	ShadowTopicPrefix/update	reported プロパティを持つシャドウドキュメント。
デバイスがシャドウと同期していない可能性があります。	ShadowTopicPrefix/get	(空)
デバイスに対するアクションは、デバイスの削除または交換時など、デバイスによってシャドウがサポートされなくなることを示します	ShadowTopicPrefix/delete	(空)

デバイスが に再接続したときのメッセージの処理 AWS IoT

1 つ以上のシャドウを持つデバイスが に接続する場合 AWS IoT、その状態を、以下によってサポートされるすべてのシャドウの状態と同期する必要があります。

1. 受信したすべての /update/delta メッセージを読み取り、一致するようにデバイスの状態を同期します。

2. デバイスの現在の状態を記載した reported メッセージ本文を含む /update メッセージを発行します。