デバイスと DPS の間でペイロードを転送する方法

  • [アーティクル]

DPS に登録するデバイスは、登録時に登録 ID と有効な資格情報 (キーまたは X.509 証明書) を指定する必要があります。 ただし、IoT ソリューションや、デバイスから追加のデータが必要になるシナリオがある場合があります。 たとえば、カスタム割り当てポリシー Webhook では、デバイス モデル番号などの情報を使用して、デバイスをプロビジョニングする IoT ハブを選択できます。 同様に、デバイスでは、クライアント側のロジックを容易にするため、登録応答に追加のデータが必要になる場合があります。 DPS は、デバイスが登録するときにオプションのペイロードを送受信する機能を提供します。

いつ使用するか

オプションのペイロードを送信する一般的なシナリオは次のとおりです。

  • カスタム割り当てポリシーでは、デバイス ペイロードを使用して、デバイスの IoT ハブを選択したり、初期ツインを設定したりできます。 たとえば、デバイス モデルに基づいてデバイス名を割り当てる必要があります。 この場合、登録した際にモデル情報を報告するようにデバイスを構成できます。 デバイスのペイロードが DPS からカスタム割り当て Webhook に渡されます。 次に、デバイスのモデル情報に基づきデバイスがプロビジョニングされる IoT Hub を Webhook 関数によって判別できます。 必要に応じて、Webhook でも Webhook 応答内の JSON オブジェクトとしてデータをデバイスに返すことができます。 詳細については、「カスタム割り当てでデバイス ペイロードを使用する」を参照してください。

  • IoT プラグ アンド プレイ (PnP) デバイスは、DPS に登録するときに、ペイロードを使用してモデル ID を送信できます。 この使用例については、SDK の PnP サンプルまたはサンプル リポジトリを参照してください。 たとえば、C# の pnp サーモスタットや Node.js の PnP 温度コントローラーなどです。

  • DPS を介して接続する IoT Central デバイスは、IoT プラグ アンド プレイ規則に従い、登録時にモデル ID を送信する必要があります。 IoT Central は、モデル ID を使用してデバイスを正しいデバイス テンプレートに割り当てることができます。 しょうさいについては、「IoT Central に関するデバイスの実装とベスト プラクティス」を参照してください。

デバイスから DPS にデータ ペイロードを送信する

デバイスがデバイスの 登録 を呼び出して DPS に登録する場合、 ペイロード プロパティに追加のデータを含めることができます。 たとえば、次の JSON は、TPM 構成証明を使用して登録する要求の本文を示しています。

{ 
    "registrationId": "mydevice", 
    "tpm": { 
        "endorsementKey": "xxxx-device-endorsement-key-xxxx", 
        "storageRootKey": "xxx-device-storage-root-key-xxxx" 
    }, 
    "payload": { A JSON object that contains your additional data } 
}

ペイロード プロパティは JSON オブジェクトである必要があり、IoT ソリューションまたはシナリオに関連する任意のデータを含めることができます。

DPS がデバイスにデータを返す

DPS は、登録応答でデバイスにデータを返すことができます。 現時点では、この機能はカスタム割り当てシナリオでのみ使用されます。 カスタム割り当てポリシー Webhook からデバイスに何らかのデータを返す場合は、Webhook 応答内の JSON オブジェクトとしてそのデータを渡します。 DPS は、そのデータを Register Device 応答の registrationState.payload プロパティに戻します。 たとえば、次の JSON は、TPM 構成証明を使用して登録する要求の本文を示しています。

{
   "operationId":"5.316aac5bdc130deb.b1e02da8-xxxx-xxxx-xxxx-7ea7a6b7f550",
   "status":"assigned",
   "registrationState":{
      "registrationId":"my-tpm-device",
      "createdDateTimeUtc":"2022-08-31T22:02:50.5163352Z",
      "assignedHub":"sample-iot-hub-1.azure-devices.net",
      "deviceId":"my-tpm-device",
      "status":"assigned",
      "substatus":"initialAssignment",
      "lastUpdatedDateTimeUtc":"2022-08-31T22:02:50.7370676Z",
      "etag":"xxxx-etag-value-xxxx",
      "tpm": {"authenticationKey": "xxxx-encrypted-authentication-key-xxxxx"},
      "payload": { A JSON object that contains the data returned by the webhook }
   }
}

ペイロード プロパティは JSON オブジェクトである必要があり、IoT ソリューションまたはシナリオに関連する任意のデータを含めることができます。

SDK サポート

この機能は、C、C#、JAVA および Node.js のクライアント SDK で使用できます。 IoT Hub と IoT Hub Device Provisioning サービスで利用可能な Azure IoT SDK の詳細については、「Microsoft Azure IoT SDKs」を参照してください。

IoT Edge のサポート

バージョン 1.4 以降の IoT Edge では、JSON ファイルに含まれるデータ ペイロードの送信がサポートされます。 デバイスが (再) 登録されると、ペイロード ファイルが読み取られて DPS に送信されます。これは通常、iotedge config apply の初回実行時に発生します。 CLI の再プロビジョニング コマンド iotedge system reprovision を使用して、再読み取りと登録を強制的に行うこともできます。

次に示したのは、/etc/aziot/config.toml のサンプル スニペットです。payload プロパティがローカル JSON ファイルのパスに設定されています。

   [provisioning]
   source = "dps"
   global_endpoint = "https://global.azure-devices-provisioning.net"
   id_scope = "0ab1234C5D6"

   # Uncomment to send a custom payload during DPS registration
   payload = { uri = "file:///home/aziot/payload.json" }

ペイロード ファイル (この場合 /home/aziot/payload.json) には、有効な JSON であれば何でも含めることができます。以下はその例です。

{
    "modelId": "dtmi:com:example:edgedevice;1"
}

次のステップ