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

Hub IoT do Azure foi projetado para coletar grandes volumes de dados de telemetria de dispositivos IoT para armazenamento ou processamento na nuvem. Neste início rápido sem código, você usará a CLI do Azure para criar um hub IoT e um dispositivo simulado. Você envia a telemetria do dispositivo para o hub e também envia mensagens, métodos de chamada e propriedades de atualização no dispositivo. Use o portal Azure para visualizar as métricas do dispositivo.

Este artigo fornece um fluxo de trabalho básico para desenvolvedores usando o CLI do Azure para interagir com um aplicativo Hub IoT.

Pré-requisitos

  • Uma assinatura do Azure. Se você não tiver um, poderá criar um gratuitamente antes de começar.
  • A Interface de Linha de Comando do Azure. Você pode executar todos os comandos neste início rápido usando Azure Cloud Shell, um shell interativo da CLI que é executado no navegador ou em um aplicativo, como Terminal do Windows. Se você usar 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, consulte Instale o CLI do Azure.

Entre no Portal do Azure

Entre no portal do Azure.

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

Abrir o Cloud Shell

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

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

    Captura de tela que mostra o botão do Cloud Shell no portal do Azure.

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

  2. Selecione seu ambiente de CLI preferido na lista suspensa Selecionar ambiente. Este início rápido usa o ambiente bash. Você também pode usar o ambiente do PowerShell.

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

    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 você usar Cloud Shell, execute essas sessões em guias Cloud Shell separadas. Se você usar um cliente da CLI local, execute 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.

Para usar o CLI do Azure, você deve estar conectado à sua conta 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 adicional que você usa 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 seu shell da CLI. A extensão de IoT adiciona comandos específicos da CLI do Azure para Hub IoT, Azure IoT Edge e o Serviço de Provisionamento de Dispositivos IoT.

    az extension add --name azure-iot

    Depois de instalar a extensão IoT do Azure, você não precisará instalá-la novamente em nenhuma sessão 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 é chamada 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 estão instaladas no momento, use az extension list.

  • Abra a segunda sessão da CLI. Se você usar o Cloud Shell em um navegador, use Abrir nova sessão. Se você usar a CLI localmente, abra uma segunda instância da CLI.

    Captura de tela mostrando a abertura de uma nova sessão do Cloud Shell.

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 de mensagens central para comunicação bidirecional entre seu aplicativo 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 a seguir cria um grupo de recursos nomeado MyResourceGroup no eastus local.

    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. São necessários alguns minutos para criar um hub IoT.

    Substitua o marcador YourIotHubName e as chaves ao redor dele no comando a seguir pelo nome que você escolheu para o seu 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 vir 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 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. Esse comando cria a identidade do dispositivo simulado.

    • YourIotHubName. Substitua esse espaço reservado no código a seguir 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}

  2. 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.

    Substitua o marcador YourIotHubName no código a seguir pelo nome que você escolheu para o seu hub IoT.

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

Para monitorar um dispositivo:

  1. 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.

    Substitua o espaço reservado YourIotHubName no código a seguir pelo nome que você escolheu para o Hub IoT.

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

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

  2. Depois de monitorar o dispositivo simulado na segunda sessão da CLI, selecione 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.

  1. Na primeira sessão da CLI, confirme se o dispositivo simulado ainda está funcionando. Se o dispositivo for interrompido, execute o comando a seguir para reiniciá-lo.

    Substitua o placeholder YourIotHubName no código a seguir pelo nome que você escolheu para o Hub IoT.

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

  2. 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.

    Substitua o placeholder YourIotHubName no código a seguir pelo nome que você escolheu para seu 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 enviar mensagens por meio do portal Azure, navegue até a página Overview para o hub IoT, selecione IoT Devices, selecione o dispositivo simulado e selecione Message to Device.

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

    Captura de tela que mostra um dispositivo simulado recebendo uma mensagem.

Usar a CLI para chamar um método do dispositivo

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

  1. Como fez anteriormente, confirme se o dispositivo simulado da primeira sessão da CLI está funcionando. Se não estiver, reinicie-o.

  2. 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.

    Substitua o marcador YourIotHubName no código a seguir pelo nome que você escolheu para o seu hub IoT.

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

  3. Na primeira sessão da CLI, confirme se a saída mostra a chamada do método.

    Captura de tela que mostra um dispositivo simulado exibindo a saída depois que um método foi invocado.

Usar a CLI para atualizar propriedades do dispositivo

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

  1. Como fez anteriormente, confirme se o dispositivo simulado da primeira sessão da CLI está funcionando. Se não estiver, reinicie-o.

  2. 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 no código a seguir. O PowerShell exige que você escape dos caracteres no conteúdo JSON.

    Substitua o marcador YourIotHubName no código a seguir pelo nome que você 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 CLI, confirme se a atualização de propriedade está na saída do dispositivo simulado.

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

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

    Substitua o placeholder YourIotHubName no código a seguir pelo nome que você escolheu para o 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.

Exibir métricas de mensagens no portal

Você pode gerenciar todos os aspectos do hub IoT e dispositivos no portal Azure. Em um aplicativo típico de Hub IoT que coleta a telemetria de dispositivos, convém monitorar os dispositivos ou analisar métricas de telemetria dos dispositivos.

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

  1. No menu de serviço no portal, selecione Todos os Recursos. Essa guia lista todos os recursos em sua assinatura, incluindo o hub IoT que você criou.

  2. Selecione o link no hub IoT que você criou. O portal exibe a página Visão geral do hub.

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

    Captura de tela que mostra métricas de mensagens do Hub IoT.

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

  5. No campo Metric Namespace, selecione Hub IoT métricas padrão.

  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 seu dispositivo enviou mensagens. O número total de mensagens de determinado período é exibido no canto inferior esquerdo da linha do tempo.

    Captura de tela que mostra uma exibição das métricas do Hub IoT.

  8. Opcionalmente, use o menu suspenso Métrica para exibir outras métricas no dispositivo simulado. Por exemplo, consulte 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 de Azure criados neste início rápido, poderá usar o CLI do Azure para excluí-los.

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

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

Para excluir um grupo de recursos por nome:

  1. Execute o comando az group delete. Esse comando remove o grupo de recursos, o hub IoT e o registro de dispositivo que você criou.

    az group delete --name MyResourceGroup

  2. Execute o comando az group list para confirmar se o grupo de recursos foi excluído.

    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 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 é consultar o guia de início rápido de telemetria que usa o SDK de Dispositivo do IoT do Azure para C. Opcionalmente, consulte um dos guias de início rápido de telemetria do Hub IoT disponíveis no idioma ou SDK de sua preferência.

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

Próxima etapa

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

  • Last updated on