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

  • Artigo

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, você usa 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 de dispositivo. Este artigo mostra um fluxo de trabalho básico para desenvolvedores que usam a CLI para interagir com um aplicativo do 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 neste início rápido 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 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 Instalar a CLI do Azure.

Inicie sessão no portal do Azure

Inicie sessão no portal do Azure.

Independentemente de você executar a CLI localmente ou no Cloud Shell, mantenha o portal aberto em seu navegador. Você pode usá-lo mais tarde neste início rápido.

Inicie o Cloud Shell

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

Para iniciar o Cloud Shell:

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

    Botão Cloud Shell do 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. Selecione seu ambiente CLI preferido na lista suspensa Selecionar ambiente . Este guia de início rápido 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.

    Selecionar ambiente CLI

Preparar duas sessões de CLI

Em seguida, você prepara duas sessões da CLI do Azure. Se você estiver usando o Cloud Shell, executará 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 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 início rápido, cole-o em sua sessão de shell e execute-o.

A CLI do Azure exige que você esteja conectado à 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, esse início rápido não precisa de 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 para CLI do Azure ao shell da CLI. A Extensão IOT adiciona comandos específicos do Hub IoT, IoT Edge e DPS (Serviço de Provisionamento de Dispositivos) ao Azure CLI.

    az extension add --name azure-iot

    Depois de instalar a extensão IOT do Azure, não é necessário instalá-la novamente em nenhuma sessão do 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-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.

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

    Abra uma nova sessão do 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 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 chamado MyResourceGroup no local eastus .

    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.

    YourIotHubName. Substitua esse espaço reservado e as chaves ao redor no comando a seguir, usando o nome escolhido para seu hub IoT. Um nome de hub IoT deve ser globalmente exclusivo no Azure. Use o nome do hub IoT no restante deste início rápido onde quer que você veja o espaço reservado.

    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 espaço reservado abaixo pelo nome que você escolheu para 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.

    YourIotHubName. Substitua este espaço reservado abaixo pelo nome que você escolheu para 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.

    YourIotHubName. Substitua este espaço reservado abaixo pelo nome que você escolheu para 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 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 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 reiniciá-lo:

    YourIotHubName. Substitua este espaço reservado abaixo pelo nome que você escolheu para seu 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 . Este comando envia uma mensagem da nuvem para o dispositivo do seu hub IoT para o dispositivo simulado. A mensagem inclui uma cadeia de caracteres e dois pares chave-valor.

    YourIotHubName. Substitua este espaço reservado abaixo 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}

    Opcionalmente, você pode enviar mensagens da nuvem para o dispositivo usando o portal do Azure. Para fazer isso, navegue até a página de 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ã de 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.

    YourIotHubName. Substitua este espaço reservado abaixo pelo nome que você escolheu para 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 de um dispositivo simulado exibindo a saída depois que um método foi 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 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 abaixo. O PowerShell exige que você escape dos caracteres na carga JSON útil.

    YourIotHubName. Substitua este espaço reservado abaixo pelo nome que você escolheu para 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 o dispositivo simulado gera 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.

    YourIotHubName. Substitua este espaço reservado abaixo pelo nome que você escolheu para 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

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

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

  1. No menu de navegação esquerdo do portal, selecione Todos os Recursos. Esta 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 de visão geral do hub.

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

    Métricas de mensagens do Hub IoT

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

  5. No campo Metric Namespace, selecione Iot Hub Standard Metrics.

  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.

    Exibir métricas do Hub IoT do Azure

  8. Opcionalmente, use a lista suspensa Métrica para exibir outras métricas em seu dispositivo simulado. Por exemplo, entregas de mensagens C2d concluídas ou Total de dispositivos (visualização).

Clean up resources (Limpar recursos)

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

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:

  1. Execute o comando az group delete . Este 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 que o grupo de recursos foi excluído.

    az group list

Próximos passos

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 você for um desenvolvedor de dispositivos, a próxima etapa sugerida é ver o início rápido de telemetria que usa o SDK de Dispositivo IoT do Azure para C. Opcionalmente, consulte um dos artigos de início rápido de telemetria do Hub IoT do Azure disponíveis em 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