共用方式為

如何在裝置與 DPS 之間傳輸承載

  • 發行項

向 DPS 註冊的裝置必須在註冊時提供註冊識別碼和有效的認證 (金鑰或 X.509 憑證)。 不過，有些 IoT 解決方案或案例可能需要另行提供裝置資料。 例如，自訂配置原則 Webhook 可能會使用裝置型號等資訊，選取要佈建裝置的 IoT 中樞。 同樣地，裝置可能需要註冊回應中的其他資料，以協助用戶端邏輯。 DPS 讓裝置能夠在註冊時傳送及接收選擇性的承載。

使用時機

傳送選擇性承載的常見案例如下：

  • 自訂配置原則可以使用裝置承載協助裝置選取 IoT 中樞，或設定其初始對應項。 例如，您可能想要根據裝置型號來配置裝置。 在此情況下，您可以設定裝置在註冊時報告其型號資訊。 DPS 會將裝置的承載傳遞至自訂配置 Webhook。 然後，您的 Webhook 可以根據裝置的型號資訊，決定裝置要佈建的 IoT 中樞。 如有需要，Webhook 也可以將資料作為 Webhook 回應中的 JSON 物件，傳回給裝置。 若要深入了解，請參閱在自訂配置中使用裝置承載。

  • IoT 隨插即用 (PnP) 裝置「可能」會在向 DPS 註冊時使用承載傳送其型號。 您可以在 SDK 或範例存放庫的 PnP 範例中找到此用法的範例。 例如，C# PnP 恆溫器或 Node.js PnP 溫度控制器。

  • 透過 DPS 連線的 IoT Central 裝置「應」遵循 IoT 隨插即用慣例，並在註冊時傳送其型號。 IoT Central 會使用型號識別碼將裝置指派給正確的裝置範本。 若要深入了解，請參閱 IoT Central 的裝置實作和最佳做法。

裝置會將資料承載傳送至 DPS

當您的裝置呼叫註冊裝置向 DPS 註冊時，可以在 payload 屬性中包含其他資料。 例如，下列 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 } 
}

payload 屬性必須是 JSON 物件，且可包含所有與 IoT 解決方案或案例相關的資料。

DPS 會將資料傳回裝置

DPS 可以在註冊回應中將資料傳回給裝置。 這項功能目前僅能在自訂配置案例中使用。 如果自訂配置原則 Webhook 需要將資料傳回裝置，可以將資料當作 Webhook 回應中的 JSON 物件傳回。 DPS 接著會使用註冊裝置回應中的 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 }
   }
}

payload 屬性必須是 JSON 物件，且可包含所有與 IoT 解決方案或案例相關的資料。

SDK 支援

此功能適用於 C、C#、JAVA 和 Node.js 用戶端 SDK。 若要深入了解適用於 IoT 中樞和 IoT 中樞裝置佈建服務的 Azure IoT SDK，請參閱 Microsoft Azure IoT SDK。

IoT Edge 支援

從 1.4 版開始，IoT Edge 支援傳送包含在 JSON 檔案中的資料承載。 當裝置 (重新) 註冊時，承載檔案會被讀取並傳送至 DPS，這通常會在您第一次執行 iotedge config apply 時發生。 您也可以使用 CLI 的重新佈建命令 iotedge system reprovision 強制重新讀取及註冊承載檔案。

以下是 payload 屬性設為本機 JSON 檔案路徑之 /etc/aziot/config.toml 的範例程式碼片段。

   [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"
}

下一步