デバイスシャドウデータの転送 - - Alibaba Cloud ドキュメントセンター

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

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

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

/shadow/update/${YourProductKey}/${YourDeviceName}
各デバイスと各アプリケーションは、このトピックにメッセージを発行します。メッセージがトピックに送信されると、IoT Platformはメッセージのステータスをデバイスシャドウに同期します。
/shadow/get/${YourProductKey}/${YourDeviceName}
デバイスシャドウの更新されたステータスがこのトピックに送信されます。各デバイスは、このトピックをサブスクライブして最新のステータスを取得できます。

例

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

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

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

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

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

電球デバイスがオンラインの場合、デバイスは /shadow/update/a1PbRCF ****/lightbulbトピックを使用して、最新のステータスをシャドウに送信します。

JSON形式のメッセージ:

{
  "method": "update", 
  "state": {
    "reported": {
      "color": "red"
    }
  }, 
  "version": 1
}

表1. パラメーター
パラメーター	説明
メソッド	デバイスまたはアプリケーションがデバイスシャドウに送信する要求内の操作のタイプ。更新操作では、methodパラメーターが必要で、updateに設定する必要があります。
state	デバイスがデバイスシャドウに送信するステータス情報。 reportedパラメーターは必須です。ステータス情報は、デバイスシャドウの報告されたパラメーターに同期されます。
バージョン	リクエスト内のバージョン情報。このパラメータはデバイスシャドウによってチェックされます。要求で指定された新しいバージョンが現在のバージョンよりも新しい場合にのみ、デバイスシャドウはバージョンを更新します。 versionパラメーターが `-1`に設定されている場合、デバイスシャドウのすべてのデータが消去されます。デバイスシャドウはバージョンを`0`に更新します。

デバイスシャドウが電球によって送信されたステータスを受信すると、デバイスシャドウはJSONファイルを更新します。

{
  "state": {
    "reported": {
      "color": "red"
    }
  }, 
  "metadata": {
    "reported": {
      "color": {
        "timestamp": 1469564492
      }
    }
  }, 
  "timestamp": 1469564492、 
  "version": 1
}

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. エラーコード
エラーコード	エラーメッセージ
400	JSON形式が無効です。
401	methodパラメーターが指定されていません。
402	stateパラメーターが指定されていません。
403	versionパラメーターの値は数値ではありません。
404	reportedパラメーターが指定されていません。
405	reportedパラメーターは空です。
406	methodパラメーターの値が無効です。
407	デバイスシャドウは空です。
408	報告されたパラメーターには、128を超えるプロパティが含まれます。
409	バージョンの競合が発生しました。
500	サーバー例外が発生しました。

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

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

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

アプリケーションは、電球のステータスを変更するためにUpdateDeviceShadow操作を呼び出します。この例では、colorプロパティの値をgreenに変更する操作が呼び出されます。
次のコードは、APIリクエストのShadowMessageパラメーターを示しています。
```
{
  "method": "update", 
  "state": {
    "desired": {
      "color": "green"
    }
  }, 
  "version": 2
} 
```

デバイスシャドウは更新リクエストを受信し、JSONファイルを更新します。

{
  "state": {
    "reported": {
      "color": "red"
    }, 
    "desired": {
      "color": "green"
    }
  }, 
  "metadata": {
    "reported": {
      "color": {
        "timestamp": 1469564492
      }
    }, 
    "desired": {
      "color": {
        "timestamp": 1469564576
      }
    }
  }, 
  "timestamp": 1469564576、 
  "version": 2
}

デバイスシャドウが更新を完了すると、/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
}

電球がオンラインで、/shadow/get/a1PbRCF ****/lightbulbのトピックに登録している場合、電球はメッセージを受信できます。
電球は、メッセージを受信した後、メッセージ内の所望のパラメータの値に基づいてその色を緑色に変更する。
電球がステータスを更新した後、最新のステータスをIoT Platformに送信します。
```
{
  "method": "update", 
  "state": {
    "reported": {
      "color": "green"
    }
  }, 
  "version": 3
} 
```
説明電球は、タイムスタンプに基づいてコマンドが期限切れになったと判断した場合、更新を実行しません。
最新のステータスが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
} 
```

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

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

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

電球は、/shadow/update/a1PbRCF ****/lightbulbのトピックに次のメッセージを送信して、デバイスシャドウに保存されている最新のステータスを要求します:
```
"method": "get"
} 
```

デバイスシャドウがメッセージを受信すると、デバイスシャドウは最新のステータスを /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
}

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

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

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

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

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

シャドウ内のプロパティを削除します。

{
  "method": "delete", 
  "state": {
    "reported": {
      "color": "null", 
      "temperature": "null"
    }
  }, 
  "version": 1
}

シャドウ内のすべてのプロパティを削除します。

{
  "method": "delete", 
  "state": {
    "reported": "null"
  }, 
  "version": 1
}