Guia de início rápido: enviar telemetria de um dispositivo para um hub IoT e monitorá-la com a CLI do Azure

O Hub IoT do Azure foi concebido para recolher grandes volumes de dados de telemetria de dispositivos IoT para armazenamento ou processamento na cloud. Neste início rápido sem código, você usa a CLI do Azure para criar um hub IoT e um dispositivo simulado. Envias telemetria do dispositivo para o hub e também envias mensagens, métodos de chamada e atualizações de propriedades no dispositivo. Usa o portal do Azure para visualizar métricas de dispositivos.

Este artigo fornece um fluxo de trabalho básico para programadores ao utilizar a CLI do Azure para interagir com uma aplicação Hub IoT.

Pré-requisitos

  • Uma assinatura do Azure. Se não tiveres um, podes criar um gratuitamente antes de começares.
  • O CLI do Azure. Pode executar todos os comandos neste quickstart usando o Azure Cloud Shell, um shell interativo de CLI que corre no seu navegador ou numa aplicação como o Terminal do Windows. Se usares Cloud Shell, não precisas de instalar nada. Se você preferir usar a CLI localmente, este início rápido requer a CLI do Azure versão 2.36 ou posterior. Executar az --version para localizar a versão. Para instalar ou atualizar, consulte Instale o CLI do Azure.

Inicie sessão no portal do Azure

Inicie sessão no portal do Azure.

Independentemente de executares a CLI localmente ou na Cloud Shell, mantém o portal aberto no teu navegador. Você usá-lo-á mais tarde neste guia de início rápido.

Abrir o Cloud Shell

Nesta secção, abres uma instância de Cloud Shell. Se você usar a CLI localmente, vá para a seção Preparar duas sessões da CLI.

  1. Selecione Cloud Shell na barra de menu no canto superior direito do portal Azure.

    Captura de ecrã que mostra o botão Cloud Shell Azure portal.

    Se for a sua primeira vez a usar o Cloud Shell, é solicitado a criar armazenamento, que é necessário para usar o Cloud Shell. Selecione uma subscrição para criar uma conta de armazenamento e uma partilha Ficheiros do Azure.

  2. Selecione o seu ambiente de CLI preferido na lista pendente Selecionar ambiente. Este quickstart utiliza o ambiente Bash. Também podes usar o ambiente PowerShell.

    Captura de ecrã que mostra a seleção do ambiente CLI.

    Alguns comandos requerem sintaxe ou formatação diferente 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ê prepara duas sessões da CLI do Azure. Se usares Cloud Shell, executa estas sessões em separadores Cloud Shell separados. Se usares um cliente de CLI local, executa 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 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 em sua sessão de shell e execute-o.

Para usar a CLI do Azure, tem de ter sessão iniciada na sua conta do Azure. Toda a comunicação entre sua sessão de shell da CLI do Azure e seu hub IoT é autenticada e criptografada. Como resultado, este quickstart não precisa da autenticação extra que se usa 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 Microsoft Azure IoT para CLI do Azure ao seu shell CLI. A extensão IoT adiciona comandos Hub IoT, Azure IoT Edge e IoT Device Provisioning Service específicos para a CLI do Azure.

    az extension add --name azure-iot

    Depois de instalar a extensão Azure IoT, não precisa de a instalar novamente em nenhuma sessão Cloud Shell.

    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-ext. Deves ter apenas 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 estão instaladas no momento, use az extension list.

  • Abra a segunda sessão da CLI. Se usares Cloud Shell num navegador, usa Abrir nova sessão. Se usares o CLI localmente, abre uma segunda instância de CLI.

    Captura de ecrã que mostra a abertura de uma nova sessão de Cloud Shell.

Criar 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 contentor lógico no qual os recursos do Azure são implementados e geridos. Um hub IoT funciona como um hub central de mensagens para comunicação bidirecional entre a sua aplicação IoT e os dispositivos.

  1. 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 nomeado MyResourceGroup na eastus localização.

    az group create --name MyResourceGroup --location eastus

  2. Na primeira sessão da CLI, execute o comando Az PowerShell module iot hub create para criar um hub IoT. Leva alguns minutos para criar um hub IoT.

    Substitua o marcador de posição YourIotHubName e as chavetas circundantes no comando seguinte pelo nome que escolheu para o seu hub IoT. Um nome de hub IoT deve ser globalmente exclusivo no Azure. Use o nome do hub IoT no restante deste guia de iniciação rápida onde se veja o marcador.

    az iot hub create --resource-group MyResourceGroup --name {YourIoTHubName}

Criar e monitorar um dispositivo

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

Para criar e iniciar um dispositivo simulado:

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

    • YourIotHubName. Substitua este marcador no código seguinte pelo nome que escolheu para o seu hub IoT.
    • simDevice. Você pode usar esse nome diretamente para o dispositivo simulado no restante deste início rápido. Opcionalmente, use um nome diferente.
    az iot hub device-identity create -d simDevice -n {YourIoTHubName}

  2. Na primeira sessão da CLI, execute o comando az iot device simulate . Este comando inicia o dispositivo simulado. O dispositivo envia telemetria para seu hub IoT e recebe mensagens dele.

    Substitua o YourIotHubName marcador no código seguinte pelo nome que escolheu para o seu hub IoT.

    az iot device simulate -d simDevice -n {YourIoTHubName}

Para monitorizar um dispositivo:

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

    Substitua o YourIotHubName marcador no código seguinte pelo nome que escolheu para o seu hub IoT.

    az iot hub monitor-events --output table -p all -n {YourIoTHubName}

    Captura de tela de eventos de monitoramento em um dispositivo simulado.

  2. Depois de monitorizares o dispositivo simulado na segunda sessão de CLI, seleciona Ctrl+C para parar a monitorização. Mantenha a segunda sessão da CLI aberta para usar em etapas posteriores.

Usar a CLI para enviar uma mensagem

Nesta seção, você envia uma mensagem para o dispositivo simulado.

  1. Na primeira sessão da CLI, confirme se o dispositivo simulado ainda está em execução. Se o dispositivo parou, execute o seguinte comando para o reiniciar.

    Substitua o YourIotHubName marcador no código seguinte pelo nome que escolheu para o seu hub IoT.

    az iot device simulate -d simDevice -n {YourIoTHubName}

  2. Na segunda sessão da CLI, execute az iot device c2d-message send comando. Este comando envia uma mensagem da nuvem para o dispositivo do seu hub IoT para o dispositivo simulado. A mensagem inclui uma cadeia e dois pares chave/valor.

    Substitua o YourIotHubName marcador no código seguinte pelo nome que escolheu para o seu hub IoT.

    az iot device c2d-message send -d simDevice --data "Hello World" --props "key0=value0;key1=value1" -n {YourIoTHubName}

    Opcionalmente, você pode enviar mensagens da nuvem para o dispositivo usando o portal do Azure. Para enviar mensagens através do portal Azure, navegue até à página Visão Geral do seu hub IoT, selecione Dispositivos IoT, selecione o dispositivo simulado e selecione Mensagem para Dispositivo.

  3. Na primeira sessão da CLI, confirme se o dispositivo simulado recebeu a mensagem.

    Captura de ecrã que mostra um dispositivo simulado a receber uma mensagem.

Usar a CLI para chamar um método de dispositivo

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

  1. Como fez antes, confirme se o dispositivo simulado na primeira sessão da CLI está em execução. Caso contrário, reinicie-o.

  2. Na segunda sessão da CLI, execute o comando az iot hub invoke-device-method . Neste exemplo, não há nenhum método preexistente para o dispositivo. O comando chama um nome de método de exemplo no dispositivo simulado e retorna uma carga útil.

    Substitua o YourIotHubName marcador no código seguinte pelo nome que escolheu para o seu hub IoT.

    az iot hub invoke-device-method --mn MySampleMethod -d simDevice -n {YourIoTHubName}

  3. Na primeira sessão de CLI, confirme que a saída mostra a chamada ao método.

    Captura de ecrã que mostra um dispositivo simulado a exibir a saída depois de um método ter sido invocado.

Usar a CLI para atualizar as propriedades do dispositivo

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

  1. Como fez antes, confirme se o dispositivo simulado na primeira sessão da CLI está em execução. Caso contrário, reinicie-o.

  2. Na segunda sessão da linha de comandos (CLI), execute o comando az iot hub device-twin update. Este comando atualiza as propriedades para o estado desejado no dispositivo gêmeo do hub IoT que corresponde ao seu dispositivo simulado. Nesse 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 no código a seguir. O PowerShell requer que se escape os caracteres na carga JSON.

    Substitua o YourIotHubName marcador no código seguinte pelo nome que escolheu para o seu 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}

  3. Na primeira sessão da linha de comandos (CLI), confirme se o dispositivo simulado produz a atualização da propriedade.

    Captura de tela que mostra como atualizar propriedades em um dispositivo.

  4. Na segunda sessão da CLI, execute o comando az iot hub device-twin show. Este comando relata alterações nas propriedades do dispositivo.

    Substitua o YourIotHubName marcador no código seguinte pelo nome que escolheu para o seu hub IoT.

    az iot hub device-twin show -d simDevice --query properties.reported -n {YourIoTHubName}

    Captura de tela que mostra as propriedades atualizadas em um dispositivo gêmeo.

Ver métricas de mensagens no portal

Pode gerir todos os aspetos do seu hub IoT e dispositivos no portal Azure. Em uma aplicação típica do Hub IoT que ingere telemetria de dispositivos, é útil monitorizar dispositivos ou visualizar métricas sobre a telemetria de dispositivos.

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

  1. No menu de serviço do portal, selecione Todos os Recursos. Este separador lista todos os recursos da sua subscrição, incluindo o hub IoT que criou.

  2. Selecione a ligação no hub IoT que criou. O portal mostra a página de Visão Geral do hub.

  3. Selecione Métricas no painel esquerdo do seu hub IoT.

    Captura de ecrã que mostra métricas de mensagens Hub IoT.

  4. No campo Escopo, insira o nome do hub IoT.

  5. No campo Espaço de Nomes de Métricas, selecione métricas padrão do Hub IoT.

  6. No campo Métrica, selecione Número total de mensagens usadas.

  7. Passe o ponteiro do mouse sobre a área da linha do tempo na qual o dispositivo enviou mensagens. O número total de mensagens em um determinado momento aparece no canto inferior esquerdo da linha do tempo.

    Captura de ecrã que mostra uma vista de métricas Hub IoT.

  8. Opcionalmente, use a lista pendente Metric para mostrar outras métricas no seu dispositivo simulado. Por exemplo, veja entregas de mensagens C2D concluídas ou Total de dispositivos (pré-visualização).

Limpar recursos

Se já não precisares dos recursos do Azure que criaste neste quickstart, podes usar a CLI do Azure para os apagar.

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. Certifique-se de não eliminar acidentalmente os grupos de recursos ou recursos errados.

Para eliminar um grupo de recursos por nome:

  1. Execute o comando az group delete. Este comando remove o grupo de recursos, o hub IoT e o registo do dispositivo que criou.

    az group delete --name MyResourceGroup

  2. Executa o comando az group list para confirmar que o grupo de recursos foi eliminado.

    az group list

Resumo

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 as propriedades desejadas e limpar recursos. Você usou o portal do Azure para visualizar métricas de mensagens em seu dispositivo.

Se és programador de dispositivos, o passo seguinte sugerido é consultar o quickstart de telemetria que utiliza o Azure IoT Device SDK for C. Opcionalmente, consulta um dos artigos disponíveis sobre o quickstart de telemetria do Hub IoT na tua língua ou SDK preferido.

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

Próximo passo

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

  • Last updated on