Noções básicas sobre as políticas de alocação personalizada com o Serviço de Provisionamento de Dispositivos no Hub IoT do Azure

Políticas de alocação personalizada proporcionam a você mais controle sobre como os dispositivos são atribuídos a seus hubs IoT. Usando políticas de alocação personalizada, você pode definir suas políticas de alocação quando as políticas internas fornecidas pelo DPS (Serviço de Provisionamento de Dispositivos) não atendem 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ê implementará uma política de alocação personalizada em um webhook hospedado no Azure Functions. Em seguida, você poderá configurar o webhook em uma ou mais inscrições individuais e grupos de inscrição. Quando um dispositivo se registra por uma entrada de inscrição 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.

Visão geral

As etapas a seguir descrevem como as políticas de alocação personalizada 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 de gatilho HTTP no Azure Functions. O webhook usa as 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 ao webhook de alocação personalizada no Azure Functions.

3. Quando um dispositivo é registrado por meio de uma entrada de registro configurada para o webhook de alocação personalizada, o DPS envia uma solicitação POST ao 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 grupo de registro ou o registro individual pelo qual ele o está provisionando. As informações do dispositivo podem incluir um payload personalizado opcional, enviado pelo dispositivo na sua solicitação de registro. Para obter mais informações, confira Solicitação de política de alocação personalizada.

4. A função do Azure executa e retorna um objeto AllocationResponse em caso de sucesso. O objeto AllocationResponse contém o hub IoT no qual o dispositivo deve ser provisionado, o estado do gêmeo inicial e um conteúdo personalizado opcional para retornar ao dispositivo. Para obter mais informações, confira 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, ele definirá o gêmeo inicial para o dispositivo de acordo. Se um conteúdo personalizado for retornado pelo webhook, ele será transmitido para o dispositivo acompanhado do hub IoT atribuído e dos detalhes de autenticação na resposta de registro do DPS.

6. O dispositivo se conecta ao hub IoT atribuído e baixa o estado do gêmeo inicial. Se um conteúdo personalizado for retornado na resposta de registro, o dispositivo o usará de acordo com a respectiva lógica do lado do cliente.

As seções a seguir fornecem mais detalhes sobre a solicitação e a resposta de alocação personalizada, os conteúdos personalizados e a implementação da 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 (Serviço de Provisionamento de Dispositivos).

Gerenciar chaves de função

As políticas de alocação personalizadas usam chaves de função para autenticar chamadas para o Azure Functions em que o nível de autorização é definido como Function. O comportamento do gerenciamento de chaves difere com base em se você configura a política de alocação personalizada por meio do portal do Azure ou programaticamente.

Chaves 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 manipula automaticamente a recuperação e a inserção da chave de função.

Depois de selecionar a função para a política de alocação personalizada, o portal recupera a chave de 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 da URL de webhook criptografada usada pelo DPS para chamar a função. A chave não é exibida no portal.

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

Chaves de função com APIs

Ao criar um registro programaticamente usando a API 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 o registro individual ou de grupo, recupere a chave de função de sua função. Para obter mais informações, consulte Obter as chaves de acesso da função. Em seguida, inclua a chave de função no campo webhookUrl do CustomAllocationDefinition.

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

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

O DPS envia uma solicitação POST para 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 esse é o registro inicial do dispositivo, a propriedade deviceRuntimeContext contém apenas a ID de registro e os detalhes de autenticação do dispositivo. O JSON a seguir mostra o deviceRuntimeContext para uma chamada seguinte para registrar o mesmo dispositivo. Observe que o nome do host do hub IoT atual e a 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 sobre 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 ao 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 os conteúdos do dispositivo na alocação personalizada

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

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

Dispositivo envia carga útil de dados para o DPS

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

Com relação ao 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}, .. } 
} 

O DPS envia o conteúdo de dados para o webhook de alocação personalizada

Se um dispositivo incluir uma solicitação de registro de conteúdo, o DPS transmitirá o conteúdo 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 runtime do dispositivo se parece com o seguinte exemplo:

{ 
    "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 esse não for o registro inicial do dispositivo, o contexto de runtime também incluirá as propriedades currentIoTHubHostname e currentDeviceId .

O webhook de alocação personalizada retorna dados ao DPS

O webhook de 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 seguinte JSON mostra uma resposta de webhook que inclui um conteúdo:

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

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

Se o DPS receber um conteúdo na resposta do webhook, ele transmitirá esses dados novamente para o dispositivo na propriedade RegistrationOperationStatus.registrationState.payload na resposta em um registro bem-sucedido. A propriedade registrationState é do tipo DeviceRegistrationResult.

O seguinte JSON 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 de implementação

O webhook de alocação personalizada pode ser chamado para um dispositivo que não foi registrado anteriormente pelo DPS (atribuição inicial) ou para um dispositivo que foi registrado anteriormente pelo DPS (reprovisionamento). O DPS dá suporte às seguintes políticas de reaprovisionamento: Reaprovisionar e migrar dados, Reaprovisionar e redefinir para a configuração inicial e Nunca reaprovisionar. 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 os conceitos de reprovisionamento de dispositivos do Hub IoT.

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

• O dispositivo deve ser atribuído a um dos hubs IoT na propriedade AllocationRequest.linkedHubs. Essa propriedade contém a lista de hubs IoT por nome do host ao qual o dispositivo pode ser atribuído. Normalmente, isso é composto pelos hubs IoT selecionados para a entrada de registro. Se nenhum hub IoT estiver 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 com a configuração de gêmeo inicial especificada na entrada de registro.

• Durante o reprovisionamento, o DPS segue a política de reprovisionamento definida na entrada de registro. O DPS utiliza a propriedade initialTwin na resposta somente se o hub IoT atual for alterado e se a política de reaprovisionamento definida na inscrição estiver em Reaprovisionar 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, conforme indicado no item anterior. Em todos os outros casos, o DPS ignora a propriedade initialTwin.

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

• 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 em que o dispositivo está atribuído no momento.

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

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

Suporte do SDK

Os SDKs de dispositivo do DPS fornecem APIs em C, C#, Java e Node.js para ajudar você a registrar os dispositivos no DPS. Os SDKs do Hub IoT e os SDKs do DPS fornecem classes que representam artefatos de dispositivo e de serviço, como dispositivos gêmeos e entradas de registro que podem ser úteis no desenvolvimento de webhooks de alocação personalizada. Para saber mais sobre os SDKs do IoT do Azure disponíveis para o Hub IoT e o serviço de provisionamento de dispositivos do Hub IoT, consulte os SDKs do Hub IoT do Azure e os SDKs da Microsoft para o Serviço de Provisionamento de Dispositivos do Hub IoT.

Próximas etapas

• Para obter um exemplo de ponta a ponta usando uma política de alocação personalizada, consulte Tutorial: Usar políticas de alocação personalizadas com o DPS (Serviço de Provisionamento de Dispositivos)

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