すべてのプロダクト
Search
ドキュメントセンター

:デバイスシャドウデータの転送

最終更新日:Feb 06, 2024

デバイスシャドウデータは、トピックを使用して転送されます。 データは、デバイスがステータスをシャドウに送信し、アプリケーションがデバイスのステータスを変更し、デバイスがオンラインになった後にシャドウを要求し、デバイスがシャドウプロパティを削除すると転送されます。 この記事では、デバイスシャドウ固有のトピックとそのデータ形式についても説明します。

デバイスシャドウ固有のトピック

IoT Platformは、シャドウデータを転送する2つのトピックを事前に定義します。

  • /shadow/update/${YourProductKey}/${YourDeviceName}

    各デバイスと各アプリケーションは、このトピックにメッセージを発行します。 メッセージがトピックに送信されると、IoT Platformはメッセージのステータスをデバイスシャドウに同期します。

  • /shadow/get/${YourProductKey}/${YourDeviceName}

    デバイスシャドウの更新されたステータスがこのトピックに送信されます。 各デバイスは、このトピックをサブスクライブして最新のステータスを取得できます。

この記事では、デバイスがステータスをシャドウに送信する方法、アプリケーションがデバイスのステータスを変更する方法、デバイスがシャドウを要求する方法、デバイスがシャドウプロパティを削除する方法について説明します。 この例では、電球デバイスが使用される。

ProductKeya1PbRCF **** で、DeviceNamelightbulbです。 デバイスは、2つのデバイスシャドウ固有のトピックにサブスクライブし、QoS 1メッセージを発行します。

デバイスはステータスを送信します。

デバイスがオンラインの場合、デバイスはステータスをそのシャドウに送信できます。 アプリケーションはシャドウからステータスを取得します。

次の図は、データ転送のプロセスを示しています。

The device submits the status
  1. 電球デバイスがオンラインの場合、デバイスは /shadow/update/a1PbRCF ****/lightbulbトピックを使用して、最新のステータスをシャドウに送信します。
    JSON形式のメッセージ:
    {
      "method": "update", 
      "state": {
        "reported": {
          "color": "red"
        }
      }, 
      "version": 1
    } 
    表1. パラメーター
    パラメーター説明
    メソッドデバイスまたはアプリケーションがデバイスシャドウに送信する要求内の操作のタイプ。

    更新操作では、methodパラメーターが必要で、updateに設定する必要があります。

    stateデバイスがデバイスシャドウに送信するステータス情報。

    reportedパラメーターは必須です。 ステータス情報は、デバイスシャドウの報告されたパラメーターに同期されます。

    バージョンリクエスト内のバージョン情報。 このパラメータはデバイスシャドウによってチェックされます。

    要求で指定された新しいバージョンが現在のバージョンよりも新しい場合にのみ、デバイスシャドウはバージョンを更新します。

    versionパラメーターが -1に設定されている場合、デバイスシャドウのすべてのデータが消去されます。 デバイスシャドウはバージョンを0に更新します。

  2. デバイスシャドウが電球によって送信されたステータスを受信すると、デバイスシャドウはJSONファイルを更新します。
    {
      "state": {
        "reported": {
          "color": "red"
        }
      }, 
      "metadata": {
        "reported": {
          "color": {
            "timestamp": 1469564492
          }
        }
      }, 
      "timestamp": 1469564492、 
      "version": 1
    } 
  3. JSONファイルが更新されると、デバイスシャドウは /shadow/get/a1PbRCF ****/lightbulbトピックを使用して電球に応答を返します。
    • 更新が成功すると、デバイスシャドウは次のメッセージを送信します:
      {
        "method": "reply" 、 
        "payload": {
          "status": "success" 、 
          "version": 1
        }, 
        "timestamp": 1469564576
      } 
    • 更新が失敗した場合、デバイスシャドウは次のメッセージを送信します:
      {
        "method": "reply" 、 
        "payload": {
          "status": "エラー" 、 
          "content": {
            "errorcode": "${errorcode}", 
            "errormessage": "${errormessage}"
          }
        }, 
        "timestamp": 1469564576
      } 
      表2. エラーコード
      エラーコードエラーメッセージ
      400JSON形式が無効です。
      401methodパラメーターが指定されていません。
      402stateパラメーターが指定されていません。
      403versionパラメーターの値は数値ではありません。
      404reportedパラメーターが指定されていません。
      405reportedパラメーターは空です。
      406methodパラメーターの値が無効です。
      407デバイスシャドウは空です。
      408報告されたパラメーターには、128を超えるプロパティが含まれます。
      409バージョンの競合が発生しました。
      500サーバー例外が発生しました。

アプリケーションがデバイスのステータスを変更する

アプリケーションは、UpdateDeviceShadow 操作を呼び出して、必要なステータスをデバイスシャドウに送信します。 次に、IoT Platformはシャドウファイルをデバイスに送信します。 デバイスはシャドウファイルに基づいてステータスを更新し、最新のステータスをデバイスシャドウに送信します。

次の図は、データ転送のプロセスを示しています。

Applications change the device status
  1. アプリケーションは、電球のステータスを変更するためにUpdateDeviceShadow操作を呼び出します。 この例では、colorプロパティの値をgreenに変更する操作が呼び出されます。

    次のコードは、APIリクエストのShadowMessageパラメーターを示しています。

    {
      "method": "update", 
      "state": {
        "desired": {
          "color": "green"
        }
      }, 
      "version": 2
    } 
  2. デバイスシャドウは更新リクエストを受信し、JSONファイルを更新します。
    {
      "state": {
        "reported": {
          "color": "red"
        }, 
        "desired": {
          "color": "green"
        }
      }, 
      "metadata": {
        "reported": {
          "color": {
            "timestamp": 1469564492
          }
        }, 
        "desired": {
          "color": {
            "timestamp": 1469564576
          }
        }
      }, 
      "timestamp": 1469564576、 
      "version": 2
    } 
  3. デバイスシャドウが更新を完了すると、/shadow/get/a1PbRCF ****/lightbulbトピックに応答が返されます。 返される情報は、デバイスシャドウによって決定されます。
    {
      "method": "control" 、 
      "payload": {
        "state": {
          "reported": {
            "color": "red"
          }, 
          "desired": {
            "color": "green"
          }
        }, 
        "metadata": {
          "reported": {
            "color": {
              "timestamp": 1469564492
            }
          }, 
          "desired": {
            "color": {
              "timestamp": 1469564576
            }
          }
        }
      }, 
      "version": 2, 
      "timestamp": 1469564576
    } 
  4. 電球がオンラインで、/shadow/get/a1PbRCF ****/lightbulbのトピックに登録している場合、電球はメッセージを受信できます。

    電球は、メッセージを受信した後、メッセージ内の所望のパラメータの値に基づいてその色を緑色に変更する。

    電球がステータスを更新した後、最新のステータスをIoT Platformに送信します。

    {
      "method": "update", 
      "state": {
        "reported": {
          "color": "green"
        }
      }, 
      "version": 3
    } 
    説明 電球は、タイムスタンプに基づいてコマンドが期限切れになったと判断した場合、更新を実行しません。
  5. 最新のステータスがIoT Platformに送信されると、デバイスとデバイスシャドウは次の操作を実行します。
    • デバイスは、/shadow/update/a1PbRCF ****/lightbulbのトピックにメッセージを送信して、目的のプロパティをクリアします。 次のコードはメッセージを示しています:
      {
        "method": "update", 
        "state": {
          "desired": "null"
        }, 
        "version": 4
      } 
    • デバイスシャドウはJSONファイルを更新します。 次のコードは、更新後のJSONファイルを示しています:
      {
        "state": {
          "reported": {
            "color": "green"
          }
        }, 
        "metadata": {
          "reported": {
            "color": {
              "timestamp": 1469564577
            }
          }, 
          "desired": {
            "timestamp": 1469564576
          }
        }, 
        "version": 4
      } 

デバイスはシャドウを要求します。

アプリケーションがコマンドを送信するとき、デバイスはオフラインであり得る。 デバイスがオンラインになった後、デバイスはシャドウを要求できます。

次の図は、データ転送のプロセスを示しています。

The device requests the shadow
  1. 電球は、/shadow/update/a1PbRCF ****/lightbulbのトピックに次のメッセージを送信して、デバイスシャドウに保存されている最新のステータスを要求します:
    
    "method": "get"
    } 
  2. デバイスシャドウがメッセージを受信すると、デバイスシャドウは最新のステータスを /shadow/get/a1PbRCF ****/lightbulbトピックに送信します。 電球は、トピックを購読することによって最新のステータスを取得します。 次のコードは、デバイスシャドウがデバイスに送信するメッセージを示しています:
    
      "method": "reply" 、 
      "payload": {
        "status": "success" 、 
        "state": {
          "reported": {
            "color": "red"
          }, 
          "desired": {
            "color": "green"
          }
        }, 
        "metadata": {
          "reported": {
            "color": {
              "timestamp": 1469564492
            }
          }, 
          "desired": {
            "color": {
              "timestamp": 1469564492
            }
          }
        }
      }, 
      "version": 2, 
      "timestamp": 1469564576
    } 

デバイスはシャドウプロパティを削除します

デバイスが最新のステータスである場合、デバイスはデバイスシャドウ内のプロパティを削除するコマンドを送信できます。

次の図は、データ転送のプロセスを示しています。

The device deletes shadow properties

デバイスは、/shadow/update/a1PbRCF ****/lightbulbトピックに次のメッセージを送信します。

次のコードでは、methodパラメーターの値はdeleteです。 プロパティの値はnullです。

  • シャドウ内のプロパティを削除します。
    {
      "method": "delete", 
      "state": {
        "reported": {
          "color": "null", 
          "temperature": "null"
        }
      }, 
      "version": 1
    } 
  • シャドウ内のすべてのプロパティを削除します。
    {
      "method": "delete", 
      "state": {
        "reported": "null"
      }, 
      "version": 1
    }