Início Rápido: enviar telemetria de um dispositivo para um Hub IoT e monitorá-lo com a CLI do Azure

Artigo
06/01/2023

O Hub IoT é um serviço do Azure que permite a ingestão de grandes volumes de telemetria de seus dispositivos IoT pela nuvem para processamento ou armazenamento. Neste início rápido sem código, você usará a CLI do Azure para criar um hub IoT e um dispositivo simulado. Você enviará a telemetria do dispositivo para o hub e enviará mensagens, métodos de chamada e atualizará as propriedades no dispositivo. Você também usará o portal do Azure para visualizar métricas do dispositivo. Esse artigo mostra um fluxo de trabalho básico para desenvolvedores que usam a CLI para interagir com um aplicativo de Hub IoT.

Pré-requisitos

Se você não tiver uma assinatura do Azure, crie uma gratuitamente antes de começar.
CLI do Azure. Você pode executar todos os comandos deste início rápido 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 você preferir usar a CLI localmente, este início rápido exige a CLI do Azure versão 2.36 ou posterior. Execute az --version para encontrar a versão. Para instalar ou atualizar, confira Instalar a CLI do Azure.

Entre no portal do Azure.

Independentemente de você executar a CLI localmente ou no Cloud Shell, mantenha o portal aberto no navegador. Você o usará posteriormente neste guia de início rápido.

Iniciar o Cloud Shell

Nesta seção, você inicia uma instância do Azure Cloud Shell. Se você usar a CLI localmente, pule para a seção Preparar duas sessões da CLI.

Para iniciar o Cloud Shell:

Clique no botão Cloud Shell na barra de menus no canto superior direito do 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.
Selecione o ambiente da CLI preferencial no menu suspenso Selecionar ambiente. Este guia de início rápido 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ê prepara 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 monitora o dispositivo na primeira sessão ou envia mensagens, comandos e atualizações de propriedade.

Para executar um comando, selecione Copiar para copiar um bloco de código neste guia de início rápido, cole-o na sessão do shell e execute-o.

A CLI do Azure exige que você esteja conectado à sua conta do Azure. Toda a comunicação entre a sessão shell da CLI do Azure e o Hub IoT é autenticada e criptografada. Como resultado, este início rápido não precisa da autenticação extra que você usaria com um dispositivo real, como uma cadeia de conexão.

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 IoT) à CLI do Azure.
```
az extension add --name azure-iot
```
Depois de instalar a extensão de IOT do Azure, você não precisará instalá-la novamente em nenhuma sessão do Cloud Shell.

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.
Abra a segunda sessão da CLI. Se você estiver usando o Cloud Shell em um navegador, use o botão Abrir nova sessão. Se estiver usando a CLI localmente, abra uma segunda instância da CLI.

Crie um hub IoT

Nesta seção, você usa a CLI do Azure para criar um grupo de recursos e um hub IoT. Um grupo de recursos do Azure é um contêiner lógico no qual os recursos do Azure são implantados e gerenciados. Um hub IoT atua como um hub central de mensagens para comunicação bidirecional entre o aplicativo IoT e os dispositivos.

Dica

Você tem a opção de criar um grupo de recursos do Azure, um hub IoT e outros recursos usando o portal do Azure, o Visual Studio Code ou outros métodos programáticos.

Na primeira sessão da CLI, execute o comando az group create para criar um grupo de recursos. O comando a seguir cria um grupo de recursos chamado MyResourceGroup na localização eastus.
```
az group create --name MyResourceGroup --location eastus
```
Na primeira sessão da CLI, execute o comando Az PowerShell module iot hub create para criar um hub IoT. São necessários alguns minutos para criar um hub IoT.

YourIotHubName. Substitua esse espaço reservado e as chaves ao redor no comando a seguir, usando o nome escolhido para o hub IoT. Um nome de Hub IoT deve ser exclusivo globalmente no Azure. Use o nome do hub IoT no restante deste guia de início rápido, sempre que ver o espaço reservado.
```
az iot hub create --resource-group MyResourceGroup --name {YourIoTHubName}
```

Criar e monitorar um dispositivo

Nesta seção, você criará um dispositivo simulado na primeira sessão da CLI. O dispositivo simulado envia a telemetria de dispositivo para o Hub IoT. Na segunda sessão da CLI, você monitora eventos e telemetria.

Para criar e iniciar um dispositivo simulado:

Na primeira sessão da CLI, execute o comando az iot hub device-identity create. Esse comando cria a identidade do dispositivo simulado.

YourIotHubName. substitua o espaço reservado abaixo pelo nome escolhido para o hub IoT.

simDevice. Você pode usar esse nome diretamente para o dispositivo simulado no restante deste guia de início rápido. Opcionalmente, use outro nome.
```
az iot hub device-identity create -d simDevice -n {YourIoTHubName} 
```
Na primeira sessão da CLI, execute o comando az iot device simulate. Esse comando inicia o dispositivo simulado. O dispositivo envia telemetria para o Hub IoT e recebe mensagens dele.

YourIotHubName. substitua o espaço reservado abaixo pelo nome escolhido para o hub IoT.
```
az iot device simulate -d simDevice -n {YourIoTHubName}
```

Para monitorar um dispositivo:

Na segunda sessão da CLI, execute o comando az iot hub monitor-events. Esse comando monitora continuamente o dispositivo simulado. A saída mostra telemetria, como eventos e alterações de estado de propriedade que o dispositivo simulado envia ao hub IoT.

YourIotHubName. substitua o espaço reservado abaixo pelo nome escolhido para o hub IoT.
```
az iot hub monitor-events --output table -p all -n {YourIoTHubName}
```
Depois de monitorar o dispositivo simulado na segunda sessão da CLI, pressione Ctrl+C para interromper o monitoramento. Mantenha a segunda sessão da CLI aberta para usar nas etapas posteriores.

Usar a CLI para enviar uma mensagem

Nesta seção, você enviará uma mensagem ao dispositivo simulado.

Na primeira sessão da CLI, confirme se o dispositivo simulado ainda está funcionando. Se o dispositivo foi interrompido, execute o seguinte comando para reiniciá-lo:

YourIotHubName. substitua o espaço reservado abaixo pelo nome escolhido para o hub IoT.
```
az iot device simulate -d simDevice -n {YourIoTHubName}
```
Na segunda sessão da CLI, execute o comando az iot device c2d-message send. Esse comando envia uma mensagem de nuvem para dispositivo do hub IoT para o dispositivo simulado. A mensagem inclui uma cadeia de caracteres e dois pares chave-valor.

YourIotHubName. substitua o espaço reservado abaixo pelo nome escolhido para o hub IoT.
```
az iot device c2d-message send -d simDevice --data "Hello World" --props "key0=value0;key1=value1" -n {YourIoTHubName}
```
Você tem a opção de enviar mensagens de nuvem para dispositivo usando o portal do Azure. Para fazer isso, navegue até a página de visão geral do Hub IoT, selecione Dispositivos IoT, selecione o dispositivo simulado e escolha Mensagem para Dispositivo.
Na primeira sessão da CLI, confirme se o dispositivo simulado recebeu a mensagem.

Usar a CLI para chamar um método do dispositivo

Nesta seção, você chamará um método direto no dispositivo simulado.

Como fez anteriormente, confirme se o dispositivo simulado da primeira sessão da CLI está funcionando. Se não estiver, reinicie-o.
Na segunda sessão da CLI, execute o comando az iot hub invoke-device-method. Neste exemplo, não há um método preexistente para o dispositivo. O comando chama um nome de método de exemplo no dispositivo simulado e retorna um conteúdo.

YourIotHubName. substitua o espaço reservado abaixo pelo nome escolhido para o hub IoT.
```
az iot hub invoke-device-method --mn MySampleMethod -d simDevice -n {YourIoTHubName}
```
Na primeira sessão da CLI, confirme se a saída mostra a chamada de método.

Usar a CLI para atualizar propriedades do dispositivo

Nesta seção, você atualizará o estado do dispositivo simulado definindo valores de propriedade.

Como fez anteriormente, confirme se o dispositivo simulado da primeira sessão da CLI está funcionando. Se não estiver, reinicie-o.
Na segunda sessão da CLI, execute o comando az iot hub device-twin update. Esse comando atualiza as propriedades para o estado desejado no dispositivo gêmeo do hub IoT que corresponde ao dispositivo simulado. Neste caso, o comando define propriedades de condição de temperatura de exemplo.

Importante

Se você estiver usando o PowerShell no shell da CLI, use a versão do PowerShell do comando abaixo. O PowerShell exige que você escape dos caracteres no conteúdo JSON.

YourIotHubName. substitua o espaço reservado abaixo pelo nome escolhido para o hub IoT.
```
az iot hub device-twin update -d simDevice --desired '{"conditions":{"temperature":{"warning":98, "critical":107}}}' -n {YourIoTHubName}
```
```
az iot hub device-twin update -d simDevice --desired '{\"conditions\":{\"temperature\":{\"warning\":98, \"critical\":107}}}' -n {YourIoTHubName}
```
Na primeira sessão da CLI, confirme se a atualização de propriedade está na saída do dispositivo simulado.
Na segunda sessão da CLI, execute o comando az iot hub device-twin show. Esse comando relata alterações nas propriedades do dispositivo.

YourIotHubName. substitua o espaço reservado abaixo pelo nome escolhido para o hub IoT.
```
az iot hub device-twin show -d simDevice --query properties.reported -n {YourIoTHubName}
```

Exibir métricas de mensagens no portal

O portal do Azure permite que você gerencie todos os aspectos do hub IoT e dos dispositivos. Em um aplicativo típico de Hub IoT que recebe a telemetria de dispositivos, convém monitorar os dispositivos ou exibir as métricas na telemetria de dispositivos.

Para visualizar as métricas de mensagens no portal do Azure:

No menu de navegação à esquerda no portal, selecione Todos os recursos. Essa guia lista todos os recursos da assinatura, incluindo o hub IoT que você criou.
Selecione o link no Hub IoT criado. O portal exibe a página de visão geral do hub.
Selecione Métricas no painel esquerdo do Hub IoT.
No campo Escopo, insira o nome do hub IoT.
No campo Namespace da Métrica, selecione Métricas Padrão do Hub IoT.
No campo Métrica, selecione Número total de mensagens usadas.
Passe o ponteiro do mouse sobre a área da linha do tempo na qual seu dispositivo enviou mensagens. O número total de mensagens de determinado período é exibido no canto inferior esquerdo da linha do tempo.
Opcionalmente, use a lista suspensa Métricas para exibir outras métricas em seu dispositivo simulado. Por exemplo, Entregas de mensagens C2d concluídas ou Total de dispositivos (versão prévia) .

Limpar os recursos

Se você não precisar mais dos recursos do Azure criados neste guia de início rápido, poderá usar a CLI do Azure para excluí-los.

Se você continuar para o próximo artigo recomendado, mantenha os recursos já criados e reutilize-os.

Importante

A exclusão de um grupo de recursos é irreversível. O grupo de recursos e todos os recursos contidos nele são excluídos permanentemente. Não exclua acidentalmente o grupo de recursos ou os recursos incorretos.

Para excluir um grupo de recursos por nome:

Execute o comando az group delete. Esse comando removerá o grupo de recursos, o hub IoT e o registro de dispositivo que você criou.
```
az group delete --name MyResourceGroup
```
Execute o comando az group list para confirmar se o grupo de recursos foi excluído.
```
az group list
```

Próximas etapas

Neste início rápido, você usou a CLI do Azure para criar um hub IoT, criar um dispositivo simulado, enviar e monitorar telemetria, chamar um método, definir propriedades desejadas e limpar recursos. Você usou o portal do Azure para visualizar as métricas de mensagens em seu dispositivo.

Se você for um desenvolvedor de dispositivos, a próxima etapa sugerida será ver o guia de início rápido de telemetria, que usa o SDK de dispositivo IoT do Azure para C. Opcionalmente, confira um dos artigos do guia de início rápido de telemetria do Hub IoT do Azure disponíveis em seu idioma ou SDK preferencial.

Para saber como controlar o dispositivo simulado em um aplicativo de back-end, continue no próximo início rápido.

Início Rápido: Controlar um dispositivo conectado a um hub IoT