Compreender o registo de identidades no seu hub IoT

  • Artigo

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

O ID do dispositivo ou módulo armazenado no registo de identidade é sensível a maiúsculas e minúsculas.

A um nível elevado, o registo de identidade é uma coleção com capacidade REST de recursos de identidade de dispositivos ou módulos. Quando adiciona uma entrada no registo de identidade, Hub IoT cria um conjunto de recursos por dispositivo, como a fila que contém mensagens da cloud para o dispositivo a bordo.

Utilize o registo de identidade quando precisar de:

  • Aprovisionar dispositivos ou módulos que se ligam ao seu hub IoT.
  • Controlar o acesso por dispositivo/por módulo ao dispositivo do hub ou aos pontos finais com acesso a módulos.

Operações de registo de identidade

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

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

Todas estas operações podem utilizar simultaneidade otimista, conforme especificado em RFC7232.

Importante

A única forma de obter todas as identidades no registo de identidades de um hub IoT é utilizar a funcionalidade Exportar .

Um registo de identidade Hub IoT:

  • Não contém metadados da aplicação.

Importante

Utilize apenas o registo de identidade para operações de gestão e aprovisionamento de dispositivos. As operações de débito elevado no tempo de execução não devem depender da realização de operações no registo de identidade. Por exemplo, verificar o estado de ligação de um dispositivo antes de enviar um comando não é um padrão suportado. Certifique-se de que verifica as taxas de limitação do registo de identidade.

Nota

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

Desativar dispositivos

Pode desativar os dispositivos ao atualizar a propriedade de estado de uma identidade no registo de identidade. Normalmente, utiliza esta propriedade em dois cenários:

  • Durante um processo de orquestração de aprovisionamento. Para obter mais informações, veja Aprovisionamento de Dispositivos.

  • Se pensa que um dispositivo está comprometido ou ficou não autorizado por qualquer motivo.

    Importante

    Hub IoT não verifica as listas de revogação de certificados ao autenticar dispositivos com autenticação baseada em certificados. Se tiver um dispositivo que precisa de ser impedido de ligar ao Hub IoT devido a um certificado potencialmente comprometido, deve desativar o dispositivo no registo de identidade.

Esta funcionalidade não está disponível para módulos.

Para obter mais informações, veja Desativar ou eliminar um dispositivo num hub IoT.

Importar e exportar identidades de dispositivos

Utilize operações assíncronas no ponto final do fornecedor de recursos Hub IoT para exportar identidades de dispositivos em massa a partir do registo de identidades de um hub IoT. As exportações são tarefas de execução prolongada que utilizam um contentor de blobs fornecido pelo cliente para guardar os dados de identidade do dispositivo lidos a partir do registo de identidade.

Utilize operações assíncronas no ponto final do fornecedor de recursos Hub IoT para importar identidades de dispositivos em massa para o registo de identidades de um hub IoT. As importações são tarefas de execução prolongada que utilizam dados num contentor de blobs fornecido pelo cliente para escrever dados de identidade do dispositivo no registo de identidade.

Para obter mais informações sobre as APIs de importação e exportação, veja HUB IOT APIs REST do fornecedor de recursos. Para saber mais sobre como executar tarefas de importação e exportação, veja Gestão em massa de identidades de dispositivos Hub IoT.

As identidades dos dispositivos também podem ser exportadas e importadas a partir de um hub IoT através da API de Serviço através da API REST ou de um dos SDKs do Serviço Hub IoT.

Aprovisionamento 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 tem de armazenar identidades de dispositivos e chaves de autenticação. Hub IoT do Azure inclui um registo de identidade que pode armazenar valores para cada dispositivo, como IDs, chaves de autenticação e códigos de estado. Uma solução pode utilizar outros serviços do Azure, como o Armazenamento de tabelas, o Armazenamento de blobs ou o Azure Cosmos DB, para armazenar outros dados do dispositivo.

O aprovisionamento de dispositivos é o processo de adicionar os dados iniciais do dispositivo aos arquivos na sua solução. Para ativar um novo dispositivo para ligar ao hub, tem de adicionar um ID de dispositivo e chaves ao registo de identidade do Hub IoT. Como parte do processo de aprovisionamento, poderá ter de inicializar dados específicos do dispositivo noutros arquivos de soluções. Também pode utilizar o Hub IoT do Azure Serviço de Aprovisionamento de Dispositivos para ativar o aprovisionamento sem toque e just-in-time num ou mais hubs IoT sem necessidade de intervenção humana. Para saber mais, veja a documentação do serviço de aprovisionamento.

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

Hub IoT pode notificar a sua solução de IoT quando uma identidade do dispositivo é criada ou eliminada através do envio de notificações de ciclo de vida. Para tal, a sua solução de IoT tem de criar uma rota e definir a origem de dados igual a DeviceLifecycleEvents. Por predefinição, não são enviadas notificações de ciclo de vida, ou seja, não existem rotas deste tipo. Ao criar uma rota com a Origem de Dados igual a DeviceLifecycleEvents, são enviados eventos de ciclo de vida para identidades de dispositivos e identidades de módulos; no entanto, o conteúdo da mensagem difere consoante os eventos sejam gerados para identidades de módulo ou identidades de dispositivo. Tenha em atenção que, para IoT Edge módulos, o fluxo de criação de identidade do módulo é diferente do dos outros módulos, pelo que, para IoT Edge módulos, a notificação de criação só é enviada se o Dispositivo de IoT Edge correspondente para a identidade atualizada do módulo IoT Edge 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 Hub IoT. Para saber mais sobre as propriedades e o corpo devolvidos na mensagem de notificação, veja Esquemas de eventos não telemétricos.

Propriedades da identidade do dispositivo

As identidades dos dispositivos são representadas como documentos JSON com as seguintes propriedades:

Propriedade Opções Descrição
deviceId obrigatório, só de leitura em atualizações Uma cadeia sensível a maiúsculas e minúsculas (até 128 carateres) de carateres alfanuméricos ASCII de 7 bits e determinados carateres especiais: - . % _ * ? ! ( ) , : = @ $ '. Os carateres especiais: + # não são suportados.
generationId obrigatório, só de leitura Uma cadeia sensível às maiúsculas e minúsculas gerada pelo hub IoT com até 128 carateres. Este valor é utilizado para distinguir dispositivos com o mesmo deviceId, quando foram eliminados e recriados.
etag obrigatório, só de leitura Uma cadeia que representa uma ETag fraca para a identidade do dispositivo, de acordo com RFC7232.
autenticação opcional Um objeto composto que contém informações de autenticação e materiais de segurança. Para obter mais informações, veja Mecanismo de Autenticação na documentação da API REST.
capacidades opcional O conjunto de capacidades do dispositivo. Por exemplo, quer o dispositivo seja ou não um dispositivo edge. Para obter mais informações, veja Capacidades do Dispositivo na documentação da API REST.
deviceScope opcional O âmbito do dispositivo. Em dispositivos edge, gerados automaticamente e imutáveis. Preterido em dispositivos não edge. No entanto, em dispositivos subordinados (folha), defina esta propriedade para o mesmo valor que a propriedade parentScopes (o deviceScope do dispositivo principal) para retrocompatibilidade com versões anteriores da API. Para obter mais informações, veja IoT Edge como um gateway: Relações entre encarregados de educação e subordinados.
parentScopes opcional O âmbito do principal direto de um dispositivo subordinado (o valor da propriedade deviceScope do dispositivo principal). Nos dispositivos edge, o valor estará vazio se o dispositivo não tiver um elemento principal. Em dispositivos não edge, a propriedade não está presente se o dispositivo não tiver um elemento principal. Para obter mais informações, veja IoT Edge como um gateway: Relações entre encarregados de educação e subordinados.
status obrigatório Um indicador de acesso. Pode ser Ativado ou Desativado. Se ativado, o dispositivo tem permissão para se ligar. Se Estiver Desativado, este dispositivo não pode aceder a nenhum ponto final com acesso ao dispositivo.
statusReason opcional Uma cadeia de carateres com 128 carateres que armazena o motivo do estado da identidade do dispositivo. Todos os carateres UTF-8 são permitidos.
statusUpdateTime só de leitura Um indicador temporal a mostrar a data e hora da última atualização de estado.
connectionState só de leitura Um campo que indica o estado da ligação: Ligado ou Desligado. Este campo representa a vista Hub IoT do estado da ligação do dispositivo. Importante: este campo deve ser utilizado apenas para fins de desenvolvimento/depuração. O estado da ligação é atualizado apenas para dispositivos com MQTT ou AMQP. Além disso, baseia-se em pings ao nível do protocolo (pings MQTT ou pings AMQP) e pode ter um atraso máximo de apenas 5 minutos. Por estas razões, podem existir falsos positivos, como dispositivos desligados comunicados como ligados.
connectionStateUpdatedTime só de leitura Um indicador temporal a mostrar a data e a última vez que o estado da ligação foi atualizado.
lastActivityTime só de leitura Um indicador temporal a mostrar a data e a última vez que o dispositivo ligou, recebeu ou enviou uma mensagem. Esta propriedade é eventualmente consistente, mas pode ser adiada até 5 a 10 minutos. Por este motivo, não deve ser utilizado em cenários de produção.

Nota

O estado da ligação só pode representar a vista Hub IoT do estado da ligação. Atualizações para este estado podem ser adiadas, consoante as condições e configurações de rede.

Nota

Atualmente, os SDKs do dispositivo não suportam a utilização dos + carateres e # no deviceId.

Propriedades da identidade do módulo

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

Propriedade Opções Descrição
deviceId obrigatório, só de leitura em atualizações Uma cadeia sensível a maiúsculas e minúsculas (até 128 carateres) de carateres alfanuméricos ASCII de 7 bits e determinados carateres especiais: - . + % _ # * ? ! ( ) , : = @ $ '.
moduleId obrigatório, só de leitura em atualizações Uma cadeia sensível a maiúsculas e minúsculas (até 128 carateres) de carateres alfanuméricos ASCII de 7 bits e determinados carateres especiais: - . + % _ # * ? ! ( ) , : = @ $ '.
generationId obrigatório, só de leitura Uma cadeia sensível às maiúsculas e minúsculas gerada pelo hub IoT com até 128 carateres. Este valor é utilizado para distinguir dispositivos com o mesmo deviceId, quando foram eliminados e recriados.
etag obrigatório, só de leitura Uma cadeia que representa uma ETag fraca para a identidade do dispositivo, de acordo com RFC7232.
autenticação opcional Um objeto composto que contém informações de autenticação e materiais de segurança. Para obter mais informações, veja Mecanismo de Autenticação na documentação da API REST.
managedBy opcional Identifica quem gere este módulo. Por exemplo, este valor é "IoT Edge" se o runtime edge for proprietário deste módulo.
cloudToDeviceMessageCount só de leitura O número de mensagens da cloud para o módulo atualmente em fila para serem enviadas para o módulo.
connectionState só de leitura Um campo que indica o estado da ligação: Ligado ou Desligado. Este campo representa a vista Hub IoT do estado da ligação do dispositivo. Importante: este campo deve ser utilizado apenas para fins de desenvolvimento/depuração. O estado da ligação é atualizado apenas para dispositivos com MQTT ou AMQP. Além disso, baseia-se em pings ao nível do protocolo (pings MQTT ou pings AMQP) e pode ter um atraso máximo de apenas 5 minutos. Por estas razões, podem existir falsos positivos, como dispositivos desligados comunicados como ligados.
connectionStateUpdatedTime só de leitura Um indicador temporal a mostrar a data e a última vez que o estado da ligação foi atualizado.
lastActivityTime só de leitura Um indicador temporal a mostrar a data e a última vez que o dispositivo ligou, recebeu ou enviou uma mensagem.

Nota

Atualmente, os SDKs do dispositivo não suportam a utilização dos + carateres e # no deviceId e moduleId.

Material de referência adicional

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

Passos seguintes

Agora que aprendeu a utilizar o registo de identidades do Hub IoT, poderá estar interessado nos seguintes artigos Hub IoT guia para programadores:

Para explorar a utilização do Serviço de Aprovisionamento de Dispositivos Hub IoT para ativar o aprovisionamento just-in-time sem toque, veja: