すべてのプロダクト
Search

このプロダクト

    IoT Platform:デバイスシャドウのデータストリーム

    ドキュメントセンター

    IoT Platform:デバイスシャドウのデータストリーム

    最終更新日:Jun 11, 2026

    デバイスシャドウのデータは、事前定義された MQTT トピックを介して流れます。このデータフローは、デバイスが現在のステータスを報告する、アプリケーションがデバイスに望ましい状態を送信する、デバイスがオンラインに復帰した後にシャドウのコンテンツを取得する、デバイスがシャドウプロパティを削除するという 4 つのシナリオをカバーします。

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

    IoT Platform は、デバイスシャドウのデータフローを処理するために、デバイスごとに 2 つのトピックを事前定義しています。

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

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

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

      デバイスシャドウは、このトピックにステータスの更新をパブリッシュします。デバイスは、このトピックをサブスクライブして最新のメッセージを受信します。

    使用例

    以下の例では、電球を使用して、デバイス、そのデバイスシャドウ、およびアプリケーションがどのように相互作用するかを説明します。これらの例は、ステータスの報告、アプリケーションからのデバイスステータスの変更、再接続時のシャドウのコンテンツの取得、シャドウプロパティの削除という 4 つすべてのデータフローシナリオをカバーしています。

    例では、ProductKey は a1PbRCF**** で、DeviceName は lightbulb です。デバイスは、サービス品質 (QoS) 1 で両方のデバイスシャドウのトピックにパブリッシュおよびサブスクライブします。

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

    デバイスがオンラインになると、現在のステータスをデバイスシャドウに報告します。その後、アプリケーションはいつでもシャドウからデバイスのステータスを読み取ることができます。

    次の図はデータフローを示しています。

    Device reports status

    1. 電球がオンラインになり、現在のステータスを /shadow/update/a1PbRCF****/lightbulb トピックにパブリッシュします。

      JSON メッセージの形式は次のとおりです：

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

      表 1. パラメーターの説明

      パラメーター

      説明

      method

      操作タイプ。更新を実行する場合、メソッドは必須です。update に設定します。

      state

      デバイスシャドウに送信されるステータスデータ。reported は必須です。値はシャドードキュメントの reported セクションに書き込まれます。

      version

      リクエストのバージョン。デバイスシャドウは、新しいバージョンが現在のバージョンより大きい場合にのみ更新を受け入れます。バージョンが -1 に設定されている場合、すべてのシャドウデータがクリアされ、バージョンは 0 にリセットされます。

    2. デバイスシャドウは、報告されたステータスでシャドードキュメントを更新します。

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

    3. シャドードキュメントを更新した後、デバイスシャドウは /shadow/get/a1PbRCF****/lightbulb トピックに結果を送信します。結果を確実に受信するために、更新トピックにパブリッシュする前にこのトピックをサブスクライブしてください。

      • 更新が成功した場合：

        {
    "method": "reply", 
    "payload": {
        "status": "success", 
        "version": 1
    }, 
    "timestamp": 1469564576
}

      • 更新が失敗した場合：

        {
    "method": "reply", 
    "payload": {
        "status": "error", 
        "content": {
            "errorcode": "${errorcode}", 
            "errormessage": "${errormessage}"
        }
    }, 
    "timestamp": 1469564576
}

        表 2. エラーコード

        errorCode

        errorMessage

        400

        無効な JSON 形式です。

        401

        シャドウデータに method フィールドがありません。

        402

        シャドウデータに state フィールドがありません。

        403

        version フィールドの値が数値ではありません。

        404

        シャドウデータに reported フィールドがありません。

        405

        reported フィールドが空です。

        406

        method の値が無効です。

        407

        シャドウのコンテンツが空です。

        408

        reported フィールドのプロパティ数が 128 を超えています。

        409

        バージョンの競合です。

        500

        サーバー側の処理エラーです。

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

    アプリケーションは UpdateDeviceShadow API を呼び出して、望ましい状態をデバイスシャドウに書き込みます。シャドウは望ましい状態をデバイスにプッシュし、デバイスは変更を適用して更新されたステータスを報告します。

    次の図はデータフローを示しています。

    Application changes device status

    1. アプリケーションは UpdateDeviceShadow API を呼び出して、color プロパティを green に設定します。

      ShadowMessage パラメーターの値は次のとおりです：

      {
    "method": "update", 
    "state": {
        "desired": {
            "color": "green"
        }
    }, 
    "version": 2
}

    2. デバイスシャドウは更新を受け取り、望ましい状態をシャドードキュメントに書き込みます。

      {
    "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 に設定されており、これによりデバイスに要求された変更を適用するよう通知されます。

      {
    "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 トピックをサブスクライブしている場合、メッセージをすぐに受信します。

      デバイスは desired フィールドを読み取り、電球の色を緑に変更します。

      ステータスを更新した後、電球は最新のステータスを IoT Platform に報告します。

      {
    "method": "update", 
    "state": {
        "reported": {
            "color": "green"
        }
    }, 
    "version": 3
}
      説明

      タイムスタンプを使用してコマンドの有効期限が切れていると判断した場合、更新を実行しないことを選択できます。

    5. デバイスシャドウは、/shadow/get/a1PbRCF****/lightbulb トピックを介してデバイスに応答を送信します。応答形式については、「デバイスによるステータス報告」のステップ 3 をご参照ください。

    6. ステータスが正常に報告された後、デバイスとデバイスシャドウは望ましい状態をクリーンアップします。

      • デバイスは /shadow/update/a1PbRCF****/lightbulb トピックにメッセージをパブリッシュして、desired フィールドをクリアします。

        {
    "method": "update", 
    "state": {
        "desired": "null"
    }, 
    "version": 4
}

      • デバイスシャドウによってドキュメントが更新されます。 desired フィールドはクリアされ、シャドウ ドキュメントには最終状態が反映されます。

        {
    "state": {
        "reported": {
            "color": "green"
        }
    }, 
    "metadata": {
        "reported": {
            "color": {
                "timestamp": 1469564577
            }
        }, 
        "desired": {
            "timestamp": 1469564576
        }
    }, 
    "version": 4
}

    デバイスによるシャドウのコンテンツの取得

    アプリケーションがコマンドを送信したときにデバイスがオフラインだった場合、再接続後にシャドウのコンテンツを取得できます。

    次の図はデータフローを示しています。

    Device retrieves shadow content

    1. 再接続後、電球は /shadow/update/a1PbRCF****/lightbulb トピックに get リクエストをパブリッシュして、最新のシャドウコンテンツを取得します。

      {
    "method": "get"
}

    2. デバイスシャドウは、最新のシャドウコンテンツを /shadow/get/a1PbRCF****/lightbulb トピックにパブリッシュして応答します。レスポンスを確実に受信できるように、get リクエストを送信する前にこのトピックをサブスクライブします。

      {
    "method": "reply", 
    "payload": {
        "status": "success", 
        "state": {
            "reported": {
                "color": "red"
            }, 
            "desired": {
                "color": "green"
            }
        }, 
        "metadata": {
            "reported": {
                "color": {
                    "timestamp": 1469564492
                }
            }, 
            "desired": {
                "color": {
                    "timestamp": 1469564576
                }
            }
        }
    }, 
    "version": 2, 
    "timestamp": 1469564576
}

    デバイスによるシャドウプロパティの削除

    デバイスがすでに最新のステータスを持っている場合、デバイスシャドウから特定のプロパティを削除できます。

    次の図はデータフローを示しています。

    Device deletes shadow properties

    シャドウプロパティを削除するには、メソッドを delete に、ターゲットプロパティの値を null に設定して、/shadow/update/a1PbRCF****/lightbulb トピックにパブリッシュします。

    • シャドウから特定のプロパティを削除します。

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

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

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