IoT Platform は、データ伝送を可能にするために、各デバイスに対して 2 つのトピックをあらかじめ定義しています。 定義済みトピックの形式は固定です。
  • トピック: /shadow/update/${YourProductKey}/${YourDeviceName}

    デバイスとアプリケーションは、このトピックにメッセージをパブリッシュします。 IoT Platform がこのトピックからメッセージを受信すると、メッセージ内のステータス情報を抽出し、デバイスシャドウのステータスを更新します。

  • トピック: /shadow/get/${YourProductKey}/${YourDeviceName}

    デバイスシャドウはこのトピックのステータスを更新し、デバイスはこのトピックからのメッセージをサブスクライブします。

例として、プロダクト bulb_1 の lightbulb デバイスを取り上げて、デバイス、デバイスシャドウ、およびアプリケーション間の通信を説明します。 次の例では、ProductKey は 10000、DeviceName は lightbulb です。 デバイスは、QoS 1 の方法を使用して、メッセージをパブリッシュし、2 つのカスタムトピックのメッセージをサブスクライブします。

デバイスによるステータスの自動報告

フローチャートを「図 1」に示します。

図 1. デバイスによるステータスの自動報告


  1. lightbulb がオンラインのとき、デバイスはトピック /shadow/update/10000/lightbulb を使用して、最新のステータスをデバイスシャドウに報告します。
    JSON メッセージの形式:
    
    {
    "method": "update",
    "state": {
    "reported": {
    "color": "red"
    }
    },
    "version": 1
    }

    JSON パラメーターを「表 1 」で説明します。

    表 1. パラメーターの説明
    パラメーター 説明
    method デバイスまたはアプリケーションがデバイスシャドウをリクエストしたときの操作タイプ。

    ステータスを更新する場合、このパラメーター method は必須で、update に設定する必要があります。

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

    reported フィールドは必須です。 ステータス情報は、デバイスシャドウの reported フィールドと同期しています。

    version リクエストに含まれているバージョン情報。

    新バージョンが現在のバージョンより新しい場合、デバイスシャドウはリクエストを受け入れて、指定されたバージョンに更新します。

  2. デバイスシャドウがデバイス lightbulb によって報告されたステータスを受け入れると、デバイスシャドウの JSON ファイルは正常に更新されます。
    
    {
    "state" : {
    "reported" : {
    "color" : "red"
    }
    },
    "metadata" : {
    "reported" : {
    "color" : {
    "timestamp" : 1469564492
    }
    }
    },
    "timestamp" : 1469564492
    "version" : 1
    }
  3. デバイスシャドウが更新されると、トピック /shadow/get/10000/lightbulb にメッセージを送信して、結果をデバイス (lightbulb) に返します。
    • 更新が成功すると、メッセージは次のようになります。
      
      {
      "method":"reply",
      "payload": {
      "status":"success",
      "version": 1
      },
      "timestamp": 1469564576
      }
    • 更新中にエラーが発生した場合、メッセージは次のようになります。
      
      {
      "method":"reply",
      "payload": {
      "status":"error",
      "content": {
      "errorcode": "${errorcode}",
      "errormessage": "${errormessage}"
      }
      },
      "timestamp": 1469564576
      }

    エラーコードを「表 2」で説明します。

    表 2. エラーコード
    errorCode errorMessage
    400 JSON ファイルが正しくありません。
    401 method フィールドが見つかりません。
    402 state フィールドが見つかりません。
    403 無効な version フィールドです。
    404 reported フィールドが見つかりません。
    405 reported フィールドは空です。
    406 method フィールドが無効です。
    407 JSON ファイルが空です。
    408 reported フィールドには、128 を超える属性が含まれています。
    409 バージョンが競合しています。
    500 サーバー例外です。

アプリケーションによるデバイスステータスの変更

フローチャートを「図 2」に示します。

図 2. アプリケーションによるデバイスステータスの変更


  1. アプリケーションは lightbulb のステータスを変更するために、デバイスシャドウにコマンドを送信します。
    アプリケーションはトピック /shadow/update/10000/lightbulb/ にメッセージを送信します。 メッセージは次のとおりです:
    
    {
    "method": "update",
    "state": {
    "desired": {
    "color": "green"
    }
    },
    "version": 2
    }
  2. アプリケーションは、デバイスシャドウ JSON ファイルを更新するための更新リクエストを送信します。 デバイスシャドウ JSON ファイルは次のように変更されます。
    
    {
    "state" : {
    "reported" : {
    "color" : "red"
    },
    "desired" : {
    "color" : "green"
    }
    },
    "metadata" : {
    "reported" : {
    "color" : {
    "timestamp" : 1469564492
    }
    },
    "desired" : {
    "color" : {
    "timestamp" : 1469564576
    }
    }
    },
    "timestamp" : 1469564576,
    "version" : 2
    }
  3. 更新後、デバイスシャドウはトピック /shadow/get/10000/lightbulb にメッセージを送信し、更新の結果をデバイスに返します。 結果メッセージは、デバイスシャドウによって作成されます。
    
    {
    "method":"control",
    "payload": {
    "status":"success",
    "state": {
    "reported": {
    "color": "red"
    },
    "desired": {
    "color": "green"
    }
    },
    "metadata": {
    "reported": {
    "color": {
    "timestamp": 1469564492
    }
    },
    "desired" : {
    "color" : {
    "timestamp" : 1469564576
    }
    }
    }
    },
    "version": 2,
    "timestamp": 1469564576
    }
  4. デバイス lightbulb がオンラインで、トピック /shadow/get/10000/lightbulb をサブスクライブしている場合、デバイスはメッセージを受信し、リクエストファイルの desired フィールドに従ってその色を緑色に変更します。 デバイスはステータスを更新した後、クラウドに最新のステータスを報告します。
    {
    method": "update", 
    "state": { 
    "reported": { 
    "color": "green" 
    } 
    }, 
    "version": 3 
    }

    コマンドが期限切れであることをタイムスタンプが示している場合は、更新しません。

  5. 最新のステータスが正常に報告された後、デバイスクライアントはトピック /shadow/update/10000/lightbulb にメッセージを送信して、desired フィールドのプロパティを空にします。 メッセージは次のとおりです。
    
    {
    "method": "update",
    "state": {
    "desired":"null"
    },
    "version": 4
    }
  6. ステータスが報告された後、デバイスシャドウは同期して更新されます。 デバイスシャドウ JSON ファイルは次のとおりです:
    
    {
    "state" : {
    "reported" : {
    "color" : "green"
    }
    },
    "metadata" : {
    "reported" : {
    "color" : {
    "timestamp" : 1469564577
    }
    },
    "desired" : {
    "timestamp" : 1469564576
    }
    },
    "version" : 4
    }

デバイスからデバイスシャドウに対するリクエスト

フローチャートを「図 3」に示します。

図 3. デバイスからデバイスシャドウに対するリクエスト


  1. デバイス lightbulb は、トピック /shadow/update/10000/lightbulb にメッセージを送信して、デバイスシャドウに保存されている最新のステータスを取得します。 メッセージは次のとおりです。
    
    {
    "method": "get"
    }
  2. デバイスシャドウが上記のメッセージを受信すると、トピック/shadow/get/10000/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
    }

デバイスによるデバイスシャドウ属性の削除

フローチャートを「図 4」に示します。
図 4. デバイスシャドウ属性の削除


デバイス lightbulb は、デバイスシャドウに保存されている、指定された属性を削除します。 デバイスは JSON メッセージをトピック /shadow/update/10000/lightbulb に送信します。 次の例のメッセージをご参照ください。

属性を削除するには、method の値を delete に設定し、属性の値を null に設定します。

  • 属性を 1 つ削除します。
    
    {
    "method": "delete",
    "state": {
    "reported": {
    "color": "null",
    "temperature":"null"
    }
    },
    "version": 1
    }
  • 属性をすべて削除します。
    
    {
    "method": "delete",
    "state": {
    "reported":"null"
    },
    "version": 1
    }