Como transferir cargas úteis entre dispositivos e DPS

  • Artigo

Os dispositivos que se registam no DPS têm de fornecer um ID de registo e credenciais válidas (chaves ou certificados X.509) quando se registam. No entanto, pode haver soluções de IoT ou cenários em que dados adicionais são necessários do dispositivo. Por exemplo, um webhook de política de alocação personalizada pode usar informações como um número de modelo de dispositivo para selecionar um hub IoT para provisionar o dispositivo. Da mesma forma, um dispositivo pode exigir dados adicionais na resposta de registro para facilitar sua lógica do lado do cliente. O DPS fornece a capacidade de os dispositivos enviarem e receberem uma carga útil opcional quando se registrarem.

Quando Utilizar

Os cenários comuns para o envio de cargas úteis opcionais são:

  • As políticas de alocação personalizadas podem usar a carga útil do dispositivo para ajudar a selecionar um hub IoT para um dispositivo ou definir seu gêmeo inicial. Por exemplo, você pode querer alocar seus dispositivos com base no modelo do dispositivo. Nesse caso, você pode configurar o dispositivo para relatar suas informações de modelo quando ele se registrar. O DPS passará a carga útil do dispositivo para o webhook de alocação personalizado. Em seguida, seu webhook pode decidir para qual hub IoT o dispositivo será provisionado com base nas informações do modelo do dispositivo. Se necessário, o webhook também pode retornar dados de volta ao dispositivo como um objeto JSON na resposta do webhook. Para saber mais, consulte Usar cargas úteis do dispositivo na alocação personalizada.

  • Os dispositivos IoT Plug and Play (PnP) podem usar a carga útil para enviar seu ID de modelo quando se registrarem no DPS. Você pode encontrar exemplos desse uso nos exemplos PnP no SDK ou repositórios de exemplo. Por exemplo, termostato PnP C# ou controlador de temperatura PnP Node.js.

  • Os dispositivos IoT Central que se conectam por meio do DPS devem seguir as convenções IoT Plug and Play e enviar sua ID de modelo quando se registrarem. O IoT Central usa o ID do modelo para atribuir o dispositivo ao modelo de dispositivo correto. Para saber mais, consulte Implementação de dispositivos e práticas recomendadas para o IoT Central.

O dispositivo envia carga útil de dados para o DPS

Quando seu dispositivo chama Registrar dispositivo para se registrar no DPS, ele pode incluir dados adicionais na propriedade de carga útil. Por exemplo, o JSON a seguir mostra o corpo de uma solicitação de registro usando o atestado 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 } 
}

A propriedade payload deve ser um objeto JSON e pode conter quaisquer dados relevantes para sua solução ou cenário de IoT.

O DPS retorna dados para o dispositivo

O DPS pode retornar dados para o dispositivo na resposta de registro. Atualmente, esse recurso é usado exclusivamente em cenários de alocação personalizados. Se o webhook de política de alocação personalizada precisar retornar dados para o dispositivo, ele poderá passar os dados de volta como um objeto JSON na resposta do webhook. O DPS passará esses dados de volta para a propriedade registrationState.payload na resposta Registrar dispositivo. Por exemplo, o JSON a seguir mostra o corpo de uma resposta bem-sucedida para registrar usando o atestado 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 }
   }
}

A propriedade payload deve ser um objeto JSON e pode conter quaisquer dados relevantes para sua solução ou cenário de IoT.

Suporte SDK

Esse recurso está disponível em C, C#, JAVA e Node.js SDKs de cliente. Para saber mais sobre os SDKs do Azure IoT disponíveis para o Hub IoT e o serviço de Provisionamento de Dispositivo do Hub IoT, consulte SDKs IoT do Microsoft Azure.

Suporte ao IoT Edge

A partir da versão 1.4, o IoT Edge oferece suporte ao envio de uma carga útil de dados contida em um arquivo JSON. O arquivo de carga útil é lido e enviado para o DPS quando o dispositivo é (re)registrado, o que normalmente acontece quando você executa iotedge config apply pela primeira vez. Você também pode forçá-lo a ser relido e registrado usando o comando iotedge system reprovisionreprovision da CLI .

Abaixo está um trecho de exemplo de onde a payload propriedade é definida para o caminho de /etc/aziot/config.toml um arquivo JSON local.

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

O arquivo de carga útil (neste caso /home/aziot/payload.json) pode conter qualquer JSON válido, como:

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

Próximos passos