Compreender as políticas de alocação personalizadas com o Serviço de Provisionamento de Dispositivo do Hub IoT do Azure

  • Artigo

As políticas de alocação personalizadas oferecem mais controle sobre como os dispositivos são atribuídos aos seus hubs IoT. Usando políticas de alocação personalizadas, você pode definir suas próprias políticas de alocação quando as políticas internas fornecidas pelo Serviço de Provisionamento de Dispositivo (DPS) não atenderem aos requisitos do seu cenário.

Por exemplo, talvez você queira examinar o certificado que um dispositivo está usando durante o provisionamento e atribuir o dispositivo a um hub IoT com base em uma propriedade de certificado. Ou, talvez você tenha informações armazenadas em um banco de dados para seus dispositivos e precise consultar o banco de dados para determinar a qual hub IoT um dispositivo deve ser atribuído ou como o gêmeo inicial do dispositivo deve ser definido.

Você implementa uma política de alocação personalizada em um webhook hospedado no Azure Functions. Em seguida, você pode configurar o webhook em uma ou mais inscrições individuais e grupos de inscrição. Quando um dispositivo se registra por meio de uma entrada de registro configurada, o DPS chama o webhook que retorna o hub IoT para registrar o dispositivo e, opcionalmente, as configurações gêmeas iniciais para o dispositivo e qualquer informação a ser retornada diretamente para o dispositivo.

Descrição geral

As etapas a seguir descrevem como as políticas de alocação personalizadas funcionam:

  1. Um desenvolvedor de alocação personalizada desenvolve um webhook que implementa a política de alocação pretendida e a implanta como uma função HTTP Trigger no Azure Functions. O webhook obtém informações sobre a entrada de registro do DPS e o dispositivo e retorna o hub IoT no qual o dispositivo deve ser registrado e, opcionalmente, informações sobre o estado inicial do dispositivo.

  2. Um operador de IoT configura um ou mais registros individuais e/ou grupos de registro para alocação personalizada e fornece detalhes de chamada para o webhook de alocação personalizada no Azure Functions.

  3. Quando um dispositivo se registra por meio de uma entrada de registro configurada para o webhook de alocação personalizado, o DPS envia uma solicitação POST para o webhook com o corpo da solicitação definido como um objeto de solicitação AllocationRequest . O objeto AllocationRequest contém informações sobre o dispositivo que está tentando provisionar e o registro individual ou grupo de registro pelo qual ele está provisionando. As informações do dispositivo podem incluir uma carga personalizada opcional enviada do dispositivo na sua solicitação de registro. Para obter mais informações, consulte Solicitação de política de alocação personalizada.

  4. A Função do Azure executa e retorna um objeto AllocationResponse com êxito. O objeto AllocationResponse contém o hub IoT para o qual o dispositivo deve ser provisionado, o estado gêmeo inicial e uma carga personalizada opcional para retornar ao dispositivo. Para obter mais informações, consulte Resposta personalizada da política de alocação.

  5. O DPS atribui o dispositivo ao hub IoT indicado na resposta e, se um gêmeo inicial for retornado, define o gêmeo inicial para o dispositivo de acordo. Se uma carga personalizada for retornada pelo webhook, ela será passada para o dispositivo junto com o hub IoT atribuído e os detalhes de autenticação na resposta de registro do DPS.

  6. O dispositivo se conecta ao hub IoT atribuído e baixa seu estado gêmeo inicial. Se uma carga personalizada for retornada na resposta de registro, o dispositivo a usará de acordo com sua própria lógica do lado do cliente.

As seções a seguir fornecem mais detalhes sobre a solicitação e resposta de alocação personalizada, cargas úteis personalizadas e implementação de política. Para obter um exemplo completo de ponta a ponta de uma política de alocação personalizada, consulte Usar políticas de alocação personalizadas.

Solicitação de política de alocação personalizada

O DPS envia uma solicitação POST para seu webhook no seguinte ponto de extremidade: https://{your-function-app-name}.azurewebsites.net/api/{your-http-trigger}

O corpo da solicitação é um objeto AllocationRequest :

Property name Descrição
individualInscrição Um registro de registro individual que contém propriedades associadas ao registro individual do qual a solicitação de alocação se originou. Apresente se o dispositivo estiver a registar-se através de uma inscrição individual.
inscriçãoGrupo de Inscrição Um registro de grupo de inscrição que contém as propriedades associadas ao grupo de inscrição do qual a solicitação de alocação se originou. Apresente se o dispositivo estiver se registrando por meio de um grupo de inscrição.
deviceRuntimeContext Um objeto que contém propriedades associadas ao dispositivo que está registrando. Sempre presente.
linkedHubs Uma matriz que contém os nomes de host dos hubs IoT vinculados à entrada de registro da qual a solicitação de alocação se originou. O dispositivo pode ser atribuído a qualquer um desses hubs IoT. Sempre presente.

O objeto DeviceRuntimeContext tem as seguintes propriedades:

Propriedade Tipo Descrição
ID de registo string O ID de registro fornecido pelo dispositivo em tempo de execução. Sempre presente.
currentIotHubHostName string O nome do host do hub IoT ao qual o dispositivo foi atribuído anteriormente (se houver). Não está presente se esta for uma tarefa inicial. Você pode usar essa propriedade para determinar se esta é uma atribuição inicial para o dispositivo ou se o dispositivo foi atribuído anteriormente.
currentDeviceId string O ID do dispositivo da atribuição anterior do dispositivo (se houver). Não está presente se esta for uma tarefa inicial.
x509 X509DeviceAttestation Para o atestado X.509, contém detalhes do certificado.
simétricaChave SymmetricKeyAttestation Para atestado de chave simétrica, contém detalhes de chave primária e secundária.
tpm TpmAtestado Para o atestado TPM, contém detalhes da chave de endosso e da chave raiz de armazenamento.
payload objeto Contém propriedades especificadas pelo dispositivo na propriedade payload durante o registro. Apresente se o dispositivo enviar uma carga personalizada na solicitação de registro DPS.

O JSON a seguir mostra o objeto AllocationRequest enviado pelo DPS para um dispositivo que se registra por meio de um grupo de registro baseado em chave simétrica.

{
   "enrollmentGroup":{
      "enrollmentGroupId":"contoso-custom-allocated-devices",
      "attestation":{
         "type":"symmetricKey"
      },
      "capabilities":{
         "iotEdge":false
      },
      "etag":"\"13003fea-0000-0300-0000-62d1d5e50000\"",
      "provisioningStatus":"enabled",
      "reprovisionPolicy":{
         "updateHubAssignment":true,
         "migrateDeviceData":true
      },
      "createdDateTimeUtc":"2022-07-05T21:27:16.8123235Z",
      "lastUpdatedDateTimeUtc":"2022-07-15T21:02:29.5922255Z",
      "allocationPolicy":"custom",
      "iotHubs":[
         "custom-allocation-toasters-hub.azure-devices.net",
         "custom-allocation-heatpumps-hub.azure-devices.net"
      ],
      "customAllocationDefinition":{
         "webhookUrl":"https://custom-allocation-function-app-3.azurewebsites.net/api/HttpTrigger1?****",
         "apiVersion":"2021-10-01"
      }
   },
   "deviceRuntimeContext":{
      "registrationId":"breakroom499-contoso-tstrsd-007",
      "symmetricKey":{
         
      }
   },
   "linkedHubs":[
      "custom-allocation-toasters-hub.azure-devices.net",
      "custom-allocation-heatpumps-hub.azure-devices.net"
   ]
}

Como este é o registro inicial para o dispositivo, a propriedade deviceRuntimeContext contém apenas a ID de registro e os detalhes de autenticação para o dispositivo. O JSON a seguir mostra o deviceRuntimeContext para uma chamada subsequente para registrar o mesmo dispositivo. Observe que o nome de host e o ID do dispositivo atuais do Hub IoT estão incluídos na solicitação.

{
   "deviceRuntimeContext":{
      "registrationId":"breakroom499-contoso-tstrsd-007",
      "currentIotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
      "currentDeviceId":"breakroom499-contoso-tstrsd-007",
      "symmetricKey":{
         
      }
   },
}

Resposta personalizada da política de alocação

Uma solicitação bem-sucedida retorna um objeto AllocationResponse .

Propriedade Descrição
gêmeo inicial Opcional. Um objeto que contém as propriedades e marcas desejadas para definir no gêmeo inicial no hub IoT atribuído. O DPS usa a propriedade initialTwin para definir o gêmeo inicial no hub IoT atribuído na atribuição inicial ou ao reprovisionar se a política de migração da entrada de registro estiver definida como Reprovisionar e redefinir para a configuração inicial. Em ambos os casos, se o initialTwin não for retornado ou estiver definido como null, o DPS definirá o gêmeo no hub IoT atribuído para as configurações iniciais do gêmeo na entrada de registro. O DPS ignora o initialTwin para todas as outras configurações de reprovisionamento na entrada de registro. Para saber mais, consulte Detalhes da implementação.
iotHubHostName Obrigatório. O nome do host do hub IoT ao qual atribuir o dispositivo. Esse deve ser um dos hubs IoT passados na propriedade linkedHubs na solicitação.
payload Opcional. Um objeto que contém dados a serem passados de volta para o dispositivo na resposta Registro. Os dados exatos dependerão do contrato implícito definido pelo desenvolvedor entre o dispositivo e a função de alocação personalizada.

O JSON a seguir mostra o objeto AllocationResponse retornado por uma função de alocação personalizada para o DPS para o registro de exemplo acima.

{
   "iotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
   "initialTwin":{
      "properties":{
         "desired":{
            "state":"ready",
            "darknessSetting":"medium"
         }
      },
      "tags":{
         "deviceType":"toaster"
      }
   }
}

Usar cargas úteis do dispositivo na alocação personalizada

Os dispositivos podem enviar uma carga personalizada que é passada pelo DPS para seu webhook de alocação personalizado, que pode usar esses dados em sua lógica. O webhook pode usar esses dados de várias maneiras, talvez para determinar a qual hub IoT atribuir o dispositivo ou para procurar informações em um banco de dados externo que pode ser usado para definir propriedades no gêmeo inicial. Por outro lado, seu webhook pode retornar dados de volta para o dispositivo através do DPS, que pode ser usado na lógica do lado do cliente do dispositivo.

Por exemplo, talvez você queira alocar dispositivos com base no modelo do dispositivo. Nesse caso, você pode configurar o dispositivo para relatar suas informações de modelo na carga útil da solicitação quando ele se registrar no DPS. O DPS passará essa carga para o webhook de alocação personalizada, que determinará para qual hub IoT o dispositivo será provisionado com base nas informações do modelo do dispositivo. Se necessário, o webhook pode retornar dados ao DPS como um objeto JSON na resposta do webhook, e o DPS retornará esses dados ao seu dispositivo na resposta de registro.

O dispositivo envia carga útil de dados para o DPS

Um dispositivo chama a API de registro para se registrar no DPS. A solicitação pode ser aprimorada com a propriedade de carga útil opcional. Esta propriedade pode conter qualquer objeto JSON válido. O conteúdo exato dependerá dos requisitos da sua solução.

Para o atestado com TPM, o corpo da solicitação tem a seguinte aparência:

{ 
    "registrationId": "mydevice", 
    "tpm": { 
        "endorsementKey": "xxxx-device-endorsement-key-xxxxx", 
        "storageRootKey": "xxxx-device-storage-root-key-xxxxx" 
    }, 
    "payload": { "property1": "value1", "property2": {"propertyA":"valueA", "property2-2":1234}, .. } 
}

O DPS envia carga útil de dados para webhook de alocação personalizada

Se um dispositivo incluir uma carga útil em sua solicitação de registro, o DPS passará a carga na propriedade AllocationRequest.deviceRuntimeContext.payload quando chamar o webhook de alocação personalizada.

Para a solicitação de registro do TPM na seção anterior, o contexto de tempo de execução do dispositivo terá a seguinte aparência:

{ 
    "registrationId": "mydevice", 
    "tpm": { 
        "endorsementKey": "xxxx-device-endorsement-key-xxxxx", 
        "storageRootKey": "xxxx-device-storage-root-key-xxxxx" 
    }, 
    "payload": { "property1": "value1", "property2": {"propertyA":"valueA", "property2-2":1234}, .. } 
}

Se este não for o registro inicial para o dispositivo, o contexto de tempo de execução também incluirá as propriedades currentIoTHubHostname e currentDeviceId.

Webhook de alocação personalizada retorna dados para DPS

O webhook da política de alocação personalizada pode retornar dados destinados a um dispositivo para o DPS em um objeto JSON usando a propriedade AllocationResponse.payload na resposta do webhook.

O JSON a seguir mostra uma resposta de webhook que inclui uma carga útil:

{
   "iotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
   "initialTwin":{
      "properties":{
         "desired":{
            "state":"ready",
            "darknessSetting":"medium"
         }
      },
      "tags":{
         "deviceType":"toaster"
      }
   },
   "payload": { "property1": "value1" } 
}

O DPS envia carga útil de dados para o dispositivo

Se o DPS receber uma carga na resposta do webhook, ele passará esses dados de volta para o dispositivo na propriedade RegistrationOperationStatus.registrationState.payload na resposta em um registro bem-sucedido. A propriedade registrationState é do tipo DeviceRegistrationResult.

O JSON a seguir mostra uma resposta de registro bem-sucedida para um dispositivo TPM que inclui a propriedade payload :

{
   "operationId":"5.316aac5bdc130deb.b1e02da8-xxxx-xxxx-xxxx-7ea7a6b7f550",
   "status":"assigned",
   "registrationState":{
      "assignedHub":"myIotHub",
      "createdDateTimeUtc" : "2022-08-01T22:57:47Z",
      "deviceId" : "myDeviceId",
      "etag" : "xxxx-etag-value-xxxxx",
      "lastUpdatedDateTimeUtc" : "2022-08-01T22:57:47Z",
      "payload": { "property1": "value1" },
      "registrationId": "mydevice", 
      "status": assigned,
      "substatus": initialAssignment,
      "tpm": {"authenticationKey": "xxxx-encrypted-authentication-key-xxxxx"}
   }
}

Detalhes da implementação

O webhook de alocação personalizada pode ser chamado para um dispositivo que não foi registrado anteriormente através do DPS (atribuição inicial) ou para um dispositivo que foi registrado anteriormente através do DPS (reprovisionamento). O DPS suporta as seguintes políticas de reprovisionamento: Reprovisionar e migrar dados, Reprovisionar e redefinir para a configuração inicial e Nunca reprovisionar. Essas políticas são aplicadas sempre que um dispositivo provisionado anteriormente é atribuído a um novo hub IoT. Para obter mais detalhes, consulte Reprovisionamento.

Os pontos a seguir descrevem os requisitos que seu webhook de alocação personalizada deve observar e o comportamento que você deve estar ciente ao projetar seu webhook:

  • O dispositivo deve ser atribuído a um dos hubs IoT na propriedade AllocationRequest.linkedHubs . Esta propriedade contém a lista de hubs IoT por nome de host aos quais o dispositivo pode ser atribuído. Isso geralmente é composto pelos hubs IoT selecionados para a entrada de inscrição. Se nenhum hub IoT for selecionado na entrada de registro, ele conterá todos os hubs IoT vinculados à instância do DPS. Por fim, se o dispositivo estiver reprovisionando e a política Nunca reprovisionar estiver definida na entrada de registro, ela conterá apenas o hub IoT ao qual o dispositivo está atribuído no momento.

  • Na atribuição inicial, se a propriedade initialTwin for retornada pelo webhook, o DPS definirá o gêmeo inicial para o dispositivo no hub IoT atribuído de acordo. Se a propriedade initialTwin for omitida ou for nula, o DPS definirá o gêmeo inicial do dispositivo para a configuração de gêmeo inicial especificada na entrada de registro.

  • No reprovisionamento, o DPS segue a política de reprovisionamento definida na entrada de registro. O DPS só usa a propriedade initialTwin na resposta se o hub IoT atual for alterado e a política de reprovisionamento definida na entrada de registro for Reprovisionar e redefinir para a configuração inicial. Nesse caso, o DPS define o gêmeo inicial para o dispositivo no novo hub IoT exatamente como faria durante a atribuição inicial no marcador anterior. Em todos os outros casos, o DPS ignora a propriedade initialTwin .

  • Se a propriedade payload estiver definida na resposta, o DPS sempre a retornará ao dispositivo, independentemente de a solicitação ser para atribuição inicial ou reprovisionamento.

  • Se um dispositivo tiver sido provisionado anteriormente para um hub IoT, o AllocationRequest.deviceRuntimeContext conterá uma propriedade currentIotHubHostName, que será definida como o nome do host do hub IoT onde o dispositivo está atribuído no momento.

  • Você pode determinar qual das políticas de reprovisionamento está definida atualmente na entrada de registro, examinando a propriedade reprovisionPolicy da propriedade AllocationRequest.individualEnrollment ou da propriedade AllocationRequest.enrollmentGroup na solicitação. o JSON a seguir mostra as configurações para a política de reprovisionamento e migração de dados :

           "reprovisionPolicy":{
          "updateHubAssignment":true,
          "migrateDeviceData":true
       }

Suporte SDK

Os SDKs de dispositivo DPS fornecem APIs em C, C#, Java e Node.js para ajudá-lo a registrar dispositivos com DPS. Tanto os SDKs do Hub IoT quanto os SDKs do DPS fornecem classes que representam artefatos de dispositivo e serviço, como gêmeos de dispositivo e entradas de registro que podem ser úteis ao desenvolver webhooks de alocação personalizados. 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 do Hub IoT do Azure e SDKs do DPS do Azure.

Próximos passos