Como transferir conteúdos entre dispositivos e o DPS

Artigo
03/15/2023

Os dispositivos registrados com DPS são necessários para fornecer uma ID de registro e credenciais válidas (chaves ou certificados X.509) no momento do registro. No entanto, pode haver soluções de IoT ou cenários em que dados adicionais são necessários no 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 em que o dispositivo deve ser provisionado. Da mesma forma, um dispositivo pode exigir dados adicionais na resposta de registro para facilitar a lógica do lado do cliente. O DPS fornece aos dispositivos a capacidade de enviar e receber um payload opcional no momento do registro.

Quando usar isso

Cenários comuns para enviar payloads opcionais são:

As políticas de alocação personalizadas podem usar o payload do dispositivo para ajudar a selecionar um hub IoT para um dispositivo ou definir o gêmeo inicial. Por exemplo, convém alocar os dispositivos com base no modelo de dispositivo. Nesse caso, você pode configurar o dispositivo para relatar as informações do modelo no momento do registro. O DPS transmite o conteúdo do dispositivo para o webhook de alocação personalizada. Em seguida, o webhook pode decidir para qual Hub IoT o dispositivo será provisionado com base nas informações do modelo de dispositivo. Se necessário, o webhook também pode retornar dados ao dispositivo como um objeto JSON na resposta do webhook. Para saber mais, confira Usar conteúdos do dispositivo na alocação personalizada.
Os dispositivos IoT Plug and Play (PnP) podem usar o payload para enviar a ID do modelo no momento do registro com o DPS. Você pode encontrar exemplos desse uso nos exemplos de PnP no SDK ou repositórios de exemplo. Por exemplo, termostato pnP C# ou controlador de temperatura Node.js PnP.
Os dispositivos IoT Central que se conectam por meio do DPS devem seguir as convenções IoT Plug and Play e enviar a ID do modelo no momento do registro. O IoT Central usa a ID do modelo para atribuir o dispositivo ao modelo de dispositivo correto. Para saber mais, confira Implementação de dispositivo e melhores práticas para o IoT Central.

O dispositivo envia o conteúdo de dados para o DPS

Quando o dispositivo chama o Dispositivo de Registro para se registrar no DPS, ele pode incluir dados adicionais na propriedade payload. 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 a solução ou o cenário de IoT.

O DPS retorna dados para o dispositivo

O DPS pode retornar dados para o dispositivo na resposta de registro. No momento, 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 pode devolver os dados como um objeto JSON na resposta do webhook. Em seguida, o DPS devolverá esses dados na propriedade registrationState.payload na resposta do Dispositivo de Registro. 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 a solução ou o cenário de IoT.

Suporte do SDK

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

Suporte do Azure IoT Edge

A partir da versão 1.4, IoT Edge dá suporte ao envio de uma carga de dados contida em um arquivo JSON. O arquivo de carga é 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 lido novamente e registrado usando o comando de reprovisionamento da CLI iotedge system reprovision.

Veja abaixo um snippet de exemplo de /etc/aziot/config.toml, em que a propriedade payload está definida como o caminho de 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 conteúdo (neste caso /home/aziot/payload.json) pode conter qualquer JSON válido, como:

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

Próximas etapas

Para obter uma visão geral das políticas de alocação personalizadas, confira Entender políticas de alocação personalizadas
Para saber como provisionar dispositivos usando uma política de alocação personalizada, confira Usar políticas de alocação personalizadas

Compartilhar via