シャドウとの相互作用 - AWS IoT Core
プロトコルサポート状態の要求と報告シャドウの更新シャドウキュメントの取得シャドウデータの削除

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

シャドウとの相互作用

このトピックでは、シャドウを操作するために AWS IoT が提供する 3 つの方法のそれぞれに関連するメッセージについて説明します。これらの方法には、次のものがあります。

UPDATE

存在しない場合はシャドウを作成します。メッセージ本文に指定された状態情報で既存のシャドウの内容を更新します。 AWS IoT は、更新ごとにタイムスタンプを記録して、状態が最後に更新された日時を示します。シャドウの状態が変わるdesiredと、 は と reportedの状態の違いを持つ/deltaメッセージをすべてのMQTTサブスクライバー AWS IoT に送信します。/delta メッセージを受信するデバイスまたはアプリは、違いに基づいてアクションを実行できます。たとえば、デバイスは自らの状態を desired 状態に更新でき、アプリケーションはデバイスの状態の変更を表示するようにその UI を更新できます。

GET

メタデータを含むシャドウの完全な状態を含む現在のシャドウドキュメントを取得します。

DELETE

デバイスシャドウとそのコンテンツを削除します。

削除したデバイスシャドウドキュメントを復元することはできませんが、削除したデバイスシャドウドキュメントの名前で新しいデバイスシャドウを作成することはできます。過去 48 時間以内に削除されたものと同じ名前のデバイスシャドウドキュメントを作成した場合、新しいデバイスシャドウドキュメントのバージョン番号は、削除されたデバイスのシャドウドキュメントのバージョン番号の続きになります。デバイスシャドウドキュメントが 48 時間より前に削除されている場合、同じ名前の新しいデバイスシャドウドキュメントのバージョン番号は 0 になります。

プロトコルサポート

AWS IoT は、shadows とやり取りするための MQTT および RESTAPIを超えるHTTPSプロトコルをサポートしています。 は、アクションMQTTを発行およびサブスクライブするための予約されたリクエストとレスポンスのトピックのセット AWS IoT を提供します。デバイスとアプリケーションは、 がリクエスト AWS IoT を処理した方法に関する情報のリクエストトピックを発行する前に、レスポンストピックをサブスクライブする必要があります。詳細については、「Device Shadow MQTTトピック」および「デバイスシャドウ REST API」を参照してください。

状態の要求と報告

AWS IoT とシャドウを使用して IoT ソリューションを設計する場合は、変更をリクエストするアプリケーションまたはデバイスと、それらを実装するアプリケーションまたはデバイスを決定する必要があります。通常、デバイスは変更をシャドウに実装して報告し、アプリとサービスはシャドウの変更に応答して要求します。ソリューションは異なる場合がありますが、このトピックの例では、クライアントアプリまたはサービスがシャドウの変更を要求し、デバイスがその変更を実行してシャドウに報告することを前提としています。

シャドウの更新

アプリケーションまたはサービスは、 を使用するUpdateThingShadowAPIか、 /updateトピックに発行することで、シャドウの状態を更新できます。更新は、リクエストで指定したフィールドにのみ反映されます。

クライアントが状態の変更を要求したときのシャドウの更新

クライアントがMQTTプロトコルを使用してシャドウの状態変更をリクエストする場合

  1. クライアントには、変更するプロパティを識別できるように、現在のシャドウドキュメントが必要です。現在のシャドウドキュメントを取得する方法については、/get アクションを参照してください。

  2. クライアントは、次の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

  3. クライアントは、シャドウの desired 状態を含む状態ドキュメントを持つ $aws/things/thingName/shadow/name/shadowName/update リクエストトピックを発行します。変更するプロパティのみをドキュメントに含める必要があります。これは、desired 状態のドキュメントの例です。

    {
  "state": {
    "desired": {
      "color": {
        "r": 10
      },
      "engine": "ON"
    }
  }
}

  4. 更新リクエストが有効な場合、 はシャドウ内の目的の状態 AWS IoT を更新し、次のトピックに関するメッセージを公開します。

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    /update/accepted メッセージには /accepted レスポンス状態ドキュメント シャドウドキュメントが含まれ、/update/delta メッセージには /delta レスポンス状態ドキュメント シャドウドキュメントが含まれます。

  5. 更新リクエストが有効でない場合、 は、エラーを説明するエラーレスポンスドキュメントシャドウドキュメントを含む $aws/things/thingName/shadow/name/shadowName/update/rejectedトピックを含むメッセージを AWS IoT 公開します。

クライアントが を使用してシャドウの状態変更をリクエストする場合 API

  1. クライアントは、メッセージ本文としてリクエスト状態ドキュメント状態ドキュメントUpdateThingShadowAPIを使用して を呼び出します。

  2. リクエストが有効な場合、 はHTTP成功レスポンスコードと/accepted レスポンス状態ドキュメントシャドウドキュメントをレスポンスメッセージ本文として AWS IoT 返します。

    AWS IoT は、サブスクライブするデバイスまたはクライアントの/delta レスポンス状態ドキュメントシャドウドキュメントを含むMQTTメッセージを$aws/things/thingName/shadow/name/shadowName/update/deltaトピックに発行します。

  3. リクエストが有効でなかった場合、 はレスポンスメッセージ本文エラーレスポンスドキュメントとして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

  2. デバイスは、この例のように、現在の状態を報告する $aws/things/thingName/shadow/name/shadowName/update トピックにメッセージを発行することによって、現在の状態を報告します。

    {
    "state": {
        "reported" : {
            "color" : { "r" : 10 },
            "engine" : "ON"
        }
    }
}

  3. が更新 AWS IoT を受け入れると、シャ/accepted レスポンス状態ドキュメントドウドキュメントを使用して$aws/things/thingName/shadow/name/shadowName/update/acceptedトピックにメッセージが発行されます。

  4. 更新リクエストが有効でない場合、 は、エラーを説明するエラーレスポンスドキュメントシャドウドキュメントを含む $aws/things/thingName/shadow/name/shadowName/update/rejectedトピックを含むメッセージを AWS IoT 公開します。

を使用してデバイスが現在の状態をシャドウに報告する場合 API

  1. デバイスは、メッセージ本文としてリクエスト状態ドキュメントステートドキュメントUpdateThingShadowAPIを使用して を呼び出します。

  2. リクエストが有効な場合、 はシャドウ AWS IoT を更新し、応答メッセージ本文としてシャ/accepted レスポンス状態ドキュメントドウドキュメントを含むHTTP成功応答コードを返します。

    AWS IoT は、サブスクライブするデバイスまたはクライアントの/delta レスポンス状態ドキュメントシャドウドキュメントを含むMQTTメッセージを$aws/things/thingName/shadow/name/shadowName/update/deltaトピックに発行します。

  3. リクエストが有効でなかった場合、 はレスポンスメッセージ本文エラーレスポンスドキュメントとしてHTTPエラーレスポンスコード AWS IoT を返します。

オプティミスティックロック

状態ドキュメントのバージョンを使用して、デバイスのシャドウドキュメントの最新バージョンを更新していることを確認できます。更新リクエストでバージョンを指定すると、現在のバージョンの状態ドキュメントが指定されたバージョンと一致しない場合、サービスは 409 HTTP の競合レスポンスコードでリクエストを拒否します。競合レスポンスコードは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 プロトコルを使用してシャドウドキュメントを取得するには

  1. デバイスまたはクライアントは、シャドウを更新する前に以下のMQTTトピックをサブスクライブする必要があります。

    • $aws/things/thingName/shadow/name/shadowName/get/accepted

    • $aws/things/thingName/shadow/name/shadowName/get/rejected

  2. デバイスまたはクライアントは、空のメッセージ本文を持つ $aws/things/thingName/shadow/name/shadowName/get トピックにメッセージを発行します。

  3. リクエストが成功すると、 はメッセージ本文/accepted レスポンス状態ドキュメントに を含むメッセージを$aws/things/thingName/shadow/name/shadowName/get/acceptedトピックに AWS IoT 発行します。

  4. リクエストが有効でなかった場合、 はメッセージ本文エラーレスポンスドキュメントに を含むメッセージを$aws/things/thingName/shadow/name/shadowName/get/rejectedトピックに AWS IoT 発行します。

を使用してシャドウドキュメントを取得するには REST API

  1. デバイスまたはクライアントは、空のメッセージ本文GetThingShadowAPIを使用して を呼び出します。

  2. リクエストが有効な場合、 は応答メッセージ本文として/accepted レスポンス状態ドキュメントシャドウドキュメントを含むHTTP成功応答コードを AWS IoT 返します。

  3. リクエストが有効でない場合、 はレスポンスメッセージ本文エラーレスポンスドキュメントとしてHTTPエラーレスポンスコード AWS IoT を返します。

シャドウデータの削除

シャドウデータを削除するには、シャドウドキュメント内の特定のプロパティを削除する方法と、シャドウを完全に削除する方法の 2 つがあります。

  • シャドウから特定のプロパティを削除するには、シャドウを更新します。ただし、削除するプロパティの値を null に設定します。値が null のフィールドは、シャドウドキュメントから削除されます。

  • シャドウ全体を削除するには、 を使用するDeleteThingShadowAPIか、/deleteトピックに公開します。

注記

シャドウを削除しても、バージョン番号は一度にゼロにリセットされません。48 時間後にゼロにリセットされます。

シャドウドキュメントからのプロパティの削除

MQTT プロトコルを使用してシャドウからプロパティを削除するには

  1. デバイスまたはクライアントには、変更するプロパティを識別できるように、現在のシャドウドキュメントが必要です。現在のシャドウドキュメントを取得する方法については、「シャドウキュメントの取得」を参照してください。

  2. デバイスまたはクライアントは、次のMQTTトピックをサブスクライブします。

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

  3. デバイスまたはクライアントは、削除するシャドウのプロパティに $aws/things/thingName/shadow/name/shadowName/update 値を割り当てる状態ドキュメントを含む null リクエストトピックを発行します。変更するプロパティのみをドキュメントに含める必要があります。これは、engine プロパティを削除するドキュメントの例です。

    {
  "state": {
    "desired": {
      "engine": null
    }
  }
}

  4. 更新リクエストが有効な場合、 はシャドウ内の指定されたプロパティ AWS IoT を削除し、メッセージ本文にシャ/accepted レスポンス状態ドキュメントドウドキュメントを含む$aws/things/thingName/shadow/name/shadowName/update/acceptedトピックを含むメッセージを公開します。

  5. 更新リクエストが有効でない場合、 は、エラーを説明するエラーレスポンスドキュメントシャドウドキュメントを含む $aws/things/thingName/shadow/name/shadowName/update/rejectedトピックを含むメッセージを AWS IoT 公開します。

を使用してシャドウからプロパティを削除するには REST API

  1. デバイスまたはクライアントは、削除するシャドウのプロパティにnull値リクエスト状態ドキュメントを割り当てる UpdateThingShadowAPIを使用して を呼び出します。削除するプロパティのみをドキュメントに含めます。これは、engine プロパティを削除するドキュメントの例です。

    {
  "state": {
    "desired": {
      "engine": null
    }
  }
}

  2. リクエストが有効な場合、 はHTTP成功レスポンスコードと/accepted レスポンス状態ドキュメントシャドウドキュメントをレスポンスメッセージ本文として AWS IoT 返します。

  3. リクエストが有効でなかった場合、 はレスポンスメッセージ本文エラーレスポンスドキュメントとして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

  2. デバイスまたはクライアントは、空のメッセージバッファを持つ $aws/things/thingName/shadow/name/shadowName/delete を発行します。

  3. 削除リクエストが有効な場合、 はシャドウ AWS IoT を削除し、メッセージ本文に$aws/things/thingName/shadow/name/shadowName/delete/acceptedトピックと省略された/accepted レスポンス状態ドキュメントシャドウドキュメントを含むメッセージを公開します。次に、受け入れられた削除メッセージの例を示します。

    {
  "version": 4,
  "timestamp": 1591057529
}

  4. 更新リクエストが有効でない場合、 は、エラーを説明するエラーレスポンスドキュメントシャドウドキュメントを含む $aws/things/thingName/shadow/name/shadowName/delete/rejectedトピックを含むメッセージを AWS IoT 公開します。

を使用してシャドウを削除するには REST API

  1. デバイスまたはクライアントは、空のメッセージバッファDeleteThingShadowAPIを使用して を呼び出します。

  2. リクエストが有効な場合、 はメッセージ本文にHTTP成功レスポンスコードと /accepted レスポンス状態ドキュメントと省略された/accepted レスポンス状態ドキュメントシャドウドキュメント AWS IoT を返します。次に、受け入れられた削除メッセージの例を示します。

    {
  "version": 4,
  "timestamp": 1591057529
}

  3. リクエストが有効でなかった場合、 はレスポンスメッセージ本文エラーレスポンスドキュメントとしてHTTPエラーレスポンスコード AWS IoT を返します。