Compartilhar via

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

  • Artigo

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 um ou mais registros individuais e grupos de registro. Quando um dispositivo é registrado 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 do gêmeo inicial para o dispositivo e qualquer informação a ser retornada diretamente para o dispositivo.

Visão geral

As seguintes etapas descrevem como as polícias 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 conteúdo personalizado opcional enviado do dispositivo na 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 sua própria 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 ver um exemplo completo de ponta a ponta de uma política de alocação personalizada, confira Usar políticas de alocação personalizada.

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 está 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, consulte Gatilho HTTP do Azure Functions > Autorização de Chave de acesso.

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

O DPS envia uma solicitação POST ao 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:

Nome da propriedade Descrição
individualEnrollment Um registro de registro individual que contém propriedades associadas ao registro individual do qual a solicitação de alocação se originou. Presente se o dispositivo está se registrando por meio de um registro individual.
enrollmentGroup Um registro de grupo de registro que contém as propriedades associadas ao grupo de registro do qual a solicitação de alocação se originou. Presente se o dispositivo está se registrando por meio de um grupo de registro.
deviceRuntimeContext Um objeto que contém propriedades associadas ao dispositivo que está sendo registrado. Sempre presente.
linkedHubs Uma matriz que contém os nomes do host dos hubs IoT que estão vinculados à entrada de registro da qual a solicitação de alocação se originou. O dispositivo pode ser atribuído a um desses hubs IoT. Sempre presente.

O objeto DeviceRuntimeContext tem as seguintes propriedades:

Propriedade Type Descrição
registrationId string A ID de registro fornecida pelo dispositivo em runtime. Sempre presente.
currentIotHubHostName string O nome do host do hub IoT ao qual o dispositivo foi atribuído anteriormente (se houver). Não presente se essa for uma atribuição inicial. Use essa propriedade para determinar se essa é uma atribuição inicial para o dispositivo ou se o dispositivo foi atribuído anteriormente.
currentDeviceId string A identidade do dispositivo da atribuição anterior do dispositivo (se houver). Não presente se essa for uma atribuição inicial.
x509 X509DeviceAttestation Para o atestado X.509, contém os detalhes do certificado.
symmetricKey SymmetricKeyAttestation Para o atestado de chave simétrica, contém detalhes da chave primária e secundária.
tpm TpmAttestation Para o atestado do TPM, contém detalhes da chave de endosso e da chave de raiz de armazenamento.
payload objeto Contém as propriedades especificadas pelo dispositivo na propriedade de conteúdo durante o registro. Presente se o dispositivo enviar um conteúdo personalizado na solicitação de registro do 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 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 identidade 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.

Propriedade Descrição
initialTwin Opcional. Um objeto que contém as propriedades e as marcas desejadas a serem definidas 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 reaprovisionar, se a política de migração da entrada do registro estiver definida como Reaprovisionar e redefinir para a configuração inicial. Em ambos os casos, se o initialTwin não for retornado ou for definido como nulo, o DPS definirá o gêmeo no hub IoT atribuído para as configurações do gêmeo inicial na entrada do registro. O DPS ignora o initialTwin para todas as outras configurações de reaprovisionamento na entrada do registro. Para saber mais, confira Detalhes da implementação.
iotHubHostName Obrigatória. O nome do host do hub IoT que será atribuído ao dispositivo. Ele precisa ser um dos hubs IoT transmitidos na propriedade linkedHubs na solicitação.
payload Opcional. Um objeto que contém os dados a serem transmitidos novamente para o dispositivo na resposta de 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 ao 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 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 o dispositivo será atribuído ou pesquisar informações em um banco de dados externo que possa ser usado para definir as propriedades no gêmeo inicial. Por outro lado, o webhook pode retornar dados ao dispositivo por meio do DPS, que pode ser usado na lógica do lado do cliente do dispositivo.

Por exemplo, o ideal é alocar os 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 transmitirá esse conteúdo para o webhook de alocação personalizada, que determinará o hub IoT no qual o dispositivo será provisionado com base nas informações do modelo de dispositivo. Se necessário, o webhook pode retornar dados novamente 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 o conteúdo 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 payload opcional. Essa propriedade pode conter qualquer objeto JSON válido. O conteúdo exato dependerá dos requisitos da sua solução.

Para o atestado com o TPM, o corpo da solicitação é semelhante ao seguinte:

{ 
    "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 será semelhante ao seguinte:

{ 
    "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 por meio do DPS (atribuição inicial) ou para um dispositivo que foi registrado anteriormente por meio do 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 detalhes, confira Reprovisionamento.

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 for selecionado na entrada de registro, ele conterá todos os hubs IoT vinculados à instância do DPS. Para terminar, se estiver reaprovisionando e a política Nunca reaprovisionar estiver definida na entrada do registro, o dispositivo 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 só usará a propriedade initialTwin na resposta se o hub IoT atual for alterado e a política de reaprovisionamento definida na entrada do registro for 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 o faria durante a atribuição inicial 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 inicial ou reprovisionamento.

  • Se um dispositivo tiver sido provisionado anteriormente em um hub IoT, o AllocationRequest.deviceRuntimeContext conterá uma propriedade currentIotHubHostName, que será 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 no Hub IoT, confira SDK do Hub IoT do Azure e SDKs do Azure DPS.

Próximas etapas