Início Rápido: Enviar telemetria de um dispositivo para um hub IoT e monitorizá-la com a CLI do Azure

Artigo
06/01/2023

O Hub IoT é um serviço do Azure que lhe permite ingerir elevados volumes de telemetria dos seus dispositivos IoT para a cloud para armazenamento ou processamento. Neste início rápido sem código, vai utilizar a CLI do Azure para criar um hub IoT e um dispositivo simulado. Irá enviar telemetria do dispositivo para o hub e enviar mensagens, métodos de chamada e atualizar propriedades no dispositivo. Também irá utilizar o portal do Azure para visualizar as métricas do dispositivo. Este artigo mostra um fluxo de trabalho básico para programadores que utilizam a CLI para interagir com uma aplicação Hub IoT.

Pré-requisitos

Se não tiver uma subscrição do Azure, crie uma gratuitamente antes de começar.
CLI do Azure. Pode executar todos os comandos neste início rápido com o Azure Cloud Shell, uma shell interativa da CLI que é executada no seu browser ou numa aplicação, como Terminal do Windows. Se utilizar a Cloud Shell, não precisa de instalar nada. Se preferir utilizar a CLI localmente, este início rápido requer a versão 2.36 ou posterior da CLI do Azure. Executar az --version para localizar a versão. Para instalar ou atualizar, veja Instalar a CLI do Azure.

Inicie sessão no portal do Azure.

Independentemente de executar a CLI localmente ou no Cloud Shell, mantenha o portal aberto no browser. Irá utilizá-la mais tarde neste início rápido.

Iniciar a Cloud Shell

Nesta secção, vai iniciar uma instância do Cloud Shell do Azure. Se utilizar a CLI localmente, avance para a secção Preparar duas sessões da CLI.

Para iniciar o Cloud Shell:

Selecione o botão Cloud Shell na barra de menus no canto superior direito do portal do Azure.

Nota

Se esta for a primeira vez que utiliza o Cloud Shell, pede-lhe para criar armazenamento, que é necessário para utilizar o Cloud Shell. Selecione uma subscrição para criar uma conta de armazenamento e a partilha de Ficheiros do Microsoft Azure.
Selecione o ambiente da CLI preferencial na lista pendente Selecionar ambiente . Este início rápido utiliza o ambiente bash . Também pode utilizar o ambiente do PowerShell .

Nota

Alguns comandos requerem sintaxe ou formatação diferentes nos ambientes do Bash e do PowerShell . Para obter mais informações, veja Sugestões para utilizar a CLI do Azure com êxito.

Preparar duas sessões da CLI

Em seguida, prepare duas sessões da CLI do Azure. Se estiver a utilizar a Cloud Shell, irá executar estas sessões em separadores Cloud Shell separadores separadores. Se utilizar um cliente da CLI local, irá executar instâncias da CLI separadas. Utilize as sessões separadas da CLI para as seguintes tarefas:

A primeira sessão simula um dispositivo IoT que comunica com o seu hub IoT.
A segunda sessão monitoriza o dispositivo na primeira sessão ou envia mensagens, comandos e atualizações de propriedades.

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

A CLI do Azure requer que tenha sessão iniciada na sua conta do Azure. Toda a comunicação entre a sessão da shell da CLI do Azure e o hub IoT é autenticada e encriptada. Como resultado, este início rápido não precisa de autenticação extra que utilizaria com um dispositivo real, como uma cadeia de ligação.

Na primeira sessão da CLI, execute o comando az extension add . O comando adiciona a Extensão IoT do Microsoft Azure para a CLI do Azure à shell da CLI. A Extensão IOT adiciona comandos específicos Hub IoT, IoT Edge e IoT Device Provisioning Service (DPS) à CLI do Azure.
```
az extension add --name azure-iot
```
Depois de instalar a extensão IOT do Azure, não precisa de instalá-la novamente em nenhuma Cloud Shell sessão.

Nota

Este artigo utiliza a versão mais recente da extensão do Azure IoT, denominada azure-iot. A versão legada é denominada azure-cli-iot-ext. Só deve ter uma versão instalada de cada vez. Pode utilizar o comando az extension list para validar as extensões atualmente instaladas.

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

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

Para ver que extensões instalou, utilize az extension list.
Abra a segunda sessão da CLI. Se estiver a utilizar o Cloud Shell num browser, utilize o botão Abrir nova sessão. Se estiver a utilizar a CLI localmente, abra uma segunda instância da CLI.

Criar um hub IoT

Nesta secção, vai utilizar a CLI do Azure para criar um grupo de recursos e um hub IoT. Um grupo de recursos do Azure é um contentor lógico no qual os recursos do Azure são implementados e geridos. Um hub IoT atua como um hub de mensagens central para a comunicação bidirecional entre a sua aplicação IoT e os dispositivos.

Dica

Opcionalmente, pode criar um grupo de recursos do Azure, um hub IoT e outros recursos com 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 seguinte cria um grupo de recursos com o nome 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. A criação de um hub IoT demora alguns minutos.

YourIotHubName. Substitua este marcador de posição e as chavetas adjacentes no seguinte comando, com o nome que escolheu para o hub IoT. Um nome de hub IoT tem de ser globalmente exclusivo no Azure. Utilize o nome do hub IoT no resto deste início rápido, onde quer que veja o marcador de posição.
```
az iot hub create --resource-group MyResourceGroup --name {YourIoTHubName}
```

Criar e monitorizar um dispositivo

Nesta secção, vai criar um dispositivo simulado na primeira sessão da CLI. O dispositivo simulado envia a telemetria do dispositivo para o seu hub IoT. Na segunda sessão da CLI, irá monitorizar 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 . Este comando cria a identidade do dispositivo simulado.

YourIotHubName. Substitua este marcador de posição abaixo pelo nome que escolheu para o hub IoT.

simDevice. Pode utilizar este nome diretamente para o dispositivo simulado no resto deste início rápido. Opcionalmente, utilize um nome diferente.
```
az iot hub device-identity create -d simDevice -n {YourIoTHubName} 
```
Na primeira sessão da CLI, execute o comando az iot device simulate . Este comando inicia o dispositivo simulado. O dispositivo envia telemetria para o seu hub IoT e recebe mensagens do mesmo.

YourIotHubName. Substitua este marcador de posição abaixo pelo nome que escolheu para o hub IoT.
```
az iot device simulate -d simDevice -n {YourIoTHubName}
```

Para monitorizar um dispositivo:

Na segunda sessão da CLI, execute o comando az iot hub monitor-events . Este comando monitoriza continuamente o dispositivo simulado. O resultado mostra telemetria, como eventos e alterações de estado de propriedade que o dispositivo simulado envia para o hub IoT.

YourIotHubName. Substitua este marcador de posição abaixo pelo nome que escolheu para o hub IoT.
```
az iot hub monitor-events --output table -p all -n {YourIoTHubName}
```
Depois de monitorizar o dispositivo simulado na segunda sessão da CLI, prima Ctrl+C para parar a monitorização. Mantenha a segunda sessão da CLI aberta para utilizar nos passos posteriores.

Utilizar a CLI para enviar uma mensagem

Nesta secção, vai enviar uma mensagem para o dispositivo simulado.

Na primeira sessão da CLI, confirme que o dispositivo simulado ainda está em execução. Se o dispositivo tiver parado, execute o seguinte comando para reiniciá-lo:

YourIotHubName. Substitua este marcador de posição abaixo pelo nome que escolheu 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 . Este comando envia uma mensagem da cloud para o dispositivo a partir do hub IoT para o dispositivo simulado. A mensagem inclui uma cadeia e dois pares chave-valor.

YourIotHubName. Substitua este marcador de posição abaixo pelo nome que escolheu para o hub IoT.
```
az iot device c2d-message send -d simDevice --data "Hello World" --props "key0=value0;key1=value1" -n {YourIoTHubName}
```
Opcionalmente, pode enviar mensagens da cloud para o dispositivo com o portal do Azure. Para tal, navegue para a página de descrição geral do seu Hub IoT, selecione Dispositivos IoT, selecione o dispositivo simulado e selecione Mensagem para Dispositivo.
Na primeira sessão da CLI, confirme que o dispositivo simulado recebeu a mensagem.

Utilizar a CLI para chamar um método de dispositivo

Nesta secção, vai chamar um método direto no dispositivo simulado.

Tal como fez anteriormente, confirme que o dispositivo simulado na primeira sessão da CLI está em execução. Caso contrário, reinicie-o.
Na segunda sessão da CLI, execute o comando az iot hub invoke-device-method . Neste exemplo, não existe nenhum método pré-existente para o dispositivo. O comando chama um nome de método de exemplo no dispositivo simulado e devolve um payload.

YourIotHubName. Substitua este marcador de posição abaixo pelo nome que escolheu para o hub IoT.
```
az iot hub invoke-device-method --mn MySampleMethod -d simDevice -n {YourIoTHubName}
```
Na primeira sessão da CLI, confirme se o resultado mostra a chamada do método.

Utilizar a CLI para atualizar as propriedades do dispositivo

Nesta secção, irá atualizar o estado do dispositivo simulado ao definir valores de propriedade.

Tal como fez anteriormente, confirme que o dispositivo simulado na primeira sessão da CLI está em execução. Caso contrário, reinicie-o.
Na segunda sessão da CLI, execute o comando az iot hub device-twin update . Este comando atualiza as propriedades para o estado pretendido no dispositivo duplo do hub IoT que corresponde ao seu dispositivo simulado. Neste caso, o comando define as propriedades da condição de temperatura de exemplo.

Importante

Se estiver a utilizar o PowerShell na shell da CLI, utilize a versão do PowerShell do comando abaixo. O PowerShell requer que escape aos carateres no payload JSON.

YourIotHubName. Substitua este marcador de posição abaixo pelo nome que escolheu 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 o dispositivo simulado produz a atualização da propriedade.
Na segunda sessão da CLI, execute o comando az iot hub device-twin show . Este comando comunica alterações às propriedades do dispositivo.

YourIotHubName. Substitua este marcador de posição abaixo pelo nome que escolheu para o hub IoT.
```
az iot hub device-twin show -d simDevice --query properties.reported -n {YourIoTHubName}
```

Ver métricas de mensagens no portal

O portal do Azure permite-lhe gerir todos os aspetos do seu hub IoT e dispositivos. Numa aplicação Hub IoT típica que ingere telemetria de dispositivos, poderá querer monitorizar dispositivos ou ver métricas na telemetria do dispositivo.

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

No menu de navegação esquerdo do portal, selecione Todos os Recursos. Este separador lista todos os recursos na sua subscrição, incluindo o hub IoT que criou.
Selecione a ligação no hub IoT que criou. O portal apresenta a página de descrição geral do hub.
Selecione Métricas no painel esquerdo do seu Hub IoT.
No campo Âmbito , introduza o nome do hub IoT.
No campo Espaço de Nomes de Métricas , selecione Métricas Padrão do Hub Iot.
No campo Métrica , selecione Número total de mensagens utilizadas.
Paire o cursor do rato sobre a área da linha cronológica na qual o dispositivo enviou mensagens. O número total de mensagens num ponto no tempo aparece no canto inferior esquerdo da linha cronológica.
Opcionalmente, utilize a lista pendente Métrica para apresentar outras métricas no seu dispositivo simulado. Por exemplo, entregas de mensagens C2d concluídas ou Total de dispositivos (pré-visualização).

Limpar os recursos

Se já não precisar dos recursos do Azure criados neste início rápido, pode utilizar a CLI do Azure para os eliminar.

Se continuar para o próximo artigo recomendado, pode manter os recursos que já criou e reutilizá-los.

Importante

A eliminação de um grupo de recursos é irreversível. O grupo de recursos e todos os recursos nele contidos são eliminados permanentemente. Confirme que não elimina acidentalmente o grupo de recursos ou recursos errados.

Para eliminar um grupo de recursos por nome:

Execute o comando az group delete . Este comando remove o grupo de recursos, o hub IoT e o registo de dispositivos que criou.
```
az group delete --name MyResourceGroup
```
Execute o comando az group list para confirmar que o grupo de recursos foi eliminado.
```
az group list
```

Passos seguintes

Neste início rápido, utilizou a CLI do Azure para criar um hub IoT, criar um dispositivo simulado, enviar e monitorizar telemetria, chamar um método, definir as propriedades pretendidas e limpar recursos. Utilizou o portal do Azure para visualizar as métricas de mensagens no seu dispositivo.

Se for um programador de dispositivos, o próximo passo sugerido é ver o início rápido da telemetria que utiliza o SDK do Dispositivo IoT do Azure para C. Opcionalmente, consulte um dos artigos de início rápido de telemetria disponíveis Hub IoT do Azure no seu idioma ou SDK preferido.

Para saber como controlar o seu dispositivo simulado a partir de uma aplicação back-end, continue para o guia de início rápido seguinte.

Guia de Início Rápido: controlar um dispositivo ligado a um hub IoT