翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
このトピックでは、シャドウを操作するために AWS IoT が提供する 3 つの方法のそれぞれに関連するメッセージについて説明します。これらの方法には、次のものがあります。
UPDATE
-
存在しない場合はシャドウを作成します。メッセージ本文に指定された状態情報で既存のシャドウの内容を更新します。 AWS IoT は、更新ごとにタイムスタンプを記録して、状態が最後に更新された日時を示します。シャドウの状態が変わる
desired
と、 AWS IoT は とreported
の状態の違いについて、すべてのMQTTサブスクライバーに/delta
メッセージを送信します。/delta
メッセージを受信するデバイスまたはアプリは、違いに基づいてアクションを実行できます。たとえば、デバイスは自らの状態を desired 状態に更新でき、アプリケーションはデバイスの状態の変更を表示するようにその UI を更新できます。 GET
-
メタデータを含むシャドウの完全な状態を含む現在のシャドウドキュメントを取得します。
DELETE
-
デバイスシャドウとそのコンテンツを削除します。
削除したデバイスシャドウドキュメントを復元することはできませんが、削除したデバイスシャドウドキュメントの名前で新しいデバイスシャドウを作成することはできます。過去 48 時間以内に削除されたものと同じ名前のデバイスシャドウドキュメントを作成した場合、新しいデバイスシャドウドキュメントのバージョン番号は、削除されたデバイスのシャドウドキュメントのバージョン番号の続きになります。デバイスシャドウドキュメントが 48 時間より前に削除されている場合、同じ名前の新しいデバイスシャドウドキュメントのバージョン番号は 0 になります。
プロトコルサポート
AWS IoT は、シャドウとやり取りするための MQTT
状態の要求と報告
AWS IoT および シャドウを使用して IoT ソリューションを設計する場合は、変更をリクエストするアプリケーションまたはデバイスと、それらを実装するアプリケーションまたはデバイスを決定する必要があります。通常、デバイスは変更をシャドウに実装して報告し、アプリとサービスはシャドウの変更に応答して要求します。ソリューションは異なる場合がありますが、このトピックの例では、クライアントアプリまたはサービスがシャドウの変更を要求し、デバイスがその変更を実行してシャドウに報告することを前提としています。
シャドウの更新
アプリまたはサービスは、 を使用するUpdateThingShadowAPIか、 /updateトピックに発行することで、シャドウの状態を更新できます。更新は、リクエストで指定したフィールドにのみ反映されます。
クライアントが状態の変更を要求したときのシャドウの更新
クライアントがMQTTプロトコルを使用してシャドウの状態変更をリクエストした場合
-
クライアントには、変更するプロパティを識別できるように、現在のシャドウドキュメントが必要です。現在のシャドウドキュメントを取得する方法については、/get アクションを参照してください。
-
クライアントは、次のMQTTトピックをサブスクライブします。
-
$aws/things/
thingName
/shadow/name/shadowName
/update/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/update/rejected -
$aws/things/
thingName
/shadow/name/shadowName
/update/delta -
$aws/things/
thingName
/shadow/name/shadowName
/update/documents
-
-
クライアントは、シャドウの desired 状態を含む状態ドキュメントを持つ
$aws/things/
リクエストトピックを発行します。変更するプロパティのみをドキュメントに含める必要があります。これは、desired 状態のドキュメントの例です。thingName
/shadow/name/shadowName
/update{ "state": { "desired": { "color": { "r": 10 }, "engine": "ON" } } }
-
更新リクエストが有効な場合、 はシャドウ内の目的の状態 AWS IoT を更新し、以下のトピックに関するメッセージを発行します。
-
$aws/things/
thingName
/shadow/name/shadowName
/update/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/update/delta
/update/accepted
メッセージには /accepted レスポンス状態ドキュメント シャドウドキュメントが含まれ、/update/delta
メッセージには /delta レスポンス状態ドキュメント シャドウドキュメントが含まれます。 -
-
更新リクエストが有効でない場合、 はエラーを説明するシャドウドキュメントを含む エラーレスポンスドキュメント
$aws/things/
トピックを含むメッセージ AWS IoT を発行します。thingName
/shadow/name/shadowName
/update/rejected
クライアントが を使用してシャドウの状態変更をリクエストした場合 API
-
クライアントは、メッセージ本文として リクエスト状態ドキュメント 状態ドキュメント
UpdateThingShadow
APIを使用して を呼び出します。 -
リクエストが有効な場合、 はHTTP成功レスポンスコードと/accepted レスポンス状態ドキュメントシャドウドキュメントをレスポンスメッセージ本文として AWS IoT 返します。
AWS IoT は、サブスクライブしているデバイスまたはクライアントの/delta レスポンス状態ドキュメントシャドウドキュメントを含むMQTTメッセージを
$aws/things/
トピックに発行します。thingName
/shadow/name/shadowName
/update/delta -
リクエストが有効でない場合、 はレスポンスメッセージ本文エラーレスポンスドキュメントとしてHTTPエラーレスポンスコード AWS IoT を返します。
デバイスが /desired
トピックに関する /update/delta
状態を受信すると、デバイス内で必要な変更を行います。次に、/update
トピックにメッセージが送信され、現在の状態がシャドウに報告されます。
デバイスが現在の状態を報告したときにシャドウを更新する
デバイスが MQTTプロトコルを使用して現在の状態をシャドウに報告する場合
-
シャドウを更新する前に、デバイスが次のMQTTトピックをサブスクライブする必要があります。
-
$aws/things/
thingName
/shadow/name/shadowName
/update/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/update/rejected -
$aws/things/
thingName
/shadow/name/shadowName
/update/delta -
$aws/things/
thingName
/shadow/name/shadowName
/update/documents
-
-
デバイスは、この例のように、現在の状態を報告する
$aws/things/
トピックにメッセージを発行することによって、現在の状態を報告します。thingName
/shadow/name/shadowName
/update{ "state": { "reported" : { "color" : { "r" : 10 }, "engine" : "ON" } } }
-
が更新 AWS IoT を受け入れると、シャド/accepted レスポンス状態ドキュメントウドキュメントを含む
$aws/things/
トピックにメッセージを発行します。thingName
/shadow/name/shadowName
/update/accepted -
更新リクエストが有効でない場合、 はエラーを説明するシャドウドキュメントを含む エラーレスポンスドキュメント
$aws/things/
トピックを含むメッセージ AWS IoT を発行します。thingName
/shadow/name/shadowName
/update/rejected
を使用してデバイスが現在の状態をシャドウに報告する場合 API
-
デバイスは、メッセージ本文として リクエスト状態ドキュメント 状態ドキュメント
UpdateThingShadow
APIを使用して を呼び出します。 -
リクエストが有効な場合、 はシャドウ AWS IoT を更新し、レスポンスメッセージ本文として/accepted レスポンス状態ドキュメントシャドウドキュメントを含むHTTP成功レスポンスコードを返します。
AWS IoT は、サブスクライブしているデバイスまたはクライアントの/delta レスポンス状態ドキュメントシャドウドキュメントを含むMQTTメッセージを
$aws/things/
トピックに発行します。thingName
/shadow/name/shadowName
/update/delta -
リクエストが有効でない場合、 はレスポンスメッセージ本文エラーレスポンスドキュメントとしてHTTPエラーレスポンスコード AWS IoT を返します。
オプティミスティックロック
状態ドキュメントのバージョンを使用して、デバイスのシャドウドキュメントの最新バージョンを更新していることを確認できます。更新リクエストでバージョンを指定すると、ステートドキュメントの現在のバージョンが指定されたバージョンと一致しない場合、サービスは HTTP 409 競合レスポンスコードでリクエストを拒否します。競合レスポンスコードはThingShadow
、 を含む API を変更する でも発生する可能性がありますDeleteThingShadow
。
以下に例を示します。
初期ドキュメント:
{
"state": {
"desired": {
"colors": [
"RED",
"GREEN",
"BLUE"
]
}
},
"version": 10
}
更新: (バージョンが一致しないと、リクエストは拒否される)
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 9
}
結果:
{
"code": 409,
"message": "Version conflict",
"clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}
更新: (バージョンが一致すると、リクエストは受け入れられる)
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 10
}
最終状態:
{
"state": {
"desired": {
"colors": [
"BLUE"
]
}
},
"version": 11
}
シャドウキュメントの取得
シャドウドキュメントを取得するには、 を使用するGetThingShadowAPIか、/getトピックをサブスクライブして公開します。これにより、desired
状態と reported
状態の間の delta を含む、完全なシャドウドキュメントが取得されます。このタスクの手順は、デバイスまたはクライアントがリクエストを行っているかどうかにかかわらず同じです。
MQTT プロトコルを使用してシャドウドキュメントを取得するには
-
シャドウを更新する前に、デバイスまたはクライアントがこれらのMQTTトピックをサブスクライブする必要があります。
-
$aws/things/
thingName
/shadow/name/shadowName
/get/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/get/rejected
-
-
デバイスまたはクライアントは、空のメッセージ本文を持つ
$aws/things/
トピックにメッセージを発行します。thingName
/shadow/name/shadowName
/get -
リクエストが成功すると、 はメッセージ本文に を含むメッセージを
$aws/things/
トピック/accepted レスポンス状態ドキュメントに AWS IoT 発行します。thingName
/shadow/name/shadowName
/get/accepted -
リクエストが有効でない場合、 はメッセージ本文に を含むメッセージを
$aws/things/
トピックエラーレスポンスドキュメントに AWS IoT 発行します。thingName
/shadow/name/shadowName
/get/rejected
を使用してシャドウドキュメントを取得するには REST API
-
デバイスまたはクライアントは、空のメッセージ本文
GetThingShadow
APIを使用して を呼び出します。 -
リクエストが有効な場合、 は、レスポンスメッセージ本文として/accepted レスポンス状態ドキュメントシャドウドキュメントを含むHTTP成功レスポンスコード AWS IoT を返します。
-
リクエストが有効でない場合、 はレスポンスメッセージ本文エラーレスポンスドキュメントとしてHTTPエラーレスポンスコード AWS IoT を返します。
シャドウデータの削除
シャドウデータを削除するには、シャドウドキュメント内の特定のプロパティを削除する方法と、シャドウを完全に削除する方法の 2 つがあります。
-
シャドウから特定のプロパティを削除するには、シャドウを更新します。ただし、削除するプロパティの値を
null
に設定します。値がnull
のフィールドは、シャドウドキュメントから削除されます。 -
シャドウ全体を削除するには、 を使用するDeleteThingShadowAPIか、 /deleteトピックに発行します。
注記
シャドウを削除しても、すぐにバージョン番号がゼロにリセットされるわけではありません。48 時間後にゼロにリセットされます。
シャドウドキュメントからのプロパティの削除
MQTT プロトコルを使用してシャドウからプロパティを削除するには
-
デバイスまたはクライアントには、変更するプロパティを識別できるように、現在のシャドウドキュメントが必要です。現在のシャドウドキュメントを取得する方法については、「シャドウキュメントの取得」を参照してください。
-
デバイスまたはクライアントは、次のMQTTトピックをサブスクライブします。
-
$aws/things/
thingName
/shadow/name/shadowName
/update/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/update/rejected
-
-
デバイスまたはクライアントは、削除するシャドウのプロパティに
$aws/things/
値を割り当てる状態ドキュメントを含むthingName
/shadow/name/shadowName
/updatenull
リクエストトピックを発行します。変更するプロパティのみをドキュメントに含める必要があります。これは、engine
プロパティを削除するドキュメントの例です。{ "state": { "desired": { "engine": null } } }
-
更新リクエストが有効な場合、 はシャドウ内の指定されたプロパティ AWS IoT を削除し、メッセージ本文にシャド/accepted レスポンス状態ドキュメントウドキュメントを含む
$aws/things/
トピックを含むメッセージを発行します。thingName
/shadow/name/shadowName
/update/accepted -
更新リクエストが有効でない場合、 はエラーを説明するシャドウドキュメントを含む エラーレスポンスドキュメント
$aws/things/
トピックを含むメッセージ AWS IoT を発行します。thingName
/shadow/name/shadowName
/update/rejected
を使用してシャドウからプロパティを削除するには REST API
-
デバイスまたはクライアントは、削除するシャドウのプロパティに
null
値リクエスト状態ドキュメントを割り当てるUpdateThingShadow
APIを使用して を呼び出します。削除するプロパティのみをドキュメントに含めます。これは、engine
プロパティを削除するドキュメントの例です。{ "state": { "desired": { "engine": null } } }
-
リクエストが有効な場合、 はHTTP成功レスポンスコードと/accepted レスポンス状態ドキュメントシャドウドキュメントをレスポンスメッセージ本文として AWS IoT 返します。
-
リクエストが有効でない場合、 はレスポンスメッセージ本文エラーレスポンスドキュメントとしてHTTPエラーレスポンスコード AWS IoT を返します。
シャドウの削除
デバイスのシャドウを削除に関する考慮事項を次に示します。
-
デバイスのシャドウ状態を
null
に設定しても、シャドウは削除されません。シャドウのバージョンは、次の更新時に増分されます。 -
デバイスのシャドウを削除しても、Thing オブジェクトは削除されません。Thing オブジェクトを削除しても、対応するデバイスのシャドウは削除されません。
-
シャドウを削除しても、すぐにバージョン番号がゼロにリセットされるわけではありません。48 時間後にゼロにリセットされます。
MQTT プロトコルを使用してシャドウを削除するには
-
デバイスまたはクライアントは、次のMQTTトピックをサブスクライブします。
-
$aws/things/
thingName
/shadow/name/shadowName
/delete/accepted -
$aws/things/
thingName
/shadow/name/shadowName
/delete/rejected
-
-
デバイスまたはクライアントは、空のメッセージバッファを持つ
$aws/things/
を発行します。thingName
/shadow/name/shadowName
/delete -
削除リクエストが有効な場合、 はシャドウ AWS IoT を削除し、メッセージ本文に
$aws/things/
トピックと省略されたシャド/accepted レスポンス状態ドキュメントウドキュメントを含むメッセージを発行します。次に、受け入れられた削除メッセージの例を示します。thingName
/shadow/name/shadowName
/delete/accepted{ "version": 4, "timestamp": 1591057529 }
-
更新リクエストが有効でない場合、 はエラーを説明するシャドウドキュメントを含む エラーレスポンスドキュメント
$aws/things/
トピックを含むメッセージ AWS IoT を発行します。thingName
/shadow/name/shadowName
/delete/rejected
を使用してシャドウを削除するには REST API
-
デバイスまたはクライアントは、空のメッセージバッファ
DeleteThingShadow
APIを使用して を呼び出します。 -
リクエストが有効な場合、 はメッセージ本文にHTTP成功レスポンスコードと /accepted レスポンス状態ドキュメントおよび省略された/accepted レスポンス状態ドキュメントシャドウドキュメント AWS IoT を返します。次に、受け入れられた削除メッセージの例を示します。
{ "version": 4, "timestamp": 1591057529 }
-
リクエストが有効でない場合、 はレスポンスメッセージ本文エラーレスポンスドキュメントとしてHTTPエラーレスポンスコード AWS IoT を返します。