如何在设备和 DPS 之间传输有效负载

项目
06/17/2024

向 DPS 注册的设备在注册时需要提供注册 ID 和有效凭据（密钥或 X.509 证书）。但是，某些 IoT 解决方案或场景需要设备提供的额外数据。例如，自定义分配策略 Webhook 可以使用设备型号等信息来选择要将设备预配到的 IoT 中心。同样，设备可能需要使用注册响应中的附加数据来简化其客户端逻辑。 DPS 为设备提供了在注册时发送和接收可选有效负载的功能。

何时使用

发送可选有效负载的常见场景是：

自定义分配策略可以使用设备有效负载来帮助选择设备的 IoT 中心或设置其初始孪生。例如，你可能希望根据设备型号分配设备。在这种情况下，可将设备配置为在注册时报告其型号信息。 DPS 会将设备的有效负载传入自定义分配 Webhook。然后，Webhook 可以根据设备型号信息决定将设备预配到哪个 IoT 中心。如果需要，Webhook 还可以在 Webhook 响应中将数据以 JSON 对象的形式返回给设备。有关详细信息，请参阅在自定义分配中使用设备有效负载。
IoT 即插即用 (PnP) 设备可以在向 DPS 注册时使用有效负载发送其型号 ID。可以在 SDK 或示例存储库中的 PnP 示例中找到此用法的示例。例如，C# PnP 恒温器或 Node.js PnP 温度控制器。
通过 DPS 连接的 IoT Central 设备应遵循 IoT 即插即用约定，并在注册时发送其型号 ID。 IoT Central 使用型号 ID 将设备分配到正确的设备模板。

设备将数据有效负载发送到 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.cn",
      "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，请参阅 Azure IoT SDK。

IoT Edge 支持

从 1.4 版开始，IoT Edge 支持发送 JSON 文件中包含的数据有效负载。在设备（重新）注册时（这通常在你首次运行 iotedge config apply 时发生）读取有效负载文件并将其发送到 DPS。也可以使用 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"
}

后续步骤

有关自定义分配策略的概述，请参阅了解自定义分配策略
若要了解如何使用自定义分配策略预配设备，请参阅使用自定义分配策略

通过