Compartilhar via

Entender o registro de identidade no Hub IoT

  • Artigo

Cada Hub IoT tem um registro de identidade que armazena informações sobre os dispositivos e módulos com permissão para se conectar a esse Hub IoT. Antes de um dispositivo ou módulo poder se conectar a um Hub IoT, deve existir uma entrada para esse dispositivo ou módulo no registro de identidade do Hub IoT. O dispositivo ou módulo autentica com o hub IoT com base em credenciais armazenadas no registro de identidade.

A identidade do dispositivo ou do módulo armazenada no registro de identidade diferencia maiúsculas de minúsculas.

O registro de identidade é uma coleção de recursos de identidade compatíveis com REST. Quando você adiciona uma entrada ao registro de identidade, o Hub IoT cria um conjunto de recursos por dispositivo, tal como a fila que contém mensagens em andamento da nuvem para o dispositivo.

Use o registro de identidade para:

  • Provisionar dispositivos ou módulos que se conectam ao Hub IoT.
  • Controlar o acesso por dispositivo/por módulo aos pontos de extremidade do hub.

Operações de registro de identidade

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

  • Criar a identidade
  • Atualizar a identidade
  • Recuperar identidade por ID
  • Excluir identidade
  • Listar até 1000 identidades
  • Exportar as identidades para o Armazenamento de Blobs do Azure
  • Importar identidades do Armazenamento de Blobs do Azure

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

Um registro de identidade do Hub IoT não contém metadados de aplicativo.

Importante

Você deve usar o registro de identidade apenas para operações de provisionamento e gerenciamento de dispositivos. As operações de alta produtividade no tempo de execução não devem depender da execução de operações no registro de identidade. Por exemplo, verificar o estado da conexão de um dispositivo antes de enviar um comando não é um padrão permitido. Lembre-se de verificar as taxas de limitação do registro de identidade.

Observação

Pode levar alguns segundos para a identidade de um dispositivo ou de um módulo estar disponível para ser recuperada após a criação. Tente de novo a operação getdas identidades do dispositivo ou do módulo em caso de falhas.

Desabilitar dispositivos

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

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

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

    Importante

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

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

Para saber mais, confira Desabilitar ou excluir um dispositivo em um hub IoT.

Importar e exportar identidades de dispositivo

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

Use operações assíncronas no ponto de extremidade de provedor de recursos do Hub IoT para importar ou exportar identidades de dispositivos em massa do registro de identidade de um Hub IoT. Importações e exportações são trabalhos de longa execução que usam um contêiner de blob fornecido pelo cliente.

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

As identidades dos dispositivos 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 de dispositivo que uma determinada solução IoT armazena dependem dos requisitos específicos dessa solução. Porém, no mínimo, uma solução deve armazenar identidades e chaves de autenticação. O registro de identidade do Hub IoT 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 o Armazenamento de Tabelas, o Armazenamento de Blobs ou o Azure Cosmos DB, para armazenar outros dados de dispositivo.

Provisionamento de dispositivos é o processo de adição dos dados iniciais do dispositivo para as lojas em sua solução. Para permitir que um dispositivo se conecte ao hub, adicione uma ID e chaves de dispositivo 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 da solução. Você também pode usar o Serviço de Provisionamento de Dispositivos no Hub IoT do Azure para habilitar o provisionamento zero-touch e just-in-time para um ou mais hubs IoT. Para obter mais informações, consulte a Documentação do serviço de provisionamento de dispositivos.

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

O Hub IoT pode notificar sua solução de IoT quando uma identidade de dispositivo é criada ou excluída, enviando notificações do ciclo de vida. Para fazer isso, sua solução de IoT precisa para criar uma rota e definir a fonte de dados como DeviceLifecycleEvents. Por padrão, nenhuma notificação de ciclo de vida é enviada, ou seja, nenhuma dessas rotas existe previamente. Ao criar uma rota com a fonte de dados igual a DeviceLifecycleEvents, os eventos de 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 não telemétricos.

As notificações para 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ó será enviada se o dispositivo IoT Edge correspondente estiver em execução. Para todos os outros módulos, as notificações de 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 do dispositivo são representadas como documentos JSON com as seguintes propriedades:

Propriedade Opções Descrição
deviceId obrigatória, somente leitura em atualizações Uma cadeia de caracteres que diferencia maiúsculas de minúsculas (com até 128 caracteres) de caracteres alfanuméricos ASCII de 7 bits, mais determinados caracteres especiais: - . % _ * ? ! ( ) , : = @ $ '. Não há suporte para os caracteres especiais + #.
generationId obrigatória, somente leitura Uma cadeia de caracteres que diferencia maiúsculas de minúsculas com até 128 caracteres gerada pelo Hub IoT. Esse valor é usado para distinguir os dispositivos com a mesma deviceId quando são excluídos e recriados.
etag obrigatória, somente leitura Uma cadeia de caracteres que representa uma ETag fraca para a identidade do dispositivo, de acordo com o RFC7232.
autenticação opcionais Um objeto composto que contém as informações de autenticação e os materiais de segurança. Para obter mais informações, consulte Mecanismo de Autenticação na documentação da API REST.
funcionalidades opcionais O conjunto de recursos do dispositivo. Por exemplo, se o dispositivo é um dispositivo de borda ou não. Para obter mais informações, consulte as Funcionalidades do Dispositivo na documentação da API REST.
deviceScope opcionais O escopo do dispositivo. Nos 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 um gateway: relações pai e filho.
parentScopes opcionais O escopo do pai direto de um dispositivo filho (o valor da propriedade deviceScope do dispositivo pai). Em dispositivos de borda, o valor está vazio se o dispositivo não tiver um pai. Em dispositivos sem borda, a propriedade não está presente se o dispositivo não tiver um pai. Para obter mais informações, consulte IoT Edge como um gateway: relações pai e filho.
status exigido Um indicador de acesso. Pode ser Enabled ou Disabled. Se estiver Enabled, o dispositivo terá permissão para se conectar. Se estiver Disabled, o dispositivo não poderá acessar nenhum ponto de extremidade voltado para o dispositivo.
statusReason opcionais Uma cadeia de caracteres com 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 hora da última atualização de status.
connectionState somente leitura Um campo que indica o status da conexão: Connected ou Disconnected. Esse campo representa a exibição do Hub IoT do status de conexão do dispositivo. Importante: esse campo deve ser usado somente para fins de desenvolvimento/depuração. O estado da conexão é atualizado somente nos dispositivos que usam MQTT ou AMQP. Além disso, ele se baseia nos pings do nível de protocolo (pings MQTT ou AMQP) e pode ter um atraso máximo de apenas cinco 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 hora da última atualização do estado da conexão.
lastActivityTime somente leitura Um indicador temporal, mostrando a data e hora da última vez em que o dispositivo se conectou, recebeu ou enviou uma mensagem. Essa propriedade ficará consistente eventualmente, mas poderá ser atrasada entre 5 a 10 minutos. Por esse motivo, ele não deverá ser usado em cenários de produção.

Observação

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

Propriedades de identidade do módulo

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

Propriedade Opções Descrição
deviceId obrigatória, somente leitura em atualizações Uma cadeia de caracteres que diferencia maiúsculas de minúsculas (com até 128 caracteres) de caracteres alfanuméricos ASCII de 7 bits, mais determinados caracteres especiais: - . % _ * ? ! ( ) , : = @ $ '.
moduleId obrigatória, somente leitura em atualizações Uma cadeia de caracteres que diferencia maiúsculas de minúsculas (com até 128 caracteres) de caracteres alfanuméricos ASCII de 7 bits, mais determinados caracteres especiais: - . % _ * ? ! ( ) , : = @ $ '. Não há suporte para os caracteres especiais + #.
generationId obrigatória, somente leitura Uma cadeia de caracteres que diferencia maiúsculas de minúsculas com até 128 caracteres gerada pelo Hub IoT. Esse valor é usado para distinguir os dispositivos com a mesma deviceId quando são excluídos e recriados.
etag obrigatória, somente leitura Uma cadeia de caracteres que representa uma ETag fraca para a identidade do dispositivo, de acordo com o RFC7232.
autenticação opcionais Um objeto composto que contém as informações de autenticação e os materiais de segurança. Para obter mais informações, consulte Mecanismo de Autenticação na documentação da API REST.
managedBy opcionais Identifica quem gerencia este módulo. Por exemplo, esse valor será IoT Edge se o runtime do Edge possuir este módulo.
cloudToDeviceMessageCount somente leitura O número de mensagens da nuvem para o módulo atualmente na fila a serem enviadas para o módulo.
connectionState somente leitura Um campo que indica o status da conexão: Connected ou Disconnected. Esse campo representa a exibição do Hub IoT do status de conexão do dispositivo. Importante: esse campo deve ser usado somente para fins de desenvolvimento/depuração. O estado da conexão é atualizado somente nos dispositivos que usam MQTT ou AMQP. Além disso, ele se baseia nos pings do nível de protocolo (pings MQTT ou AMQP) e pode ter um atraso máximo de apenas cinco 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 hora da última atualização do estado da conexão.
lastActivityTime somente leitura Um indicador temporal, mostrando a data e hora da última vez em que o dispositivo se conectou, recebeu ou enviou uma mensagem.

Conteúdo relacionado

Para explorar usando o Serviço de Provisionamento de Dispositivos do Hub IoT para habilitar o provisionamento sem toque e Just-In-Time, consulte: