Compartilhar via

Configuração e relatórios personalizados com o Azure IoT e OSConfig

  • Artigo

Importante

A versão 1.0.3 (publicada em 28 de junho de 2022) inclui alterações significativas nos nomes dos membros que podem afetar os usuários existentes. Para obter mais informações, consulte: Transição de nomes de membro de PascalCase para camelCase na versão 1.0.3

Este artigo foi projetado para dar suporte a pessoas que provisionam ou gerenciam dispositivos com o Azure IoT. Se isso não soar como você, considere dar uma olhada na documentação do Audiences for OSConfig.

O recurso CommandRunner -->RunCommand permite que você troque alguma simplicidade para obter flexibilidade. Quando precisar, você pode descartar um nível de abstração para executar relatórios e configurações personalizados.

Exemplos comuns de relatórios personalizados e configuração

  • Verificar a conectividade do dispositivo com pontos de extremidade de chave
  • Verificar se daemons específicos estão em execução
  • Depurar ou solucionar problemas de dispositivos, por exemplo, coletando arquivos de log e carregando-os no armazenamento em nuvem
  • Configure todos os dispositivos para usar o fuso horário desejado ao registrar dados em log, gerar carimbos de data/hora etc.
  • Relatar (ou configurar) seus próprios componentes de dispositivo exclusivos sobre os quais o OSConfig nunca saberia
  • As possibilidades são infinitas, quase qualquer tarefa que você possa fazer em um shell para um dispositivo, você pode fazer com o Azure IoT e o OSConfig CommandRunner para frotas de dispositivos

Dica

Este artigo se concentra em exemplos práticos com explicação mínima. Para obter informações técnicas sobre CommandRunner, consulte: Como interagir com o recurso CommandRunner do OSConfig e do Azure IoT.

Exemplos de casos de uso

Esses exemplos podem servir como pontos de partida para você se adaptar ao seu ambiente exclusivo.

Cada exemplo inclui etapas e capturas de tela para trabalhar no portal do Azure e para trabalhar em bash com a CLI do Azure.

Cada exemplo também inclui variações para um dispositivo (por exemplo, um cenário de solução de problemas) ou para muitos dispositivos (por exemplo, um cenário de provisionamento de configuração ou relatório).

O que esperar:

Nas instruções de dispositivo único, você lerá e gravará as propriedades relatadas e desejadas diretamente no gêmeo OSConfig para um dispositivo. Nas instruções em escala, você usará Hub IoT Configurações (também conhecidas como Gerenciamento de Dispositivos Automática ou ADM) para enviar propriedades desejadas por push para muitos gêmeos e usar Hub IoT Consultas (independentemente ou anexadas às Configurações como Métricas) para observar os resultados provenientes dos dispositivos.

Pré-requisitos para os exemplos a seguir

Se você estiver usando este artigo para referência (por exemplo, você está aqui para copiar um nome de propriedade), não há pré-requisitos.

Se você quiser experimentar os exemplos em sistemas dinâmicos (recomendado), então:

  1. Você precisará de uma conta do Azure com um Hub IoT

    Este artigo pressupõe alguma familiaridade com Hub IoT e ferramentas relacionadas. Por exemplo, ele pressupõe que você esteja confortável criando Hubs IoT e anexando dispositivos. Se você preferir uma introdução passo a passo mais prescritiva à instalação e ao uso do OSConfig do zero, consulte: Início Rápido: Gerenciar um único dispositivo IoT virtual usando a CLI do Azure .

  2. Você precisará de pelo menos um dispositivo Linux com o agente OSConfig instalado e conectado ao Azure IoT.

    Para obter mais informações, consulte: Como e onde instalar o agente OSConfig para Linux.

  3. Você usará o Portal do Azure ou a CLI do Azure para interagir com os dispositivos por meio de seu Hub IoT

    Para outras etapas, escolha sua experiência preferida:

  1. Verifique se você está conectado ao Portal do Azure e pode acessar a página visão geral do Hub IoT Captura de tela mostrando Hub IoT e dispositivos do Portal do Azure

Dica

Há duas coisas que você deve saber sobre o comportamento do CommandRunner para ter êxito usando estes exemplos:

  • Conforme demonstrado nos exemplos, cada nova solicitação deve incluir um novo valor para commandId (pode ser qualquer cadeia de caracteres, por exemplo, "MyCmd01", "MyCmd02").
  • O processo é assíncrono, portanto, os resultados não estão disponíveis instantaneamente. O procedimento mais simples é aguardar cerca de um minuto depois de iniciar uma solicitação CommandRunner. Após esse minuto, sem etapas extras de sua parte, os resultados estarão disponíveis em properties.reported.CommandRunner.commandStatus. Para saber mais sobre o comportamento de atualização, atualizações de status assíncrono, etc., consulte: Como interagir com o recurso CommandRunner do OSConfig e do Azure IoT.

Exemplo 1. Verificar a conectividade do dispositivo com pontos de extremidade específicos

Neste exemplo, pedimos que os dispositivos façam ping www.github.com três vezes. Observamos o código de saída do ping (êxito ou falha) e podemos observar a saída textual do comando ping.

  1. Na página do portal do seu Hub IoT, navegue até o gêmeo do módulo OSConfig para o dispositivo que você deseja gerenciar. Em seguida, adicione o seguinte à properties.desired seção (seguido por uma vírgula para separá-la do próximo item).properties.desired

      "CommandRunner": {
             "__t": "c",
             "commandArguments": {
                 "commandId": "pingcmd",
                 "arguments": "ping -c 3 www.github.com",
                 "timeout": 120,
                 "singleLineTextResult": false,
                 "action": 3
             }
         }

    Captura de tela mostrando o conteúdo gêmeo desejado para um comando ping usando o módulo OSConfig para um único dispositivo do Portal do Azure

  2. Você pode verificar a conectividade do dispositivo verificando a resposta ao comando ping do módulo gêmeo OSConfig em si. Role para baixo o módulo gêmeo para encontrar as propriedades relatadas para CommandRunner. Verificar o resultCode: 0 que indica que o comando foi bem-sucedido e textResult que mostra a saída do comando ping .

    Captura de tela mostrando conteúdo gêmeo relatado para um comando ping usando o módulo OSConfig para um único dispositivo do Portal do Azure

Exemplo 2. Obter conteúdo de /etc/ssh/sshd_config

Neste exemplo, usamos CommandRunner para capturar o conteúdo de um arquivo de cada dispositivo. Neste exemplo, não carregamos explicitamente o arquivo em nenhum serviço de armazenamento em nuvem, mas simplesmente capturamos seu conteúdo no gêmeo.

Importante

As atualizações de propriedade gêmeo são limitadas a 4KB. A abordagem mostrada aqui captura o conteúdo do arquivo (de cat) embutido no gêmeo. Para arquivos muito pequenos, essa abordagem tem o benefício de não exigir nenhum serviço de armazenamento ou credenciais externos. Para arquivos maiores, essa abordagem não é aplicável. Em vez disso, você incluiria a lógica em seu script/comando para carregar o arquivo no local ou no armazenamento em nuvem de sua escolha. Por exemplo, você pode se conectar a um compartilhamento cifs e copiar o arquivo lá ou enviar o conteúdo do arquivo por push para o Armazenamento do Azure.

  1. Na página do portal do seu Hub IoT, navegue até o gêmeo OSConfig para o dispositivo que você deseja gerenciar. Em seguida, adicione o seguinte à properties.desired seção (seguido por uma vírgula para separá-la do próximo item).properties.desired Você pode substituir o nome de arquivo de sua escolha no campo de argumentos abaixo.

      "CommandRunner": {
             "__t": "c",
             "commandArguments": {
                 "commandId": "sshdconfig",
                 "arguments": "cat /etc/ssh/sshd_config",
                 "timeout": 30,
                 "singleLineTextResult": false,
                 "action": 3
             }
         }

    Captura de tela mostrando como definir a propriedade desejada do módulo gêmeo OSConfig para ler o conteúdo do arquivo de um único dispositivo usando o módulo OSConfig do Portal do Azure

  2. Você pode ver o conteúdo do arquivo do módulo gêmeo em si. Role para baixo o módulo gêmeo para localizar commandStatus em propriedades relatadas para CommandRunner, aqui você verá isso no textResult. Verifique o resultCode: 0 que indica que o comando foi bem-sucedido e textResult que mostrará o conteúdo do arquivo desejado.

    "CommandRunner": {
             "__t": "c",
             "commandStatus": {
                 "commandId": "sshdconfig",
                 "resultCode": 0,
                 "textResult": "<sshd_config_file_contents>",
                 "currentState": 2
             }
          }

    Captura de tela mostrando o módulo gêmeo OSConfig que mostra o conteúdo do arquivo solicitado de um único dispositivo do Portal do Azure

Exemplo 3. Implantar um script embutido simples para definir o fuso horário como UTC e relatar o fuso horário

Este exemplo ilustra um caso de uso simples em que o script e os resultados podem ser tratados embutidos como parte do gêmeo. O exemplo aqui definirá o fuso horário como UTC e, em seguida, consultará o fuso horário depois de definido.

  1. Na página do portal do seu Hub IoT, navegue até o gêmeo OSConfig para o dispositivo que você deseja gerenciar e adicione o seguinte à properties.desired seção, seguido por uma vírgula para separá-lo do próximo item em properties.desired. action=3 abaixo especifica a ação RunCommand .

    "CommandRunner": {
   "__t": "c",
   "commandArguments": {
      "commandId": "settimezonecmd",
      "arguments": "timedatectl set-timezone Etc/UTC | timedatectl | grep Time",
      "timeout": 30,
      "singleLineTextResult": false,
      "action": 3
   }
}

    Captura de tela mostrando como definir a propriedade desejada para atualizar o fuso horário em um dispositivo usando o módulo OSConfig do Portal do Azure

  2. Depois que o comando for executado, role para baixo o módulo gêmeo para encontrar commandStatus sob as propriedades relatadas para CommandRunner, aqui você verá o textResult exibir o conjunto de fuso horário atual no dispositivo.

    "CommandRunner": {
   "__t": "c",
   "commandStatus": {
      "commandId": "settimezonecmd",
      "resultCode": 0,
      "textResult": " Time zone: Etc/UTC (UTC, +0000)",
      "currentState": 2
   }
}

    Captura de tela mostrando a resposta da configuração do comando de fuso horário em um único dispositivo do Portal do Azure

Exemplo 4. Implantar um script de relatório personalizado de um repositório online

Este exemplo ilustra a chamada de um script localizado fora do gêmeo. Por exemplo, você pode colocar seus scripts no GitHub. Esse padrão pode surgir por necessidade (o script é muito grande para gêmeos) ou fora de preferência. O comando no gêmeo é um wrapper simples. Ele baixa o script principal e o executa.

Importante

Para dar suporte a este documento, publicamos um script de exemplo. Este script de exemplo é fornecido como um stand-in para seu próprio script no GitHub ou em outro lugar. Ele coleta alguns pontos de dados do dispositivo, incluindo um carimbo de data/hora, status de daemon e espaço livre em disco. Você deve inspecionar scripts da Internet, incluindo este, antes de executá-los em seus dispositivos.

  1. Na página do portal do Hub IoT, navegue até o gêmeo OSConfig para o dispositivo que você deseja gerenciar e adicione o seguinte à properties.desired seção, seguido por uma vírgula para separá-lo do próximo item em properties.desired.

    "CommandRunner": {
    "__t": "c",
   "commandArguments": {
      "commandId": "runcustomscript",
      "arguments": "curl -s -L https://learn.microsoft.com/azure/osconfig/samples/report-multiple-datapoints-from-device.sh | tr -d \r| bash",
      "timeout": 60,
      "singleLineTextResult": false,
      "action": 3
   }
}

    Captura de tela mostrando como atualizar o conteúdo gêmeo para executar um script personalizado em um único dispositivo usando o Portal do Azure

  2. Role para baixo o módulo gêmeo para encontrar CommandRunner -->commandStatus na seção de propriedades relatadas do gêmeo. Verifique se há resultCode: 0 que indica que o comando foi bem-sucedido e textResult que mostra a saída do script executado. Veja a seguir a saída de exemplo obtida do gêmeo OSConfig de um dispositivo:

    "CommandRunner": {
   "__t": "c",
   "commandStatus": {
      "commandId": "runcustomscript",
      "resultCode": 0,
      "textResult": "+TIMESTAMP: 'Fri Jul  8 19:01:15 UTC 2022'  +DAEMON_STATUS: 'Active: active (running) since Mon 2022-06-27 19:02:46 UTC; 1 weeks 3 days ago'  +FREE_SPACE: '/dev/sda1       30309264 8811724  21481156  30% /'"
      "currentState": 2
   },
}

    Captura de tela mostrando como verificar o conteúdo gêmeo depois que um script personalizado é executado em um único dispositivo usando o Portal do Azure

Próximas etapas

Para obter uma visão geral dos cenários e funcionalidades do OSConfig, consulte:

Para obter exemplos práticos específicos, consulte: