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 ao 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 também deve realizar a autenticação no Hub IoT com base em credenciais armazenadas no registro de identidade.

A ID do dispositivo ou módulo armazenada 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 do dispositivo ou módulo. 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 quando você precisa:

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

Operações de registro de identidade

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

  • Criar identidade de dispositivo ou módulo
  • Atualizar identidade de dispositivo ou módulo
  • Recuperar identidade de dispositivo ou módulo por ID
  • Excluir identidade de 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 blobs do Azure

Todas essas operações podem usar a 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 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

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

Use operações assíncronas no ponto de extremidade de provedor de recursos do Hub IoT para importar identidades de dispositivos em massa para o registro de identidade de um Hub IoT. As exportações são trabalhos de execução longa que usam dados em um contêiner de blobs 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, 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 Hub IoT do Azure inclui um registro de identidades 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 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, você deve adicionar 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 sem toque e Just-In-Time para um ou mais hubs IoT sem a necessidade de intervenção humana. Para obter mais informações, consulte a documentação do serviço de provisionamento.

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 estar Habilitado ou Desabilitado. Se estiver Habilitado, o dispositivo terá permissão para se conectar. Se estiver Desabilitado, este dispositivo não poderá acessar qualquer 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 indicando o status da conexão: Conectado ou Desconectado. 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.

Observação

No momento, os SDKs do dispositivo não dão suporte ao uso dos caracteres + e # no deviceId.

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: - . + % _ # * ? ! ( ) , : = @ $ '.
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 possui 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 indicando o status da conexão: Conectado ou Desconectado. 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.

Observação

No momento, os SDKs do dispositivo não dão suporte ao uso dos caracteres + e # no deviceId e no moduleId.

Material de referência adicional

Outros tópicos do artigo no Guia do desenvolvedor do Hub IoT incluem:

Próximas etapas

Agora que você aprendeu a usar o Registro de identidade do Hub IoT, pode ser interessante ler os seguintes artigos do Guia do desenvolvedor do Hub IoT:

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