Compartilhar via

Início Rápido: Gerenciar um único dispositivo IoT virtual usando a CLI do Azure

  • Artigo

Importante

Este documento não é mais atualizado e será removido. Para up-toinstruções sobre como experimentar cenários osConfig:

  1. Primeiro, siga as etapas em Criar um ambiente de laboratório osConfig (com Azure IoT) em 5 minutos
  2. Em seguida, experimente qualquer um dos cenários de: O que posso provisionar e gerenciar?

O objetivo deste Início Rápido é familiarizá-lo com a administração remota de dispositivos IoT/Edge por meio do OSConfig para IoT. Na Parte 1, você configurará um ambiente de teste, incluindo a criação de uma VM para atuar como um dispositivo IoT virtual. Na Parte 2, você executará várias ações de gerenciamento de dispositivos, por exemplo:

  • Recuperar remotamente o endereço IP do dispositivo
  • Testar remotamente a conectividade do ponto de extremidade da perspectiva do dispositivo
  • Reinicializar remotamente o dispositivo
  • e mais

Este Início Rápido usa um único dispositivo de exemplo. Para usar o OSConfig em escala, você usaria serviços de gerenciamento de dispositivos do Hub Iot como o plano de controle, em vez de comandos individuais da CLI do Azure.

Pré-requisitos

  1. Você precisará de uma conta do Azure com uma assinatura ativa. Se necessário, você pode criar uma conta paragratuito.
  2. Você usará o ambiente de do Azure Cloud Shell
    • OBSERVAÇÃO: se esta for a primeira vez que você usa o Azure Cloud Shell, o portal orientará você na criação de algum espaço de armazenamento antes de continuar. Isso é normal.
    • OBSERVAÇÃO: o Azure Cloud Shell já tem as ferramentas mais recentes da CLI do Azure e é conectado automaticamente à sua conta do Azure. Se você preferir usar seu próprio ambiente bash em vez do cloud shell, poderá instalar e configurar a CLI do Azure em seu próprio ambiente bash.
  3. Você precisará da extensão IOT do Azure para a CLI do Azure, que pode ser adicionada usando o seguinte comando:
az extension add --name azure-iot

captura de tela mostrando az extension add --name azure-iot

Verificando pré-requisitos

  • No do Azure Cloud Shell (ou em seu ambiente de bash alternativo), verifique se a CLI do Azure está conectado à conta do Azure e ao contexto de assinatura que você deseja usar.
az account show

captura de tela do comando: az account show

Se você precisar entrar com uma conta diferente ou alterar assinaturas, poderá usar os comandos az login e az account set.

Visão geral do ambiente de início rápido

Diagrama para contexto, mostrando a CLI do Azure sendo usada para criar o Hub IoT e a VM e sendo usada para usar o OSConfig

Parte 1: Configurar seu ambiente

1.1: Criar seus recursos de IoT do Azure

1.1.1: Definir um nome exclusivo para o Hub IoT

Você precisará criar um nome exclusivo para o Hub IoT, como "Início Rápido12345" ou "HelloWorld98765". Esse nome será usado repetidamente em comandos posteriores, portanto, vamos armazená-lo em uma variável bash, da seguinte maneira:

# In the following command replace <Your_Made_Up_Name_Here> 
# with your own preferred hub name, for example:
# MY_IOT_HUB_NAME="MyQuickStart54321"
MY_IOT_HUB_NAME="<Your_Made_Up_Name_Here>"

captura de tela do exemplo bash atribuindo o nome exclusivo escolhido para o Hub IOT à variável MY_IOT_HUB_NAME

1.1.2: Criar um grupo de recursos e um Hub IoT

az group create --resource-group QuickstartOSConfig --location westus
az iot hub create --resource-group QuickstartOSConfig --name "$MY_IOT_HUB_NAME" --query id

captura de tela do comando az group create

captura de tela do comando az iot hub create

Ponta

Se o comando az iot hub create... falhar com um erro de que o nome não estava disponível, isso significa que o nome escolhido já estava em uso em outro lugar no Azure. Para resolver isso, repita a etapa MY_IOT_HUB_NAME="<Your_Made_Up_Name_Here>" acima com um nome novo e mais exclusivo e tente o comando az iot hub create ... novamente.

Ponta

Não é incomum que o comando az iot hub create... leve alguns minutos para ser concluído.

1.1.3: Criar a ID do dispositivo e obter a cadeia de conexão do dispositivo

az iot hub device-identity create --hub-name "$MY_IOT_HUB_NAME" -d device01 --query deviceId
az iot hub device-identity connection-string show --hub-name "$MY_IOT_HUB_NAME" --device-id device01

captura de tela dos comandos az iot de exemplo

Ponta

Anote o valor de connectionString retornado pelo último comando (ele começa com HostName=). Você usará essa cadeia de conexão em uma etapa posterior.

1.2: Criar uma VM do Azure para atuar como o dispositivo IoT virtual

Use o comando a seguir para criar uma máquina virtual.

az vm create --resource-group QuickstartOSConfig --name device01 --image Canonical:UbuntuServer:18.04-lts:latest --admin-username azureuser --generate-ssh-keys --query publicIpAddress

captura de tela do comando az vm create

Ponta

Anote o endereço IP retornado pelo último comando. Você usará esse endereço na etapa a seguir.

1.3: Instalar o software cliente no dispositivo IoT virtual

1.3.1: Estabelecer de acesso de terminal ao dispositivo virtual

Os próximos comandos precisam executados na VM que você acabou de criar. Use o SSH para se conectar:

# In the following command, replace <public ip address from previous step> with
# the actual IP address. For example:
# ssh azureuser@1.2.3.4
ssh azureuser@<ip address from previous step>

captura de tela do comando ssh

Ponta

Seu cliente ssh pode exigir que você digite yes para continuar. Isso é normal.

Ponta

Antes de continuar, verifique se você está conectado ao dispositivo IoT virtual. O prompt de comando deve ter sido alterado de <your name>@azure: para azureuser@device01:. Se o prompt de comando não tiver sido alterado para azureuser@device01:, execute o comando ssh acima novamente.

1.3.2: No dispositivo virtual, instalar aziot-identity-service

sudo apt-get update
curl -sSL https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add
sudo apt-add-repository https://packages.microsoft.com/ubuntu/18.04/multiarch/prod
sudo apt-get update
sudo apt install -y aziot-identity-service

captura de tela dos comandos

captura de tela 2 dos comandos

1.3.3: No dispositivo virtual, aplicar a cadeia de conexão

Configure o dispositivo para autenticar no Azure IoT usando o comando a seguir. Você usará o valor da cadeia de conexão obtida anteriormente no Criar seus recursos de IoT do Azure.

sudo aziotctl config mp --connection-string "<your connection string>"
sudo aziotctl config apply

captura de tela dos comandos aziotctl

1.3.4: No dispositivo virtual, instalar o pacote OSConfig e observar que ele está em execução

sudo apt install -y osconfig
sudo systemctl status osconfig | grep --color=never Active

captura de tela do sudo apt install -y osconfig

1.2.5: Sair da sessão SSH

exit

captura de tela da saída da sessão SSH, retornando à sessão do Cloud Shell

Parte 2: Usar o OSConfig para IoT

Você conseguiu! Agora que o ambiente está preparado, podemos começar a usar o OSConfig para obter e definir a configuração e o estado no nível do host por meio do Hub IoT. No Azure Cloud Shell ou em seu computador, use os seguintes comandos da CLI do Azure para concluir cada exemplo.

2.1: Está tudo ligado?

Começaremos obtendo o Hub IoT do dispositivo deviceIde mostraremos que o OSConfig está ativo.

az iot hub query --hub-name "$MY_IOT_HUB_NAME" -q "select deviceId,moduleId,connectionState from devices.modules where deviceID='device01' and moduleId='osconfig'"

captura de tela do comando de consulta do hub iot

2.2: Obter o estado de rede do dispositivo, como endereços IP e servidores DNS, para qualquer dispositivo habilitado para OSConfig no Hub IoT

Há muitos casos de uso para relatar o estado da rede de dispositivos gerenciados. Por exemplo, talvez você precise do endereço IP local para conectar um fluxo de vídeo IP local Da mesma forma, convém relatar os servidores DNS em uso para solução de problemas ou para garantir que os dispositivos estejam usando a infraestrutura de rede esperada. O exemplo a seguir recupera os endereços IP e os servidores DNS atribuídos a cada adaptador de rede.

az iot hub query --hub-name "$MY_IOT_HUB_NAME" -q "select deviceId,properties.reported.Networking.NetworkConfiguration.IpAddresses,properties.reported.Networking.NetworkConfiguration.DnsServers from devices.modules where moduleId='osconfig'"

captura de tela da consulta az iot (adicional)

Ponta

As informações de IP retornadas são da perspectiva do dispositivo, correspondendo ao que você obteria executando ifconfig ou ip address localmente no dispositivo. O endereço IP público do Azure (usado anteriormente para SSH) é roteado por NAT fora da VM, portanto, ele não é visto aqui.

2.3: Configurar a política de telemetria do ADHS (Serviço de Integridade do Dispositivo) do Azure e verificar a conformidade

O ADHS é um agente de diagnóstico incluído em alguns dispositivos. A VM que você acabou de criar não tem o ADHS instalado, mas ainda podemos definir a política proativamente como um exemplo.

O primeiro comando define a propriedade desejada do gêmeo para ADHS como 2 (o que significa aceitação). O segundo comando compara as versões desejadas (definidas por você, o administrador) e relatadas (enviadas pelo dispositivo) da propriedade para verificar se o dispositivo recebeu e aplicou a política.

az iot hub module-twin update --hub-name "$MY_IOT_HUB_NAME" -d device01 -m osconfig --desired '{"Settings":{"__t":"c","DeviceHealthTelemetryConfiguration":2}}' > /dev/null
az iot hub query --hub-name "$MY_IOT_HUB_NAME" -q "select deviceId,properties.desired.Settings.DeviceHealthTelemetryConfiguration AS ADHSLevel_Desired,properties.reported.Settings.DeviceHealthTelemetryConfiguration.value AS ADHSLevel_Reported from devices.modules where moduleId='osconfig'"

captura de tela da consulta az iot (outro exemplo adicional)

2.4: Aplicar uma configuração personalizada (exemplo de fuso horário)

O recurso CommandRunner do OSConfig permite que você obtenha e defina quase tudo no dispositivo. Este exemplo define o fuso horário do sistema operacional do dispositivo como UTC. Impor um fuso horário uniforme em pontos de extremidade (independentemente de sua localização física) é uma prática comum para melhorar a manipulação de carimbo de data/hora em uma solução distribuída.

O comando da CLI do Azure a seguir informa ao OSConfig para definir o fuso horário usando timedatectle relatar o fuso horário resultante.

az iot hub module-twin update --hub-name "$MY_IOT_HUB_NAME" -d device01 -m osconfig --desired '{"CommandRunner":{"__t":"c","CommandArguments":{"CommandId":"my_timezone_config", "Action":3, "Arguments": "timedatectl set-timezone UTC; timedatectl | grep zone | tr -d '[:space:]'"}}}' --query "properties.desired.CommandRunner"

captura de tela do comando az iot hub module-twin update

A saída mostra que definimos o comando desejado no gêmeo. Para confirmar que funcionou, daremos uma etapa adicional. Primeiro, aguardaremos pelo menos 30 segundos dando tempo para o dispositivo receber o comando, processá-lo e atualizar o gêmeo com os resultados.

Tendo esperado pelo menos 30 segundos desde o comando anterior, use o seguinte para recuperar a saída:

az iot hub query --hub-name "$MY_IOT_HUB_NAME" -q "select deviceId,properties.reported.CommandRunner.CommandStatus from devices.modules where moduleId='osconfig'"

captura de tela da consulta az iot (exemplo de fuso horário)

2.5: Testar a conectividade do dispositivo (exemplo de ping)

Este exemplo usa o recurso CommandRunner junto com ping para testar a conectividade de rede da perspectiva do dispositivo.

az iot hub module-twin update --hub-name "$MY_IOT_HUB_NAME" -d device01 -m osconfig --desired '{"CommandRunner":{"__t":"c","CommandArguments":{"CommandId":"connectivity_test_1", "Action":3, "Arguments":"ping -c 2 example.com"}}}' --query "properties.desired.CommandRunner"

captura de tela do comando az iot hub module-twin update (exemplo de ping)

Assim como no exemplo anterior, a saída de az iot hub module-twin update mostra que definimos a propriedade de comando desejada no gêmeo e usaremos uma segunda etapa para recuperar os resultados.

Tendo esperado pelo menos 30 segundos desde o comando anterior, use o seguinte para recuperar os resultados:

az iot hub query --hub-name "$MY_IOT_HUB_NAME" -q "select deviceId,properties.reported.CommandRunner.CommandStatus from devices.modules where moduleId='osconfig'"

captura de tela da consulta az iot (exemplo de ping)

2.6: Reinicializar ou desligar usando ações predefinidas do CommandRunner

O exemplo a seguir reinicializa o dispositivo. Se você quiser desligar, altere Action: 1 para Action: 2 no valor de propriedade desejado.

az iot hub module-twin update --hub-name "$MY_IOT_HUB_NAME" -d device01 -m osconfig --desired '{"CommandRunner":{"__t":"c","CommandArguments":{"CommandId":"my_reboot_command", "Action":1}}}' --query "properties.desired.CommandRunner"

captura de tela da atualização do módulo gêmeo do hub iot (exemplo de reinicialização)

Limpar recursos

Se você não pretende manter nenhum dos recursos, poderá excluí-los excluindo o grupo de recursos que você criou anteriormente.

az group delete --resource-group QuickstartOSConfig

captura de tela az group delete

Próximas etapas

  • Este guia usou apenas um dispositivo para começar rapidamente. Para configurar dispositivos em escala, você pode usar o OSConfig junto com de Gerenciamento de Dispositivos do Hub IoT com o OSConfig.
  • Para saber mais sobre OSConfig, consulte: documentação do OSConfig.