Partilhar via

Compreender o registo de identidade no seu hub IoT

  • Artigo

Cada hub IoT tem um registro de identidade que armazena informações sobre os dispositivos e módulos permitidos para se conectar ao hub IoT. Antes que um dispositivo ou módulo possa se conectar a um hub IoT, deve haver uma entrada para esse dispositivo ou módulo no registro de identidade do hub IoT. Um dispositivo ou módulo também deve se autenticar com o hub IoT com base nas credenciais armazenadas no registro de identidade.

O ID do dispositivo ou módulo armazenado no registro de identidade diferencia maiúsculas de minúsculas.

Em um alto nível, o registro de identidade é uma coleção compatível com REST de recursos de identidade de dispositivo ou módulo. Quando você adiciona uma entrada no registro de identidade, o Hub IoT cria um conjunto de recursos por dispositivo, como a fila que contém mensagens de nuvem para dispositivo em voo.

Use o registro de identidade quando precisar:

  • Provisione dispositivos ou módulos que se conectam ao seu hub IoT.
  • Controle o acesso por dispositivo/por módulo ao dispositivo do seu hub ou aos pontos finais voltados para o módulo.

Operações de registo de identidade

O registro de identidade do Hub IoT expõe as seguintes operações:

  • Criar identidade de dispositivo ou módulo
  • Atualizar a identidade do dispositivo ou módulo
  • Recuperar identidade do dispositivo ou módulo por ID
  • Excluir identidade do dispositivo ou módulo
  • Listar até 1000 identidades
  • Exportar identidades de dispositivo para o armazenamento de blobs do Azure
  • Importar identidades de dispositivo do armazenamento de blob do Azure

Todas essas operações podem usar simultaneidade otimista, conforme especificado no RFC7232.

Importante

A única maneira de recuperar todas as identidades no registro de identidade de um hub IoT é usar a funcionalidade Exportar .

Um registro de identidade do Hub IoT:

  • Não contém metadados de aplicativos.

Importante

Use apenas o registro de identidade para operações de provisionamento e gerenciamento de dispositivos. As operações de alta taxa de transferência em tempo de execução não devem depender da execução de operações no registro de identidade. Por exemplo, verificar o estado de conexão de um dispositivo antes de enviar um comando não é um padrão suportado. Certifique-se de verificar as taxas de limitação para o registro de identidade.

Nota

Pode levar alguns segundos para que uma identidade de dispositivo ou módulo esteja disponível para recuperação após a criação. Tente novamente a get operação de identidades de dispositivo ou módulo em caso de falhas.

Desativar dispositivos

Você pode desabilitar dispositivos atualizando a propriedade status de uma identidade no registro de identidade. Normalmente, você usa essa propriedade em dois cenários:

  • Durante um processo de orquestração de provisionamento. Para obter mais informações, consulte Provisionamento de dispositivos.

  • Se você acha que um dispositivo está comprometido ou se tornou não autorizado por qualquer motivo.

    Importante

    O Hub IoT não verifica as listas de revogação de certificados ao autenticar dispositivos com autenticação baseada em certificados. Se você tiver um dispositivo que precisa ser impedido de se conectar ao Hub IoT devido a um certificado potencialmente comprometido, desative o dispositivo no registro de identidade.

Este recurso não está disponível para módulos.

Para obter mais informações, consulte Desabilitar ou excluir um dispositivo em um hub IoT.

Importar e exportar identidades de dispositivos

Use operações assíncronas no ponto de extremidade do provedor de recursos do Hub IoT para exportar identidades de dispositivo em massa do registro de identidade de um hub IoT. As exportações são trabalhos de longa execução que usam um contêiner de blob fornecido pelo cliente para salvar os dados de identidade do dispositivo lidos do registro de identidade.

Use operações assíncronas no ponto de extremidade do provedor de recursos do Hub IoT para importar identidades de dispositivo em massa para o registro de identidade de um hub IoT. As importações são trabalhos de longa execução que usam dados em um contêiner de blob fornecido pelo cliente para gravar dados de identidade do dispositivo no registro de identidade.

Para obter mais informações sobre as APIs de importação e exportação, consulte APIs REST do provedor de recursos do Hub IoT. Para saber mais sobre como executar trabalhos de importação e exportação, consulte Gerenciamento em massa de identidades de dispositivo do Hub IoT.

As identidades de dispositivo também podem ser exportadas e importadas de um hub IoT usando a API de Serviço por meio da API REST ou de um dos SDKs de Serviço do Hub IoT.

Provisionamento de dispositivos

Os dados do dispositivo que uma determinada solução de IoT armazena dependem dos requisitos específicos dessa solução. Mas, no mínimo, uma solução deve armazenar identidades de dispositivo e chaves de autenticação. O Hub IoT do Azure inclui um registro de identidade que pode armazenar valores para cada dispositivo, como IDs, chaves de autenticação e códigos de status. Uma solução pode usar outros serviços do Azure, como armazenamento de tabela, armazenamento de Blob ou Azure Cosmos DB para armazenar outros dados de dispositivo.

O provisionamento de dispositivos é o processo de adicionar os dados iniciais do dispositivo aos armazenamentos em sua solução. Para permitir que um novo dispositivo se conecte ao seu hub, você deve adicionar uma ID de dispositivo e chaves ao registro de identidade do Hub IoT. Como parte do processo de provisionamento, talvez seja necessário inicializar dados específicos do dispositivo em outros repositórios de soluções. Você também pode usar o Serviço de Provisionamento de Dispositivo do Hub IoT do Azure para habilitar o provisionamento zero-touch, just-in-time para um ou mais hubs IoT sem exigir intervenção humana. Para saber mais, consulte a documentação do serviço de provisionamento.

Notificações do ciclo de vida do dispositivo e do módulo

O Hub IoT pode notificar sua solução de IoT quando uma identidade de dispositivo é criada ou excluída enviando notificações de ciclo de vida. Para fazer isso, sua solução de IoT precisa criar uma rota e definir a fonte de dados igual a DeviceLifecycleEvents. Por padrão, nenhuma notificação de ciclo de vida é enviada, ou seja, não existem tais rotas. Ao criar uma rota com Data Source igual a DeviceLifecycleEvents, os eventos do ciclo de vida são enviados para identidades de dispositivo e identidades de módulo. O conteúdo da mensagem difere dependendo se os eventos são gerados para identidades de módulo ou identidades de dispositivo. Para saber mais sobre as propriedades e o corpo retornados na mensagem de notificação, consulte Esquemas de eventos sem telemetria.

As notificações para a criação de identidade de módulo são diferentes para módulos do IoT Edge do que para outros módulos. Para módulos do IoT Edge, a notificação de criação só é enviada se o dispositivo IoT Edge correspondente estiver em execução. Para todos os outros módulos, as notificações do ciclo de vida são enviadas sempre que a identidade do módulo é atualizada no lado do Hub IoT.

Propriedades de identidade do dispositivo

As identidades de dispositivo são representadas como documentos JSON com as seguintes propriedades:

Property Opções Description
deviceId obrigatório, somente leitura em atualizações Uma cadeia de caracteres que diferencia maiúsculas de minúsculas (até 128 caracteres) de caracteres alfanuméricos ASCII de 7 bits mais certos caracteres especiais: - . % _ * ? ! ( ) , : = @ $ '. Os caracteres especiais: + # não são suportados.
geraçãoId obrigatório, somente leitura Uma cadeia de caracteres gerada pelo hub IoT, sensível a maiúsculas e minúsculas, com até 128 caracteres. Esse valor é usado para distinguir dispositivos com o mesmo deviceId, quando eles foram excluídos e recriados.
etag obrigatório, somente leitura Uma cadeia de caracteres que representa um ETag fraco para a identidade do dispositivo, conforme RFC7232.
autenticação opcional Um objeto composto contendo informações de autenticação e materiais de segurança. Para obter mais informações, consulte Mecanismo de autenticação na documentação da API REST.
capacidades opcional O conjunto de capacidades do dispositivo. Por exemplo, se o dispositivo é um dispositivo de borda ou não. Para obter mais informações, consulte Recursos do dispositivo na documentação da API REST.
deviceScope opcional O escopo do dispositivo. Em dispositivos de borda, gerados automaticamente e imutáveis. Preterido em dispositivos sem borda. No entanto, em dispositivos filho (folha), defina essa propriedade com o mesmo valor da propriedade parentScopes (o deviceScope do dispositivo pai) para compatibilidade com versões anteriores da API. Para obter mais informações, consulte IoT Edge como gateway: relações pai e filho.
parentScopes opcional O escopo do pai direto de um dispositivo filho (o valor da propriedade deviceScope do dispositivo pai). Em dispositivos de borda, o valor estará vazio se o dispositivo não tiver pai. Em dispositivos sem borda, a propriedade não estará presente se o dispositivo não tiver pai. Para obter mais informações, consulte IoT Edge como gateway: relações pai e filho.
status obrigatório Um indicador de acesso. Pode ser ativado ou desativado. Se Ativado, o dispositivo tem permissão para se conectar. Se Desativado, este dispositivo não pode acessar nenhum ponto de extremidade voltado para o dispositivo.
statusRazão opcional Uma cadeia de caracteres de 128 caracteres que armazena o motivo do status de identidade do dispositivo. Todos os caracteres UTF-8 são permitidos.
statusUpdateTime somente leitura Um indicador temporal, mostrando a data e a hora da última atualização de status.
connectionState somente leitura Um campo indicando o status da conexão: Conectado ou Desconectado. Este campo representa a vista do Hub IoT do estado da ligação do dispositivo. Importante: Este campo deve ser usado apenas para fins de desenvolvimento/depuração. O estado da conexão é atualizado somente para dispositivos que usam MQTT ou AMQP. Além disso, é baseado em pings de nível de protocolo (pings MQTT ou pings AMQP) e pode ter um atraso máximo de apenas 5 minutos. Por esses motivos, pode haver falsos positivos, como dispositivos desconectados relatados como conectados.
connectionStateUpdatedTime somente leitura Um indicador temporal, mostrando a data e a última vez que o estado da conexão foi atualizado.
lastActivityTime somente leitura Um indicador temporal, mostrando a data e a última vez que o dispositivo se conectou, recebeu ou enviou uma mensagem. Esta propriedade é eventualmente consistente, mas pode ser atrasada até 5 a 10 minutos. Por esse motivo, ele não deve ser usado em cenários de produção.

Nota

O estado da conexão só pode representar a exibição do Hub IoT do status da conexão. As atualizações para esse estado podem ser atrasadas, dependendo das condições e configurações da rede.

Nota

Atualmente, os SDKs de dispositivo não suportam o uso de + caracteres e # no deviceId.

Propriedades de identidade do módulo

As identidades de módulo são representadas como documentos JSON com as seguintes propriedades:

Property Opções Description
deviceId obrigatório, somente leitura em atualizações Uma cadeia de caracteres que diferencia maiúsculas de minúsculas (até 128 caracteres) de caracteres alfanuméricos ASCII de 7 bits mais certos caracteres especiais: - . + % _ # * ? ! ( ) , : = @ $ '.
moduleId obrigatório, somente leitura em atualizações Uma cadeia de caracteres que diferencia maiúsculas de minúsculas (até 128 caracteres) de caracteres alfanuméricos ASCII de 7 bits mais certos caracteres especiais: - . + % _ # * ? ! ( ) , : = @ $ '.
geraçãoId obrigatório, somente leitura Uma cadeia de caracteres gerada pelo hub IoT, sensível a maiúsculas e minúsculas, com até 128 caracteres. Esse valor é usado para distinguir dispositivos com o mesmo deviceId, quando eles foram excluídos e recriados.
etag obrigatório, somente leitura Uma cadeia de caracteres que representa um ETag fraco para a identidade do dispositivo, conforme RFC7232.
autenticação opcional Um objeto composto contendo informações de autenticação e materiais de segurança. Para obter mais informações, consulte Mecanismo de autenticação na documentação da API REST.
geridoPor opcional Identifica quem gerencia este módulo. Por exemplo, esse valor é "IoT Edge" se o tempo de execução da borda possuir esse módulo.
cloudToDeviceMessageCount somente leitura O número de mensagens de nuvem para módulo atualmente enfileiradas para serem enviadas ao módulo.
connectionState somente leitura Um campo indicando o status da conexão: Conectado ou Desconectado. Este campo representa a vista do Hub IoT do estado da ligação do dispositivo. Importante: Este campo deve ser usado apenas para fins de desenvolvimento/depuração. O estado da conexão é atualizado somente para dispositivos que usam MQTT ou AMQP. Além disso, é baseado em pings de nível de protocolo (pings MQTT ou pings AMQP) e pode ter um atraso máximo de apenas 5 minutos. Por esses motivos, pode haver falsos positivos, como dispositivos desconectados relatados como conectados.
connectionStateUpdatedTime somente leitura Um indicador temporal, mostrando a data e a última vez que o estado da conexão foi atualizado.
lastActivityTime somente leitura Um indicador temporal, mostrando a data e a última vez que o dispositivo se conectou, recebeu ou enviou uma mensagem.

Nota

Atualmente, os SDKs de dispositivo não suportam o uso dos + caracteres e # no deviceId e moduleId.

Material de referência adicional

Outros artigos de referência no guia do desenvolvedor do Hub IoT incluem:

  • Os pontos de extremidade do Hub IoT descrevem os vários pontos de extremidade que cada hub IoT expõe para operações de gerenciamento e tempo de execução.

  • Limitação e cotas descreve as cotas e comportamentos de limitação que se aplicam ao serviço Hub IoT.

  • Os SDKs de dispositivo e serviço do Azure IoT listam os vários SDKs de idioma que você pode usar ao desenvolver aplicativos de dispositivo e serviço que interagem com o Hub IoT.

  • A linguagem de consulta do Hub IoT descreve a linguagem de consulta que você pode usar para recuperar informações do Hub IoT sobre seus gêmeos de dispositivo e trabalhos.

  • O suporte MQTT do Hub IoT fornece mais informações sobre o suporte do Hub IoT para o protocolo MQTT.

Próximos passos

Agora que você aprendeu como usar o registro de identidade do Hub IoT, pode estar interessado nos seguintes artigos do guia do desenvolvedor do Hub IoT:

Para explorar o uso do Serviço de Provisionamento de Dispositivos do Hub IoT para habilitar o provisionamento zero-touch just-in-time, consulte: