Compreenda o registo de identidade no seu hub IoT

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 poder ligar-se a um hub IoT, deve haver uma entrada para esse dispositivo ou módulo no registo de identidade do hub IoT. Um dispositivo ou módulo também deve autenticar com o hub IoT com base em credenciais armazenadas no registo de identidade.

O dispositivo ou iD do módulo armazenado no registo de identidade é sensível a casos.

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

Utilize o registo de identidade quando precisar:

  • Dispositivos ou módulos de fornecimento que se ligam ao seu hub IoT.
  • Controle o acesso por dispositivo/módulo ao dispositivo do seu hub ou pontos finais virados para o módulo.

Operações de registo de identidade

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

  • Criar identidade de dispositivo ou módulo
  • Atualizar identidade de dispositivo ou módulo
  • Recuperar identidade do dispositivo ou módulo por ID
  • Eliminar identidade de dispositivo ou módulo
  • Listar até 1000 identidades
  • Identidades do dispositivo de exportação para o armazenamento de bolhas Azure
  • Identidades do dispositivo de importação do armazenamento de bolhas Azure

Todas estas operações podem utilizar a concordância otimista, conforme especificado no RFC7232.

Importante

A única maneira de recuperar todas as identidades no registo de identidade de um hub IoT é usar a funcionalidade Exportação.

Um registo de identidade IoT Hub:

  • Não contém nenhum metadados de aplicação.

Importante

Utilize apenas o registo de identidade para operações de gestão e provisionamento de dispositivos. As operações de elevado rendimento 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 verificar as taxas de aceleração do registo de identidade e o padrão de batimentocardíaco do dispositivo.

Desativar dispositivos

Pode desativar os dispositivos atualizando a propriedade de estado de uma identidade no registo de identidade. Normalmente, você usa esta propriedade em dois cenários:

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

  • Se, por qualquer motivo, achar que um dispositivo está comprometido ou se não tiver sido autorizado.

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

Identidades dos dispositivos de importação e exportação

Utilize operações assíncronos no ponto final do fornecedor de recursos IoT Hub para exportar identidades de dispositivos a granel a partir do registo de identidade de um hub IoT. As exportações são empregos de longa duração que utilizam um recipiente de bolhas fornecido pelo cliente para guardar os dados de identidade do dispositivo lidos a partir do registo de identidade.

Utilize operações assíncronos no ponto final do fornecedor de recursos IoT Hub para importar identidades de dispositivos a granel para o registo de identidade de um hub IoT. As importações são empregos de longa duração que utilizam dados num recipiente de bolhas fornecidos 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, consulte o fornecedor de recursos IoT Hub REST APIs. Para saber mais sobre a gestão de postos de trabalho de importação e exportação, consulte a gestão a granel das identidades dos dispositivos IoT Hub.

As identidades do dispositivo também podem ser exportadas e importadas de um Hub IoT através da API de serviço através da API REST ou de um dos SDKs de serviço IoTHub .

Provisão de dispositivos

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

O fornecimento de dispositivos é o processo de adição dos dados iniciais do dispositivo às lojas na sua solução. Para permitir que um novo dispositivo se conecte ao seu hub, tem de adicionar um ID do dispositivo e chaves ao registo de identidade do IoT Hub. Como parte do processo de provisionamento, poderá ser necessário inicializar dados específicos do dispositivo noutras lojas de soluções. Também pode utilizar o Serviço de Provisionamento de Dispositivos Azure IoT Hub para permitir o fornecimento de zero toques, just-in-time, para um ou mais hubs IoT sem necessidade de intervenção humana. Para saber mais, consulte a documentação do serviço de fornecimento.

Batimento cardíaco do dispositivo

O registo de identidade IoT Hub contém um campo chamado connectionState. Utilize apenas o campo de ligaçãoEse durante o desenvolvimento e depuragem. As soluções IoT não devem consultar o campo no tempo de execução. Por exemplo, não consulte o campo de ligaçãoEve para verificar se um dispositivo está ligado antes de enviar uma mensagem nuvem-para-dispositivo ou um SMS. Recomendamos a subscrição do evento desligado do dispositivo na Grelha de Eventos para obter alertas e monitorizar o estado de ligação do dispositivo. Utilize este tutorial para aprender a integrar eventos ligados ao dispositivo conectados e desligados do dispositivo a partir do IoT Hub na sua solução IoT.

Se a sua solução IoT precisar de saber se um dispositivo está ligado, pode implementar o padrão de batimentocardíaco. No padrão de batimentos cardíacos, o dispositivo envia mensagens dispositivo-a-nuvem pelo menos uma vez a cada quantidade fixa de tempo (por exemplo, pelo menos uma vez a cada hora). Portanto, mesmo que um dispositivo não tenha quaisquer dados para enviar, ainda envia uma mensagem vazia de dispositivo para nuvem (geralmente com uma propriedade que o identifica como um batimento cardíaco). Do lado do serviço, a solução mantém um mapa com o último batimento cardíaco recebido para cada dispositivo. Se a solução não receber uma mensagem de batimento cardíaco dentro do tempo esperado do dispositivo, assume que existe um problema com o dispositivo.

Uma implementação mais complexa poderia incluir as informações do Azure Monitor e da Azure Resource Health para identificar dispositivos que estão a tentar ligar ou comunicar, mas falhando. Para saber mais, consulte o Monitor IoT Hub e verifique a saúde dos recursos do IoT Hub. Quando implementar o padrão de batimentos cardíacos, certifique-se de verificar IoT Hub Quotas e Throttles.

Nota

Se uma solução IoT utilizar o estado de ligação apenas para determinar se envia mensagens nuvem-para-dispositivo e as mensagens não são transmitidas para grandes conjuntos de dispositivos, considere usar o padrão de tempo de validade de curto prazo mais simples. Este padrão obtém o mesmo resultado que manter um registo estatal de ligação do dispositivo usando o padrão de batimentocardíaco, ao mesmo tempo que é mais eficiente. Se solicitar avisos de mensagens, o IoT Hub pode notificá-lo sobre quais os dispositivos que podem receber mensagens e quais não são.

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

O IoT Hub pode notificar a sua solução 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 IoT necessita de criar uma rota e de definir a Fonte de Dados igual à DeviceLifecycleEvents. Por padrão, não são enviadas notificações de ciclo de vida, ou seja, não existem tais rotas pré-existentes. Ao criar uma rota com Fonte de Dados igual a DeviceLifecycleEvents, serão enviados eventos de ciclo de vida tanto para identidades do dispositivo como para identidades de módulos; no entanto, o conteúdo da mensagem diferirá dependendo se os eventos são gerados para identidades de módulos ou identidades do dispositivo. Note-se que, para os módulos IoT Edge, o fluxo de criação de identidade do módulo é diferente do de outros módulos, como resultado dos módulos IoT Edge, a notificação de criação só é enviada se o dispositivo IoT Edge correspondente para a identidade do módulo IoT Edge atualizado 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 IoT Hub. A mensagem de notificação inclui propriedades e corpo.

Propriedades: As propriedades do sistema de mensagens estão prefixadas com o $ símbolo.

Mensagem de notificação para o dispositivo:

Name Valor
$content tipo application/json
$iothub-enquestime Hora em que a notificação foi enviada
$iothub-mensagem-fonte dispositivoLifecycleS
$content codificação utf-8
opType criarDeviceIdentity ou eliminarDeviceDentity
nome hub Nome do Hub IoT
deviceId ID do dispositivo
operaçãoTimestamp ISO8601 timetamp de funcionamento
iothub-mensagem-schema dispositivoLifecycleNotificação

Corpo: Esta secção está no formato JSON e representa o gémeo da identidade do dispositivo criado. Por exemplo,

{
    "deviceId":"11576-ailn-test-0-67333793211",
    "etag":"AAAAAAAAAAE=",
    "properties": {
        "desired": {
            "$metadata": {
                "$lastUpdated": "2016-02-30T16:24:48.789Z"
            },
            "$version": 1
        },
        "reported": {
            "$metadata": {
                "$lastUpdated": "2016-02-30T16:24:48.789Z"
            },
            "$version": 1
        }
    }
}

Mensagem de notificação para módulo:

Name Valor
$content tipo application/json
$iothub-enquestime Hora em que a notificação foi enviada
$iothub-mensagem-fonte móduloLifecycleEvents
$content codificação utf-8
opType criarModuleIdentity ou excluirModuleIdentity
nome hub Nome do Hub IoT
moduleId ID do módulo
operaçãoTimestamp ISO8601 timetamp de funcionamento
iothub-mensagem-schema móduloNotificação de Vida

Corpo: Esta secção está em formato JSON e representa o gémeo da identidade do módulo criado. Por exemplo,

{
    "deviceId":"11576-ailn-test-0-67333793211",
    "moduleId":"tempSensor",
    "etag":"AAAAAAAAAAE=",
    "properties": {
        "desired": {
            "$metadata": {
                "$lastUpdated": "2016-02-30T16:24:48.789Z"
            },
            "$version": 1
        },
        "reported": {
            "$metadata": {
                "$lastUpdated": "2016-02-30T16:24:48.789Z"
            },
            "$version": 1
        }
    }
}

Propriedades de identidade do dispositivo

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

Propriedade Opções Description
deviceId necessário, ler apenas sobre atualizações Uma corda sensível a casos (até 128 caracteres) de caracteres alfanuméricos ASCII de 7 bits, além de certos caracteres especiais: - . + % _ # * ? ! ( ) , : = @ $ ' .
geraçãoId necessário, apenas ler Uma corda ioT gerada por um hub, sensível a casos até 128 caracteres de comprimento. Este valor é utilizado para distinguir dispositivos com o mesmo dispositivoId, quando estes foram eliminados e recriados.
etag necessário, apenas ler Uma corda que representa um ETag fraco para a identidade do dispositivo, de acordo com o RFC7232.
autenticação opcional Um objeto composto contendo informações de autenticação e materiais de segurança. Para obter mais informações, consulte o 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 as capacidades do dispositivo na documentação DA API REST.
dispositivoOscópio opcional O âmbito do dispositivo. Em dispositivos de borda, gerados automaticamente e imutáveis. Precotado em dispositivos sem borda. No entanto, em dispositivos infantis (folhas), dedipulhe esta propriedade ao mesmo valor que a propriedade parentScopes (o dispositivoScope do dispositivo-mãe) para retrocompatibilidade com versões anteriores da API. Para mais informações, consulte ioT Edge como uma porta de entrada: Relacionamento entre pais e filhos.
parentScopes opcional O âmbito do progenitor direto de um dispositivo infantil (o valor da propriedade do dispositivoScope do dispositivo principal). Nos dispositivos de borda, o valor está vazio se o dispositivo não tiver pai. Em dispositivos sem borda, a propriedade não está presente se o dispositivo não tiver pai. Para mais informações, consulte ioT Edge como uma porta de entrada: Relacionamento entre pais e filhos.
status obrigatório Um indicador de acesso. Pode ser ativado ou desativado. Se ativado, o dispositivo pode ligar-se. Se estiver desativado, este dispositivo não pode aceder a nenhum ponto final virado para o dispositivo.
statusReason opcional Uma cadeia de 128 caracteres que armazena a razão para o estado de identidade do dispositivo. Todos os caracteres UTF-8 são permitidos.
statusUpdateTime read-only Um indicador temporal, mostrando a data e a hora da última atualização do estado.
ligação Estado read-only Um campo indicando o estado da ligação: ligado ou desligado. Este campo representa a visão do Hub IoT do estado de ligação do dispositivo. Importante: Este campo deve ser utilizado apenas para fins de desenvolvimento/depuragem. O estado de ligação é atualizado apenas para dispositivos que utilizem MQTT ou AMQP. Além disso, baseia-se em pings de nível de protocolo (pings MQTT, ou pings AMQP), e pode ter um atraso máximo de apenas 5 minutos. Por estas razões, pode haver falsos positivos, como dispositivos relatados como conectados, mas que estão desligados.
conexãoStateUpdatedTime read-only Um indicador temporal, mostrando a data e a última vez que o estado de ligação foi atualizado.
última Hora de Atividade read-only Um indicador temporal, mostrando 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 esta razão, não deve ser usado em cenários de produção.

Nota

O estado de ligação só pode representar a visão do Hub IoT do estado da ligação. As atualizações a este estado podem ser atrasadas, dependendo das condições e configurações da rede.

Nota

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

Propriedades de identidade do módulo

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

Propriedade Opções Description
deviceId necessário, ler apenas sobre atualizações Uma corda sensível a casos (até 128 caracteres) de caracteres alfanuméricos ASCII de 7 bits, além de certos caracteres especiais: - . + % _ # * ? ! ( ) , : = @ $ ' .
moduleId necessário, ler apenas sobre atualizações Uma corda sensível a casos (até 128 caracteres) de caracteres alfanuméricos ASCII de 7 bits, além de certos caracteres especiais: - . + % _ # * ? ! ( ) , : = @ $ ' .
geraçãoId necessário, apenas ler Uma corda ioT gerada por um hub, sensível a casos até 128 caracteres de comprimento. Este valor é utilizado para distinguir dispositivos com o mesmo dispositivoId, quando estes foram eliminados e recriados.
etag necessário, apenas ler Uma corda que representa um ETag fraco para a identidade do dispositivo, de acordo com o RFC7232.
autenticação opcional Um objeto composto contendo informações de autenticação e materiais de segurança. Para obter mais informações, consulte o Mecanismo de Autenticação na documentação DA API REST.
managedBy opcional Identifica quem gere este módulo. Por exemplo, este valor é "IotEdge" se o tempo de execução da borda for dono deste módulo.
cloudToDeviceMessageCount read-only O número de mensagens cloud-to-module atualmente em fila para ser enviado para o módulo.
ligação Estado read-only Um campo indicando o estado da ligação: ligado ou desligado. Este campo representa a visão do Hub IoT do estado de ligação do dispositivo. Importante: Este campo deve ser utilizado apenas para fins de desenvolvimento/depuragem. O estado de ligação é atualizado apenas para dispositivos que utilizem MQTT ou AMQP. Além disso, baseia-se em pings de nível de protocolo (pings MQTT, ou pings AMQP), e pode ter um atraso máximo de apenas 5 minutos. Por estas razões, pode haver falsos positivos, como dispositivos relatados como conectados, mas que estão desligados.
conexãoStateUpdatedTime read-only Um indicador temporal, mostrando a data e a última vez que o estado de ligação foi atualizado.
última Hora de Atividade read-only Um indicador temporal, mostrando a data e a última vez que o dispositivo ligou, recebeu ou enviou uma mensagem.

Nota

Atualmente, os SDKs do dispositivo não suportam utilizando o + e os caracteres no # dispositivoId e móduloId.

Material de referência adicional

Outros tópicos de referência no guia de desenvolvimento do IoT Hub incluem:

Passos seguintes

Agora que aprendeu a usar o registo de identidade do IoT Hub, poderá estar interessado nos seguintes tópicos de guia de desenvolvimento do IoT Hub:

Para experimentar alguns dos conceitos descritos neste artigo, consulte o seguinte tutorial IoT Hub:

Para explorar utilizando o serviço de provisionamento de dispositivos IoT Hub para permitir o fornecimento de zero toques, just-in-time, consulte: