Compartir a través de

Configuración personalizada e informes con Azure IoT y OSConfig

  • Artículo

Importante

La versión 1.0.3 (publicada el 28 de junio de 2022) incluye cambios importantes en los nombres de miembros que pueden afectar a los usuarios existentes. Para obtener más información, vea: Los nombres de miembros pasan de PascalCase a camelCase en la versión 1.0.3.

Este artículo está diseñado para admitir personas que aprovisionan o administran dispositivos con Azure IoT. Si eso no suena como usted, considere la posibilidad de echar un vistazo a la documentación de Audiences for OSConfig.

La característica CommandRunner -->RunCommand le permite intercambiar cierta simplicidad para obtener flexibilidad. Cuando necesite, puede colocar un nivel de abstracción para realizar informes y configuraciones personalizados.

Ejemplos comunes de configuración y informes personalizados

  • Comprobación de la conectividad del dispositivo a puntos de conexión clave
  • Comprobación de que se están ejecutando demonios específicos
  • Depuración o solución de problemas de dispositivos, por ejemplo, mediante la recopilación de archivos de registro y su carga en el almacenamiento en la nube
  • Configure todos los dispositivos para usar la zona horaria deseada al registrar datos, generar marcas de tiempo, etc.
  • Informe sobre (o configure) sus propios componentes de dispositivo únicos que OSConfig nunca sabría de lo contrario.
  • Las posibilidades son infinitas, casi cualquier tarea que pueda realizar en un shell para un dispositivo, puede hacerlo con Azure IoT y OSConfig CommandRunner para flotas de dispositivos.

Sugerencia

Este artículo se centra en ejemplos prácticos con una explicación mínima. Para obtener información técnica sobre CommandRunner, consulte : Interacción con la característica CommandRunner de OSConfig y Azure IoT.

Ejemplos de casos de uso

Estos ejemplos pueden servir como puntos de partida para adaptarse a su entorno único.

Cada ejemplo incluye pasos y capturas de pantalla para trabajar en la Azure Portal y para trabajar en Bash con la CLI de Azure.

Cada ejemplo también incluye variaciones para un dispositivo (por ejemplo, un escenario de solución de problemas) o para muchos dispositivos (por ejemplo, un escenario de aprovisionamiento o informes de configuración).

Qué esperar:

En las instrucciones de un solo dispositivo, leerá y escribirá las propiedades notificadas y deseadas directamente en el gemelo OSConfig para un dispositivo. En las instrucciones a escala, usará IoT Hub Configuraciones (también conocidas como Administración de dispositivos automática o ADM) para insertar propiedades deseadas en muchos gemelos y usar IoT Hub Consultas (de forma independiente o asociadas a configuraciones como métricas) para observar los resultados procedentes de los dispositivos.

Requisitos previos para los ejemplos siguientes

Si usa este artículo como referencia (por ejemplo, está aquí para copiar un nombre de propiedad), no hay requisitos previos.

Si desea probar los ejemplos en sistemas activos (recomendado), haga lo siguiente:

  1. Necesitará una cuenta de Azure con un IoT Hub

    En este artículo se da por supuesto cierta familiaridad con IoT Hub y herramientas relacionadas. Por ejemplo, se supone que está familiarizado con la creación de ioT Hubs y la conexión de dispositivos. Si prefiere una introducción paso a paso más prescriptiva para instalar y usar OSConfig desde cero, consulte Inicio rápido: Administración de un único dispositivo IoT virtual mediante la CLI de Azure en su lugar.

  2. Necesitará al menos un dispositivo Linux con el agente OSConfig instalado y conectado a Azure IoT.

    Para obtener más información, vea Cómo y dónde instalar el agente OSConfig para Linux.

  3. Usará Azure Portal o la CLI de Azure para interactuar con los dispositivos a través de la IoT Hub

    Para conocer más pasos, elija su experiencia preferida:

  1. Asegúrese de que ha iniciado sesión en Azure Portal y puede acceder a la página Información general de la IoT Hub captura de pantalla que muestra IoT Hub y dispositivos desde Azure Portal

Sugerencia

Hay dos cosas que debe saber sobre el comportamiento de CommandRunner para tener éxito con estos ejemplos:

  • Como se muestra en los ejemplos, cada nueva solicitud debe incluir un nuevo valor para ( commandId puede ser cualquier cadena, por ejemplo, "MyCmd01", "MyCmd02").
  • El proceso es asincrónico, por lo que los resultados no están disponibles de forma instantánea. El procedimiento más sencillo es esperar aproximadamente un minuto después de iniciar una solicitud CommandRunner. Después de ese minuto, sin ningún paso adicional por su parte, los resultados están disponibles en properties.reported.CommandRunner.commandStatus. Para más información sobre el comportamiento de actualización, las actualizaciones de estado asincrónico, etc., consulte : Interacción con la característica CommandRunner de OSConfig y Azure IoT.

Ejemplo 1. Comprobación de la conectividad del dispositivo a puntos de conexión específicos

En este ejemplo, pedimos a los dispositivos que hagan ping www.github.com 3 veces. Observamos el código de salida del ping (correcto o incorrecto) y podemos observar la salida textual del comando ping.

  1. En la página del portal del IoT Hub, vaya al módulo gemelo OSConfig para el dispositivo que desea administrar. A continuación, agregue lo siguiente a la properties.desired sección (seguida de una coma para separarla del siguiente elemento de properties.desired).

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

    Captura de pantalla que muestra el contenido gemelo deseado para un comando ping mediante el módulo OSConfig para un único dispositivo desde Azure Portal

  2. Puede comprobar la conectividad del dispositivo comprobando la respuesta al comando ping desde el propio módulo gemelo OSConfig. Desplácese hacia abajo del módulo gemelo para buscar las propiedades notificadas de CommandRunner. Buscar resultCode: 0 que indica que el comando se ha realizado correctamente y textResult que muestra la salida del comando ping .

    Captura de pantalla que muestra el contenido del gemelo notificado para un comando ping mediante el módulo OSConfig para un único dispositivo desde Azure Portal

Ejemplo 2. Obtener contenido de /etc/ssh/sshd_config

En este ejemplo, usamos CommandRunner para capturar el contenido de un archivo de cada dispositivo. En este ejemplo no cargamos explícitamente el archivo en ningún servicio de almacenamiento en la nube, sino simplemente capturamos su contenido en el gemelo.

Importante

Las actualizaciones de propiedades gemelas están limitadas a 4 KB. El enfoque que se muestra aquí captura el contenido del archivo (de cat) insertado en el gemelo. Para archivos muy pequeños, este enfoque tiene la ventaja de no requerir ningún servicio de almacenamiento externo ni credenciales. Para archivos más grandes, este enfoque no es aplicable. En su lugar, incluiría lógica en el script o comando para cargar el archivo en el almacenamiento local o en la nube de su elección. Por ejemplo, puede conectarse a un recurso compartido cifs y copiar el archivo allí o insertar el contenido del archivo en Azure Storage.

  1. En la página del portal de la IoT Hub, vaya al gemelo OSConfig del dispositivo que desea administrar. A continuación, agregue lo siguiente a la properties.desired sección (seguido de una coma para separarla del siguiente elemento de properties.desired). Puede reemplazar el nombre de archivo que prefiera en el campo argumentos siguiente.

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

    Captura de pantalla que muestra cómo establecer la propiedad deseada del módulo gemelo OSConfig para leer el contenido de un archivo desde un único dispositivo mediante el módulo OSConfig de Azure Portal

  2. Puede ver el contenido del archivo desde el propio módulo gemelo. Desplácese hacia abajo en el módulo gemelo para buscar commandStatus en las propiedades notificadas de CommandRunner; aquí verá esto en textResult. Buscar resultCode: 0 que indica que el comando se ha realizado correctamente y textResult que mostrará el contenido del archivo deseado.

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

    Captura de pantalla que muestra el módulo gemelo OSConfig que muestra el contenido del archivo solicitado desde un único dispositivo desde Azure Portal

Ejemplo 3. Implementación de un script en línea simple para establecer la zona horaria en UTC e informar sobre la zona horaria

En este ejemplo se muestra un caso de uso sencillo en el que tanto el script como los resultados se pueden controlar en línea como parte del gemelo. En el ejemplo siguiente se establecerá la zona horaria en UTC y, a continuación, se consultará la zona horaria una vez establecida.

  1. En la página del portal de la IoT Hub, vaya al gemelo OSConfig para el dispositivo que desea administrar y agregue lo siguiente a la properties.desired sección, seguido de una coma para separarla del siguiente elemento de properties.desired. action=3 a continuación especifica la acción RunCommand .

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

    Captura de pantalla que muestra cómo establecer la propiedad deseada para actualizar la zona horaria en un dispositivo mediante el módulo OSConfig desde Azure Portal

  2. Una vez ejecutado el comando, desplácese hacia abajo hasta el módulo gemelo para buscar commandStatus en las propiedades notificadas de CommandRunner, aquí verá que textResult muestra el conjunto de zona horaria actual en el dispositivo.

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

    Captura de pantalla que muestra la respuesta de establecer el comando de zona horaria en un único dispositivo desde Azure Portal

Ejemplo 4. Implementación de un script de informes personalizado desde un repositorio en línea

En este ejemplo se muestra la llamada a un script ubicado fuera del gemelo. Por ejemplo, puede colocar los scripts en GitHub. Este patrón puede surgir por necesidad (el script es demasiado grande para el gemelo) o fuera de preferencia. El comando del gemelo es un contenedor sencillo. Descarga el script principal y lo ejecuta.

Importante

Para admitir este documento, hemos publicado un script de ejemplo. Este script de ejemplo se proporciona como un stand-in para su propio script en GitHub o en cualquier otro lugar. Recopila algunos puntos de datos del dispositivo, como una marca de tiempo, el estado del demonio y el espacio libre en disco. Debe inspeccionar scripts desde Internet, incluido este, antes de ejecutarlos en los dispositivos.

  1. En la página del portal de la IoT Hub, vaya al gemelo OSConfig para el dispositivo que desea administrar y agregue lo siguiente a la properties.desired sección, seguido de una coma para separarla del siguiente elemento de 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 pantalla que muestra cómo actualizar el contenido del gemelo para ejecutar un script personalizado en un único dispositivo mediante Azure Portal

  2. Desplácese hacia abajo del módulo gemelo para buscar CommandRunner -->commandStatus en la sección de propiedades notificadas del gemelo. Buscar resultCode: 0 que indica que el comando se ha realizado correctamente y textResult que muestra la salida del script ejecutado. A continuación se muestra una salida de ejemplo tomada del gemelo OSConfig de un 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 pantalla que muestra cómo comprobar el contenido del gemelo después de ejecutar un script personalizado en un único dispositivo mediante Azure Portal

Pasos siguientes

Para obtener información general sobre los escenarios y funcionalidades de OSConfig, consulte:

Para obtener ejemplos prácticos específicos, consulte: