Introdução aos dispositivos gêmeos (CLI do Azure)

• CLI
• .NET
• Python
• Node.js
• Java

Dispositivos gêmeos são documentos JSON que armazenam informações do estado do dispositivo, incluindo metadados, configurações e condições. O Hub IoT persiste um dispositivo gêmeo para cada dispositivo que você conecta a ele.

Observação

Os recursos descritos neste artigo estão disponíveis apenas na camada padrão do Hub IoT. Para obter mais informações sobre as camadas básica e padrão/gratuita do Hub IoT, confira Escolher a camada certa do Hub IoT para a sua solução.

Use os dispositivos gêmeos para:

• Armazene os metadados de dispositivo de seu back-end da solução.

• Relate informações de estado atual, como funcionalidades disponíveis e condições (por exemplo, o método conectividade usado) do aplicativo do dispositivo.

• Sincronize o estado dos fluxos de trabalho de longa duração (como atualizações de firmware e de configuração) entre um aplicativo de dispositivo e um aplicativo de back-end.

• Consultar os metadados, a configuração ou o estado do seu dispositivo.

Dispositivos gêmeos são projetados para sincronização e para consultar condições e configurações de dispositivos. Para obter mais informações sobre dispositivos gêmeos e quando usá-los, confira Noções básicas sobre dispositivos gêmeos.

Os hubs IoT armazenam dispositivos gêmeos, que contêm os seguintes elementos:

• Marcas. Metadados do dispositivo acessíveis apenas por meio do back-end da solução.

• Propriedades desejadas. Objetos JSON modificáveis pelo back-end da solução e observáveis pelo aplicativo de dispositivo.

• Propriedades reportadas. Objetos JSON modificáveis pelo aplicativo de dispositivo e legíveis pelo back-end da solução.

Marcas e propriedades não podem conter matrizes, mas podem conter objetos aninhados.

A ilustração a seguir mostra a organização de um dispositivo gêmeo:

Além disso, o back-end da solução pode consultar dispositivos gêmeos com base em todos os dados acima. Para obter mais informações sobre dispositivos gêmeos, consulte Noções básicas de dispositivos gêmeos. Para obter mais informações sobre a consulta, consulte Linguagem de consulta do Hub IoT.

Este artigo mostra como:

• Use um dispositivo simulado para relatar seu canal de conectividade como uma propriedade relatada no dispositivo gêmeo.

• Dispositivos de consulta usando filtros nas marcas e propriedades criadas anteriormente.

Para mais informações sobre o uso das propriedades relatadas do dispositivo gêmeo, consulte Diretrizes de comunicação do dispositivo para nuvem.

Este artigo mostra como criar duas sessões da CLI do Azure:

• Uma sessão que cria um dispositivo simulado. O dispositivo simulado relata seu canal de conectividade como uma propriedade relatada no dispositivo gêmeo correspondente do dispositivo quando inicializado.

• Uma sessão que atualiza as marcas do dispositivo gêmeo para o dispositivo simulado e, em seguida, consulta dispositivos do seu Hub IoT. As consultas utilizam filtros baseados nas marcas e propriedades previamente atualizadas em ambas as sessões.

Pré-requisitos

• CLI do Azure. Você também pode executar os comandos deste artigo usando o Azure Cloud Shell, um shell da CLI interativa executado em seu navegador ou em um aplicativo, como Terminal do Windows. Se você usar o Cloud Shell, não precisará instalar nada. Se preferir usar a CLI localmente, este artigo requer a CLI do Azure versão 2.36 ou posterior. Execute az --version para encontrar a versão. Para instalar ou atualizar a CLI do Azure localmente, confira Instalar a CLI do Azure.

• Um hub IoT. Crie um com a CLI ou o portal do Azure.

• Verifique se a porta 8883 está aberta no firewall. Os exemplos desse artigo usam o protocolo MQTT que se comunica pela porta 8883. Essa porta poderá ser bloqueada em alguns ambientes de rede corporativos e educacionais. Para obter mais informações e maneiras de resolver esse problema, confira Como se conectar ao Hub IoT (MQTT).

Preparar o Cloud Shell

Se você quiser usar o Cloud Shell do Azure, primeiro inicie-o e configure-o. Se você usar a CLI localmente, pule para a seção Preparar duas sessões da CLI.

1. Selecione o ícone Cloud Shell no cabeçalho da página no portal do Azure.

   

   Observação

   Se esta for a primeira vez que você usa o Cloud Shell, ele solicitará que você crie o armazenamento, que é necessário para usar o Cloud Shell. Selecione uma assinatura para criar uma conta de armazenamento e um compartilhamento de Arquivos do Microsoft Azure.

2. Use o seletor de ambiente na barra de ferramentas do Cloud Shell para selecionar seu ambiente de CLI preferido. Este artigo usa o ambiente de Bash. Você também pode usar o ambiente do PowerShell.

   Observação

   Alguns comandos exigem sintaxe ou formatação diferentes nos ambientes Bash e PowerShell. Para obter mais informações, consulte Dicas para usar a CLI do Azure com êxito.

   

Preparar duas sessões da CLI

Em seguida, você precisa preparar duas sessões da CLI do Azure. Se estiver usando o Cloud Shell, você executará essas sessões em guias separadas do Cloud Shell. Se estiver usando um cliente CLI local, executará instâncias separadas da CLI. Use as sessões separadas da CLI para as seguintes tarefas:

• A primeira sessão simula um dispositivo IoT que se comunica com o hub IoT.
• A segunda sessão atualiza seu dispositivo simulado e consulta seu Hub IoT.

1. Se você estiver usando o Cloud Shell, pule para a próxima etapa. Caso contrário, execute o comando az login na primeira sessão da CLI para entrar na sua conta do Azure.

   Se você estiver usando o Cloud Shell, será conectado automaticamente à sua conta do Azure. Toda a comunicação entre a sessão da CLI do Azure e do Hub IoT é autenticada e criptografada. Como resultado, este artigo não precisa da autenticação extra que você usaria com um dispositivo real, como uma cadeia de conexão. Para obter mais informações sobre como entrar com a CLI do Azure, confira Entrar com a CLI do Azure.

   az login
   

2. Na primeira sessão da CLI, execute o comando az extension add. O comando adiciona a extensão IoT do Microsoft Azure da CLI do Azure ao shell da CLI. A Extensão de IoT adiciona comandos específicos do Hub IoT, do IoT Edge e do DPS (Serviço de Provisionamento de Dispositivos no Hub IoT) à CLI do Azure. Depois de instalar a extensão, você não precisará instalá-la novamente em nenhuma sessão do Cloud Shell.

   az extension add --name azure-iot
   

   Observação

   Este artigo usa a versão mais recente da extensão de IoT do Azure, chamada azure-iot. A versão herdada chama-se azure-cli-iot-ext. Você deve ter apenas uma versão instalada por vez. Use o comando az extension list para validar quais extensões estão instaladas.

   Use az extension remove --name azure-cli-iot-ext para remover a versão herdada da extensão.

   Use az extension add --name azure-iot para adicionar a nova versão da extensão.

   Para ver quais extensões você tem instaladas, use az extension list.

3. Abra a segunda sessão da CLI. Se você estiver usando o Cloud Shell em um navegador, selecione o ícone Abrir nova sessão na barra de ferramentas da primeira sessão da CLI. Se estiver usando a CLI localmente, abra uma segunda instância da CLI.

   

Criar e simular um dispositivo

Nesta seção, você cria uma identidade de dispositivo para o hub IoT na primeira sessão da CLI e simula um dispositivo usando essa identidade do dispositivo. O dispositivo simulado responde aos trabalhos agendados na segunda sessão da CLI.

Para criar e iniciar um dispositivo simulado:

1. Na primeira sessão da CLI, execute o comando az iot hub device-identity create, substituindo os espaços reservados a seguir por seus valores correspondentes. Esse comando cria a identidade do dispositivo para o dispositivo simulado.

   {DeviceName}. O nome do dispositivo simulado.

   {HubName}. O nome de seu hub IoT.

   az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName} 
   

2. Na primeira sessão da CLI, execute o comando az iot device simulate, substituindo os espaços reservados a seguir por seus valores correspondentes. Esse comando simula o dispositivo que você criou na etapa anterior. O comando também configura o dispositivo simulado para relatar seu canal de conectividade como uma propriedade relatada no dispositivo gêmeo correspondente do dispositivo quando inicializado.

   {DeviceName}. O nome do dispositivo simulado.

   {HubName}. O nome de seu hub IoT.

   az iot device simulate --device-id {DeviceName} --hub-name {HubName} \
                          --init-reported-properties '{"connectivity":{"type": "cellular"}}'
   

   Dica

   Por padrão, o comando az iot device simulate envia 100 mensagens de dispositivo para nuvem com um intervalo de 3 segundos entre mensagens. A simulação termina depois que todas as mensagens são enviadas. Se quiser que a simulação seja executada por mais tempo, você poderá usar o parâmetro --msg-count para especificar mais mensagens ou o parâmetro --msg-interval para especificar um intervalo mais longo entre as mensagens. Você também pode executar o comando novamente para reiniciar o dispositivo simulado.

Atualize o dispositivo gêmeo

Uma vez que uma identidade do dispositivo é criada, um dispositivo gêmeo é implicitamente criado no Hub IoT. Nesta seção, você usa a segunda sessão da CLI para atualizar um conjunto de marcas no dispositivo gêmeo associado à identidade do dispositivo criado na seção anterior. Você pode usar as marcas do dispositivo gêmeo para organizar e gerenciar os dispositivos nas suas soluções de IoT. Para obter mais informações sobre como gerenciar dispositivos usando marcas, consulte Como gerenciar dispositivos usando marcas de dispositivos gêmeos no Hub IoT do Azure.

1. Confirme se o dispositivo simulado está em execução. Caso contrário, reinicie-o executando o comando az iot device simulate novamente em Criar e simular um dispositivo.

2. Na segunda sessão da CLI, execute o comando az iot hub device-twin update, substituindo os seguintes espaços reservados por seus valores correspondentes. Neste exemplo, estamos atualizando várias marcas no dispositivo gêmeo para a identidade do dispositivo que criamos na seção anterior.

   {DeviceName}. O nome do seu dispositivo.

   {HubName}. O nome de seu hub IoT.

   az iot hub device-twin update --device-id {DeviceName} --hub-name {HubName} \
                                 --tags '{"location":{"region":"US","plant":"Redmond43"}}'
   

3. Na segunda sessão da CLI, confirme se a resposta JSON mostra os resultados da operação de atualização. No seguinte exemplo de resposta do JSON, usamos SampleDevice para o espaço reservado {DeviceName} no comando az iot hub device-twin update da CLI.

   {
     "authenticationType": "sas",
     "capabilities": {
       "iotEdge": false
     },
     "cloudToDeviceMessageCount": 0,
     "connectionState": "Connected",
     "deviceEtag": "MTA2NTU1MDM2Mw==",
     "deviceId": "SampleDevice",
     "deviceScope": null,
     "etag": "AAAAAAAAAAI=",
     "lastActivityTime": "0001-01-01T00:00:00+00:00",
     "modelId": "",
     "moduleId": null,
     "parentScopes": null,
     "properties": {
       "desired": {
         "$metadata": {
           "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
         },
         "$version": 1
       },
       "reported": {
         "$metadata": {
           "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
           "connectivity": {
             "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
             "type": {
               "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
             }
           }
         },
         "$version": 2,
         "connectivity": {
           "type": "cellular"
         }
       }
     },
     "status": "enabled",
     "statusReason": null,
     "statusUpdateTime": "0001-01-01T00:00:00+00:00",
     "tags": {
       "location": {
         "plant": "Redmond43",
         "region": "US"
       }
     },
     "version": 4,
     "x509Thumbprint": {
       "primaryThumbprint": null,
       "secondaryThumbprint": null
     }
   }
   

Consulte seu Hub IoT para dispositivos gêmeos

O Hub IoT expõe os dispositivos gêmeos do seu Hub IoT como uma coleção de documentos chamada dispositivos. Nesta seção, você usa a segunda sessão da CLI para executar duas consultas no conjunto de dispositivos gêmeos para seu Hub IoT: a primeira consulta seleciona apenas os dispositivos gêmeos dos dispositivos localizados na planta Redmond43 e a segunda refina a consulta para selecionar apenas os dispositivos que também estão conectados de dispositivos gêmeos. Ambas as consultas retornam somente os primeiros 100 dispositivos no conjunto de resultados. Para mais informações sobre consultas de dispositivos gêmeos, consulte Consultas para dispositivos e módulos gêmeos do Hub IoT.

1. Confirme se o dispositivo simulado está em execução. Caso contrário, reinicie-o executando o comando az iot device simulate novamente em Criar e simular um dispositivo.

2. Na segunda sessão da CLI, execute o comando az iot hub query, substituindo os seguintes espaços reservados por seus valores correspondentes. Neste exemplo, estamos filtrando a consulta para somente os dispositivos gêmeos de dispositivos localizados na planta Redmond43.

   {HubName}. O nome de seu hub IoT.

   az iot hub query --hub-name {HubName} \
                    --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'" \
                    --top 100
   

3. Na segunda sessão da CLI, confirme se a resposta do JSON mostra os resultados da consulta.

   {
     "authenticationType": "sas",
     "capabilities": {
       "iotEdge": false
     },
     "cloudToDeviceMessageCount": 0,
     "connectionState": "Connected",
     "deviceEtag": "MTA2NTU1MDM2Mw==",
     "deviceId": "SampleDevice",
     "deviceScope": null,
     "etag": "AAAAAAAAAAI=",
     "lastActivityTime": "0001-01-01T00:00:00+00:00",
     "modelId": "",
     "moduleId": null,
     "parentScopes": null,
     "properties": {
       "desired": {
         "$metadata": {
           "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
         },
         "$version": 1
       },
       "reported": {
         "$metadata": {
           "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
           "connectivity": {
             "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
             "type": {
               "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
             }
           }
         },
         "$version": 2,
         "connectivity": {
           "type": "cellular"
         }
       }
     },
     "status": "enabled",
     "statusReason": null,
     "statusUpdateTime": "0001-01-01T00:00:00+00:00",
     "tags": {
       "location": {
         "plant": "Redmond43",
         "region": "US"
       }
     },
     "version": 4,
     "x509Thumbprint": {
       "primaryThumbprint": null,
       "secondaryThumbprint": null
     }
   }
   

4. Na segunda sessão da CLI, execute o comando az iot hub query, substituindo os seguintes espaços reservados por seus valores correspondentes. Neste exemplo, estamos filtrando a consulta para retornar apenas os dispositivos gêmeos localizados na planta Redmond43 que também estão conectados através de uma rede celular.

   {HubName}. O nome de seu hub IoT.

   az iot hub query --hub-name {HubName} \
                    --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' \
                                     AND properties.reported.connectivity.type = 'cellular'" \
                    --top 100
   

5. Na segunda sessão da CLI, confirme se a resposta do JSON mostra os resultados da consulta. Os resultados desta consulta devem corresponder aos resultados da consulta anterior nesta seção.

Neste artigo você:

• Adição de metadados de dispositivos como marcas de uma sessão da CLI do Azure
• Simulou um dispositivo que relatou as informações de conectividade do dispositivo no dispositivo gêmeo
• Consultou as informações sobre o dispositivo gêmeo, usando uma linguagem de consulta do Hub IoT semelhante a SQL em uma sessão da CLI do Azure

Próximas etapas

Para saber como:

• Enviar telemetria de dispositivos, consulte Início Rápido: enviar telemetria de um dispositivo IoT Plug and Play para o Hub IoT do Azure.

• Configurar dispositivos usando as propriedades desejadas do dispositivo gêmeo, consulte Tutorial: Configurar seus dispositivos de um serviço de back-end.

• Controlar dispositivos interativamente, como ativar um ventilador de um aplicativo controlado pelo usuário, consulte Início Rápido: controlar um dispositivo conectado a um hub IoT.