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

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. Pode então configurar o webhook em um ou mais registos 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 quaisquer informações a serem retornadas 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 uma ou mais inscrições individuais e/ou grupos de inscrição para alocação personalizada e fornece detalhes de chamada para o webhook de alocação personalizada nas Azure Functions.

3. Quando um dispositivo se regista através de uma entrada de adesão 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á a tentar provisionar e o registo individual ou grupo de registo através do qual está a provisionar. As informações do dispositivo podem incluir uma carga personalizada opcional enviada do dispositivo no seu pedido de registo. 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 da política de alocação personalizada.

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 juntamente 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 mais informações sobre um exemplo completo de ponta a ponta de uma política de alocação personalizada, consulte Tutorial: Usar políticas de alocação personalizadas com o DPS (Device Provisioning Service).

Gerenciar teclas de função

As políticas de alocação personalizadas usam teclas de função para autenticar chamadas para o Azure Functions onde o nível de autorização está definido como Function. O comportamento do gerenciamento de chaves difere com base na configuração da política de alocação personalizada por meio do portal do Azure ou programaticamente.

Teclas de função no portal

Quando você cria um registro no portal do Azure e especifica uma política de alocação personalizada, o portal lida automaticamente com a recuperação e incorporação da chave de função.

Depois de selecionar a função para a política de alocação personalizada, o portal obtém a chave da função. Esta etapa não é visível para os usuários por meio da interface do portal. Em seguida, a chave de função é armazenada como parte do URL de webhook criptografado usado pelo DPS para chamar a função. A chave não é exibida no portal.

Você pode verificar se a chave está incorporada na URL do webhook executando um comando GET para recuperar os detalhes do registro. Na configuração de inscrição, a tecla de função é incluída no campo webhookUrl.

Teclas de função com APIs

Ao criar um registro programaticamente usando a API do DPS, você precisa fornecer manualmente a chave durante a criação do registro. Se a chave não for fornecida, a chamada do Azure Functions falhará na autenticação.

Antes de criar a inscrição individual ou de grupo, recupere a chave de função da sua função. Para obter mais informações, consulte Obter as teclas de acesso da função. Em seguida, inclua a chave de função no campo webhookUrl de CustomAllocationDefinition.

Para obter mais informações, consulte Autorização de chave de acesso.

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

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

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

O objeto DeviceRuntimeContext tem as seguintes propriedades:

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 do hub IoT atual e o ID do dispositivo 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 da política de alocação personalizada

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

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

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

Usar cargas do dispositivo numa alocação personalizada

Os dispositivos podem enviar uma carga útil personalizada que é passada pelo DPS para o seu webhook de alocação personalizado, que pode então usar esses dados na sua lógica. O webhook pode usar esses dados de muitas 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 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 passa essa carga para o webhook de alocação personalizada, que determina para qual hub IoT o dispositivo é 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 retorna esses dados ao seu dispositivo na resposta de registro.

O dispositivo envia um pacote de dados para DPS

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

Para o atestado com TPM, o corpo da solicitação se parece com o exemplo a seguir:

{ 
    "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}, .. } 
} 

DPS envia payload de dados para webhook de atribuição personalizada

Se um dispositivo incluir uma carga útil na 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 se parece com o exemplo a seguir:

{ 
    "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 o DPS

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

O JSON a seguir mostra uma resposta de webhook que inclui um payload.

{
   "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 retornará esses dados para o dispositivo na propriedade RegistrationOperationStatus.registrationState.payload como parte de uma resposta de registo 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 tinha sido registado anteriormente através do DPS (atribuição inicial) ou para um dispositivo que tinha sido registado 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 informações, consulte Conceitos de reprovisionamento de dispositivos do Hub IoT.

Os pontos a seguir descrevem os requisitos que o seu webhook de alocação personalizada deve observar e o comportamento de que deve estar ciente ao conceber o 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. Geralmente, é composto pelos hubs IoT selecionados para a 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 inicial especificada no registo de inscrição.

• Durante o reprovisionamento, o DPS segue a política de reprovisionamento definida na entrada de inscrição. O DPS só utiliza a propriedade initialTwin na resposta se o IoT hub atual for alterado e a política de reprovisionamento definida na entrada de inscrição for Reprovisionar e redefinir para a configuração inicial. Nesse caso, o DPS define o gêmeo inicial para o dispositivo no novo IoT hub exatamente como faria durante a atribuição inicial no ponto anterior. Em todos os outros casos, o DPS ignora o parâmetro 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 foi provisionado anteriormente para um hub IoT, o AllocationRequest.deviceRuntimeContext contém uma propriedade currentIotHubHostName , que é 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á atualmente configurada na inscrição, examinando a propriedade reprovisionPolicy da propriedade AllocationRequest.individualEnrollment ou da propriedade AllocationRequest.enrollmentGroup no pedido. 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 dispositivos e serviços, como gêmeos digitais de dispositivos 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 da Microsoft para o Serviço de Provisionamento de Dispositivo do Hub IoT.

Próximos passos

• Para obter um exemplo completo usando uma política de alocação personalizada, consulte Tutorial: Usar políticas de alocação personalizadas com o DPS (Device Provisioning Service)

• Para saber mais sobre o Azure Functions, consulte a documentação do Azure Functions