翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# シャドウとの相互作用
このトピックでは、シャドウを操作するために AWS IoT が提供する 3 つの方法のそれぞれに関連するメッセージについて説明します。これらの方法には、次のものがあります。
`UPDATE`
存在しない場合はシャドウを作成します。メッセージ本文に指定された状態情報で既存のシャドウの内容を更新します。 AWS IoT は、更新ごとにタイムスタンプを記録して、状態が最後に更新された日時を示します。シャドウの状態が変更されると、 AWS IoT はすべての MQTT サブスクライバーに 状態`desired`と `reported`状態の違いとともに`/delta`メッセージを送信します。`/delta` メッセージを受信するデバイスまたはアプリは、違いに基づいてアクションを実行できます。たとえば、デバイスは自らの状態を desired 状態に更新でき、アプリケーションはデバイスの状態の変更を表示するようにその UI を更新できます。
`GET`
メタデータを含むシャドウの完全な状態を含む現在のシャドウドキュメントを取得します。
`DELETE`
デバイスシャドウとそのコンテンツを削除します。
削除したデバイスシャドウドキュメントを復元することはできませんが、削除したデバイスシャドウドキュメントの名前で新しいデバイスシャドウを作成することはできます。過去 48 時間以内に削除されたものと同じ名前のデバイスシャドウドキュメントを作成した場合、新しいデバイスシャドウドキュメントのバージョン番号は、削除されたデバイスのシャドウドキュメントのバージョン番号の続きになります。デバイスシャドウドキュメントが 48 時間より前に削除されている場合、同じ名前の新しいデバイスシャドウドキュメントのバージョン番号は 0 になります。
## プロトコルサポート
AWS IoT は[、MQTT](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html) と HTTPS プロトコル経由の REST API をサポートして shadows とやり取りします。 は、MQTT 発行およびサブスクライブアクション用に予約された一連のリクエストおよびレスポンストピック AWS IoT を提供します。デバイスとアプリは、 がリクエスト AWS IoT を処理した方法についての情報をリクエストトピックに発行する前に、レスポンストピックをサブスクライブする必要があります。詳細については、「[Device Shadow MQTT トピック](device-shadow-mqtt.md)」および「[Device Shadow の REST API](device-shadow-rest-api.md)」を参照してください。
## 状態の要求と報告
AWS IoT とシャドウを使用して IoT ソリューションを設計する場合は、変更をリクエストするアプリケーションまたはデバイスと、変更を実装するアプリケーションまたはデバイスを決定する必要があります。通常、デバイスは変更をシャドウに実装して報告し、アプリとサービスはシャドウの変更に応答して要求します。ソリューションは異なる場合がありますが、このトピックの例では、クライアントアプリまたはサービスがシャドウの変更を要求し、デバイスがその変更を実行してシャドウに報告することを前提としています。
## シャドウの更新
アプリまたはサービスは、[UpdateThingShadow](device-shadow-rest-api.md#API_UpdateThingShadow) API を使用するか、[/update](device-shadow-mqtt.md#update-pub-sub-topic) トピックに発行することで、シャドウの状態を更新できます。更新は、リクエストで指定したフィールドにのみ反映されます。
### クライアントが状態の変更を要求したときのシャドウの更新
**クライアントが MQTT プロトコルを使用してシャドウの状態の変更を要求した場合**
1. クライアントには、変更するプロパティを識別できるように、現在のシャドウドキュメントが必要です。現在のシャドウドキュメントを取得する方法については、/get アクションを参照してください。
1. クライアントは、次の 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`
1. クライアントは、シャドウの desired 状態を含む状態ドキュメントを持つ `$aws/things/thingName/shadow/name/shadowName/update` リクエストトピックを発行します。変更するプロパティのみをドキュメントに含める必要があります。これは、desired 状態のドキュメントの例です。
```
{
"state": {
"desired": {
"color": {
"r": 10
},
"engine": "ON"
}
}
}
```
1. 更新リクエストが有効な場合、 はシャドウ内の目的の状態 AWS IoT を更新し、これらのトピックに関するメッセージを発行します。
+ `$aws/things/thingName/shadow/name/shadowName/update/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/update/delta`
`/update/accepted` メッセージには [/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted) シャドウドキュメントが含まれ、`/update/delta` メッセージには [/delta レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-delta) シャドウドキュメントが含まれます。
1. 更新リクエストが有効でない場合、 はエラーを説明する[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)シャドウドキュメントを含む `$aws/things/thingName/shadow/name/shadowName/update/rejected`トピックを含むメッセージ AWS IoT を発行します。
**クライアントが API を使用してシャドウの状態の変更を要求した場合**
1. クライアントは、`UpdateThingShadow` API と [リクエスト状態ドキュメント](device-shadow-document.md#device-shadow-example-request-json) 状態ドキュメントをメッセージ本文として使用します。
1. リクエストが有効な場合、 は HTTP 成功レスポンスコードと[/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted)シャドウドキュメントをレスポンスメッセージ本文として AWS IoT 返します。
AWS IoT は、サブスクライブするデバイスまたはクライアントの[/delta レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-delta)シャドウドキュメントを含む MQTT メッセージも`$aws/things/thingName/shadow/name/shadowName/update/delta`トピックに発行します。
1. リクエストが有効でない場合、 はレスポンスメッセージ本文[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)として HTTP エラーレスポンスコード AWS IoT を返します。
デバイスが `/desired` トピックに関する `/update/delta` 状態を受信すると、デバイス内で必要な変更を行います。次に、`/update` トピックにメッセージが送信され、現在の状態がシャドウに報告されます。
### デバイスが現在の状態を報告したときにシャドウを更新する
**デバイスが MQTT プロトコルを使用して現在の状態をシャドウに報告する場合**
1. デバイスは、シャドウを更新する前に、次の 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`
1. デバイスは、この例のように、現在の状態を報告する `$aws/things/thingName/shadow/name/shadowName/update` トピックにメッセージを発行することによって、現在の状態を報告します。
```
{
"state": {
"reported" : {
"color" : { "r" : 10 },
"engine" : "ON"
}
}
}
```
1. が更新 AWS IoT を受け入れると、シャ[/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted)ドウドキュメントを使用して`$aws/things/thingName/shadow/name/shadowName/update/accepted`トピックにメッセージを発行します。
1. 更新リクエストが有効でない場合、 はエラーを説明する[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)シャドウドキュメントを含む `$aws/things/thingName/shadow/name/shadowName/update/rejected`トピックを含むメッセージ AWS IoT を発行します。
**デバイスが API を使用して現在の状態をシャドウに報告する場合**
1. デバイスは、[リクエスト状態ドキュメント](device-shadow-document.md#device-shadow-example-request-json) 状態ドキュメントをメッセージ本文として使用して `UpdateThingShadow` API を呼び出します。
1. リクエストが有効な場合、 はシャドウ AWS IoT を更新し、レスポンスメッセージ本文としてシャドウドキュメントを含む HTTP [/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted) 成功レスポンスコードを返します。
AWS IoT は、サブスクライブするデバイスまたはクライアントの[/delta レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-delta)シャドウドキュメントを含む MQTT メッセージも`$aws/things/thingName/shadow/name/shadowName/update/delta`トピックに発行します。
1. リクエストが有効でない場合、 はレスポンスメッセージ本文[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)として HTTP エラーレスポンスコード AWS IoT を返します。
### オプティミスティックロック
状態ドキュメントのバージョンを使用して、デバイスのシャドウドキュメントの最新バージョンを更新していることを確認できます。更新リクエストでバージョンを渡したとき、そのバージョンと状態ドキュメントの現在のバージョンとが一致しない場合、サービスは HTTP 409 conflict レスポンスコードでリクエストを拒否します。競合レスポンスコードは、`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
}
```
## シャドウキュメントの取得
シャドウドキュメントは、[GetThingShadow](device-shadow-rest-api.md#API_GetThingShadow) API を使用するか、[/get](device-shadow-mqtt.md#get-pub-sub-topic) トピックをサブスクライブして発行することによって取得できます。これにより、`desired` 状態と `reported` 状態の間の delta を含む、完全なシャドウドキュメントが取得されます。このタスクの手順は、デバイスまたはクライアントがリクエストを行っているかどうかにかかわらず同じです。
**MQTT プロトコルを使用してシャドウドキュメントを取得するには**
1. デバイスまたはクライアントは、シャドウを更新する前に、次の MQTT トピックにサブスクライブする必要があります。
+ `$aws/things/thingName/shadow/name/shadowName/get/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/get/rejected`
1. デバイスまたはクライアントは、空のメッセージ本文を持つ `$aws/things/thingName/shadow/name/shadowName/get` トピックにメッセージを発行します。
1. リクエストが成功すると、 はメッセージ本文[/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted)に を含むメッセージを`$aws/things/thingName/shadow/name/shadowName/get/accepted`トピックに AWS IoT 発行します。
1. リクエストが有効でなかった場合、 はメッセージ本文に を含むメッセージを`$aws/things/thingName/shadow/name/shadowName/get/rejected`トピックに AWS IoT 発行[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)します。
**REST API を使用してシャドウドキュメントを取得するには**
1. デバイスまたはクライアントは、空のメッセージ本文で `GetThingShadow` API を呼び出します。
1. リクエストが有効な場合、 はレスポンスメッセージ本文としてシャドウドキュメントを含む HTTP [/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted) 成功レスポンスコード AWS IoT を返します。
1. リクエストが有効でない場合、 はレスポンスメッセージ本文[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)として HTTP エラーレスポンスコード AWS IoT を返します。
## シャドウデータの削除
シャドウデータを削除するには、シャドウドキュメント内の特定のプロパティを削除する方法と、シャドウを完全に削除する方法の 2 つがあります。
+ シャドウから特定のプロパティを削除するには、シャドウを更新します。ただし、削除するプロパティの値を `null` に設定します。値が `null` のフィールドは、シャドウドキュメントから削除されます。
+ シャドウ全体を削除するには、[DeleteThingShadow](device-shadow-rest-api.md#API_DeleteThingShadow) API を使用するか、[/delete](device-shadow-mqtt.md#delete-pub-sub-topic) トピックに発行します。
**注記**
シャドウを削除しても、すぐにバージョン番号がゼロにリセットされるわけではありません。48 時間後にゼロにリセットされます。
### シャドウドキュメントからのプロパティの削除
**MQTT プロトコルを使用してシャドウからプロパティを削除するには**
1. デバイスまたはクライアントには、変更するプロパティを識別できるように、現在のシャドウドキュメントが必要です。現在のシャドウドキュメントを取得する方法については、「[シャドウキュメントの取得](#retrieving-device-shadow)」を参照してください。
1. デバイスまたはクライアントは、次の MQTT トピックにサブスクライブします。
+ `$aws/things/thingName/shadow/name/shadowName/update/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/update/rejected`
1. デバイスまたはクライアントは、削除するシャドウのプロパティに `$aws/things/thingName/shadow/name/shadowName/update` 値を割り当てる状態ドキュメントを含む `null` リクエストトピックを発行します。変更するプロパティのみをドキュメントに含める必要があります。これは、`engine` プロパティを削除するドキュメントの例です。
```
{
"state": {
"desired": {
"engine": null
}
}
}
```
1. 更新リクエストが有効な場合、 はシャドウ内の指定されたプロパティ AWS IoT を削除し、メッセージ本文にシャド[/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted)ウドキュメントを含む `$aws/things/thingName/shadow/name/shadowName/update/accepted`トピックを含むメッセージを発行します。
1. 更新リクエストが有効でない場合、 はエラーを説明する[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)シャドウドキュメントを含む `$aws/things/thingName/shadow/name/shadowName/update/rejected`トピックを含むメッセージ AWS IoT を発行します。
**REST API を使用してシャドウからプロパティを削除するには**
1. デバイスまたはクライアントは、削除するシャドウのプロパティに `null` 値を割り当てる [リクエスト状態ドキュメント](device-shadow-document.md#device-shadow-example-request-json) を使用して `UpdateThingShadow` API を呼び出します。削除するプロパティのみをドキュメントに含めます。これは、`engine` プロパティを削除するドキュメントの例です。
```
{
"state": {
"desired": {
"engine": null
}
}
}
```
1. リクエストが有効な場合、 は HTTP 成功レスポンスコードと[/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted)シャドウドキュメントをレスポンスメッセージ本文として AWS IoT 返します。
1. リクエストが有効でない場合、 はレスポンスメッセージ本文[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)として HTTP エラーレスポンスコード AWS IoT を返します。
### シャドウの削除
デバイスのシャドウを削除に関する考慮事項を次に示します。
+ デバイスのシャドウ状態を `null` に設定しても、シャドウは削除されません。シャドウのバージョンは、次の更新時に増分されます。
+ デバイスのシャドウを削除しても、Thing オブジェクトは削除されません。Thing オブジェクトを削除しても、対応するデバイスのシャドウは削除されません。
+ シャドウを削除しても、すぐにバージョン番号がゼロにリセットされるわけではありません。48 時間後にゼロにリセットされます。
**MQTT プロトコルを使用してシャドウを削除するには**
1. デバイスまたはクライアントは、次の MQTT トピックにサブスクライブします。
+ `$aws/things/thingName/shadow/name/shadowName/delete/accepted`
+ `$aws/things/thingName/shadow/name/shadowName/delete/rejected`
1. デバイスまたはクライアントは、空のメッセージバッファを持つ `$aws/things/thingName/shadow/name/shadowName/delete` を発行します。
1. 削除リクエストが有効な場合、 はシャドウ AWS IoT を削除し、メッセージ本文に `$aws/things/thingName/shadow/name/shadowName/delete/accepted`トピックと省略されたシャド[/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted)ウドキュメントを含むメッセージを発行します。次に、受け入れられた削除メッセージの例を示します。
```
{
"version": 4,
"timestamp": 1591057529
}
```
1. 更新リクエストが有効でない場合、 はエラーを説明する[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)シャドウドキュメントを含む `$aws/things/thingName/shadow/name/shadowName/delete/rejected`トピックを含むメッセージ AWS IoT を発行します。
**REST API を使用してシャドウを削除するには**
1. デバイスまたはクライアントは、空のメッセージバッファを使用して `DeleteThingShadow` API を呼び出します。
1. リクエストが有効な場合、 はメッセージ本文に HTTP 成功レスポンスコードと [/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted) [/accepted レスポンス状態ドキュメント](device-shadow-document.md#device-shadow-example-response-json-accepted)と省略されたシャドウドキュメント AWS IoT を返します。次に、受け入れられた削除メッセージの例を示します。
```
{
"version": 4,
"timestamp": 1591057529
}
```
1. リクエストが有効でない場合、 はレスポンスメッセージ本文[エラーレスポンスドキュメント](device-shadow-document.md#device-shadow-example-error-json)として HTTP エラーレスポンスコード AWS IoT を返します。