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

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

os dispositivos duplos são documentos JSON que armazenam informações de estado dos dispositivos, incluindo metadados, configurações e condições. O Hub IoT persiste um gêmeo de dispositivo para cada dispositivo que se conecta a ele.

Nota

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

Use gêmeos de dispositivo para:

• Armazene metadados do dispositivo a partir do back-end da solução.

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

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

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

Os gêmeos de dispositivo são projetados para sincronização e para consultar configurações e condições do dispositivo. Para obter mais informações sobre gêmeos de dispositivo, incluindo quando usar gêmeos de dispositivo, consulte Compreender gêmeos de dispositivo.

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

• Etiquetas. Metadados do dispositivo acessíveis apenas pelo back-end da solução.

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

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

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

A ilustração a seguir mostra a organização de gêmeos do dispositivo:

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

Este artigo mostra-lhe como:

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

• Consultar dispositivos usando filtros nas tags e propriedades criadas anteriormente.

Para obter mais informações sobre como usar propriedades relatadas de gêmeos de dispositivo, consulte Diretrizes de comunicação entre dispositivos e 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 gêmeo de dispositivo correspondente do dispositivo quando inicializado.

• Uma sessão que atualiza as tags do dispositivo gêmeo para o dispositivo simulado e, em seguida, consulta dispositivos do seu hub IoT. As consultas usam filtros com base nas tags e propriedades previamente atualizadas em ambas as sessões.

Pré-requisitos

• CLI do Azure. Você também pode executar os comandos neste artigo usando o Azure Cloud Shell, um shell interativo da CLI que é executado em seu navegador ou em um aplicativo como o Terminal do Windows. Se você usa o Cloud Shell, não precisa instalar nada. Se você preferir usar a CLI localmente, este artigo requer a CLI do Azure versão 2.36 ou posterior. Executar az --version para localizar a versão. Para instalar ou atualizar localmente a CLI do Azure, consulte 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 neste artigo usam o protocolo MQTT, que se comunica pela porta 8883. Essa porta pode ser bloqueada em alguns ambientes de rede corporativa e educacional. Para obter mais informações e maneiras de contornar esse problema, consulte Conectando-se ao Hub IoT (MQTT).

Preparar o Cloud Shell

Se quiser usar o Azure Cloud Shell, você deve primeiro iniciá-lo e configurá-lo. Se você usar a CLI localmente, vá para a seção Preparar duas sessões da CLI.

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

   

   Nota

   Se esta for a primeira vez que você usa o Cloud Shell, ele solicita que você crie armazenamento, que é necessário para usar o Cloud Shell. Selecione uma subscrição para criar uma conta de armazenamento e a partilha de Ficheiros 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 Bash . Você também pode usar o ambiente do PowerShell .

   Nota

   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 de CLI

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

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

1. Se estiver a utilizar o Cloud Shell, avance para o passo seguinte. Caso contrário, execute o comando az login na primeira sessão da CLI para entrar na sua conta do Azure.

   Se estiver a utilizar o Cloud Shell, inicia sessão automaticamente na sua conta do Azure. Toda a comunicação entre sua sessão da CLI do Azure e seu hub IoT é autenticada e criptografada. Como resultado, este artigo não precisa de 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, consulte 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 para CLI do Azure ao shell da CLI. A extensão adiciona comandos específicos do Hub IoT, IoT Edge e DPS (Serviço de Provisionamento de Dispositivos IoT) à CLI do Azure. Depois de instalar a extensão, não é necessário instalá-la novamente em nenhuma sessão do Cloud Shell.

   az extension add --name azure-iot
   

   Nota

   Este artigo usa a versão mais recente da extensão do Azure IoT, chamada azure-iot. A versão herdada é chamada azure-cli-iot-extde . Você só deve ter uma versão instalada de cada vez. Você pode usar o comando az extension list para validar as extensões atualmente 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ê instalou, 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 sua 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 seu hub IoT na primeira sessão da CLI e, em seguida, simula um dispositivo usando essa identidade de 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 seguintes espaços reservados por seus valores correspondentes. Este comando cria a identidade do dispositivo para o dispositivo simulado.

   {NomedoDispositivo}. O nome do seu dispositivo simulado.

   {HubName}. O nome do 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 seguintes espaços reservados por seus valores correspondentes. Este 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 gêmeo de dispositivo correspondente do dispositivo quando inicializado.

   {NomedoDispositivo}. O nome do seu dispositivo simulado.

   {HubName}. O nome do seu hub IoT.

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

   Gorjeta

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

Atualizar o dispositivo twin

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

1. Confirme se o dispositivo simulado na primeira sessão da CLI 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 tags no gêmeo do dispositivo para a identidade do dispositivo que criamos na seção anterior.

   {NomedoDispositivo}. O nome do seu dispositivo.

   {HubName}. O nome do 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 exemplo de resposta JSON a seguir, usamos SampleDevice para o espaço reservado {DeviceName} no az iot hub device-twin update comando 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
     }
   }
   

Consultar seu hub IoT para gêmeos de dispositivo

O Hub IoT expõe os gêmeos de dispositivo para 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 gêmeos de dispositivo para seu hub IoT: a primeira consulta seleciona apenas os gêmeos de dispositivo de dispositivos localizados na planta Redmond43 e a segunda refina a consulta para selecionar apenas os dispositivos que também estão conectados por meio de uma rede celular. Ambas as consultas retornam apenas os primeiros 100 dispositivos no conjunto de resultados. Para obter mais informações sobre consultas gêmeas de dispositivo, consulte Consultas para dispositivo do Hub IoT e gêmeos de módulo.

1. Confirme se o dispositivo simulado na primeira sessão da CLI 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 retornar apenas os gêmeos de dispositivos localizados na planta Redmond43 .

   {HubName}. O nome do 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 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 gêmeos de dispositivos localizados na planta Redmond43 que também estão conectados por meio de uma rede celular.

   {HubName}. O nome do 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 JSON mostra os resultados da consulta. Os resultados desta consulta devem corresponder aos resultados da consulta anterior nesta secção.

Neste artigo, irá:

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

Próximos passos

Para saber como:

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

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

• Controle dispositivos interativamente, como ligar um ventilador de um aplicativo controlado pelo usuário, consulte Guia de início rápido: controlar um dispositivo conectado a um hub IoT.