Compartir a través de

Interacción con la característica CommandRunner de OSConfig y Azure IoT

  • Artículo

La mayoría de las propiedades de dispositivo expuestas por OSConfig son discretas y abstraidas de los detalles de implementación. Por ejemplo, cuando se usa HostName.desiredName para establecer el nombre de host de un dispositivo, no es necesario preocuparse por el tipo del sistema operativo, sobre las dependencias del entorno de ejecución de scripting o sobre los matices de tiempo de ejecución.

A veces, sin embargo, es posible que desee cambiar la simplicidad de la flexibilidad. Por ejemplo:

  • Debe recuperar información personalizada del dispositivo, como el deseo de informar sobre los resultados de ping example.com desde la perspectiva del dispositivo.
  • Debe configurar algo en el dispositivo donde no hay ninguna propiedad OSConfig deseada o grabable existente.

La característica CommandRunner de OSConfig permite la configuración personalizada y los informes a través de comandos o scripts de shell. También incluye ciertas acciones predefinidas (apagado, reinicio) que no requieren ningún scripting.

Sugerencia

En este artículo de referencia se describen los conceptos de CommandRunner, el modelo de interacción, etc. Para obtener ejemplos de uso concretos, consulte:

El modelo de interacción y las propiedades o campos clave

Resumen del modelo de interacción

Aunque es posible usar más matices (y se describe más adelante en este artículo), el modelo de interacción principal es sencillo:

  • Para iniciar una solicitud de comando, escriba en el gemelo deseado commandArguments .
  • Para obtener los resultados, lea los informes commandStatus del gemelo.

Diagrama que muestra commandArguments y commandStatus

Importante

Las cargas que se muestran en este diagrama se quitan para resaltar el flujo de entrada y salida. Para obtener el modelo de objetos completo, incluidos los miembros necesarios que no se muestran aquí, vea: El modelo de objetos completo

El identificador de ida y vuelta es: commandId

En el diagrama anterior, tenga en cuenta que tanto como commandArgumentscommandStatus incluyen un campo denominado commandId. Este es el identificador de ida y vuelta que vincula la solicitud y el resultado a lo largo de esta operación asincrónica.

El autor de la llamada (cadena de herramientas de administrador o administrador) elige el valor commandId.

Sugerencia

commandId es necesario en commandArguments. Los autores de llamadas suelen usar uno de estos patrones al elegir valores:

  • Valores monotonicos como "1" (para la primera solicitud), "2" (para la segunda solicitud), etc. o valores descriptivos como "my_ping_command"

    Estas son adecuadas para la exploración ad hoc; no requieren planeación y se pueden escribir fácilmente al editar contenido gemelo.

  • Valores generados automáticamente de alta entropía, como UUID

    Estos son adecuados para el uso mediante programación a gran escala en el que un back-end de soluciones en la nube creará y realizará un seguimiento de los valores mediante programación.

Un nuevo valor de commandId en commandArguments indica que se trata de una nueva solicitud. En el contexto del gemelo de un único dispositivo, rellenar un nuevo commandId es aproximadamente análogo a presionar "Entrar" en un entorno de shell.

commandId también permite realizar un seguimiento de varias solicitudes. CommandRunner en cada dispositivo puede recibir (y notificar el estado en) varias solicitudes a lo largo del tiempo. Mientras tanto, los commandArguments componentes y commandStatus de cada dispositivo gemelo solo pueden describir una solicitud en cualquier momento. commandId es el identificador de ida y vuelta que permite al autor de la llamada comprender (y controlar) qué solicitud anterior se describe actualmente en commandStatus. En efecto, commandStatus comunica "para la solicitud en la que el identificador era "foo", el estado es <...>".

¿Cuándo se commandStatus actualiza?

Hay dos desencadenadores para CommandRunner en el dispositivo para actualizar commandStatus.

  1. Actualización en segundo plano

    commandStatus se actualiza a intervalos regulares (el valor predeterminado es de 30 segundos). De forma predeterminada, esta actualización en segundo plano hace que represente el estado de la solicitud más reciente.

    En la práctica, esto significa que después de enviar una solicitud a través de commandArguments, puede esperar ver el estado correspondiente en commandStatus después de aproximadamente 30-60 segundos.

  2. refreshCommandStatus

    refreshCommandStatus es un mecanismo que aborda dos casos de uso avanzados:

    1. Ha emitido varias solicitudes a lo largo del tiempo a través commandArgumentsde y desea ver el estado de una solicitud específica, no la solicitud más reciente.
    2. No desea esperar a la actualización en segundo plano, aunque solo esté interesado en la solicitud más reciente.

    Para desencadenar este mecanismo, consulte la documentación del modelo de objetos siguiente para commandArguments.

Procedimientos recomendados para la configuración personalizada e informes con CommandRunner

  1. Consideraciones de tamaño

    En el caso de comandos o scripts cortos y salidas cortas, puede trabajar directamente en línea a través del gemelo. Este enfoque tiene ventajas, especialmente teniendo ninguna dependencia de red o autenticación fuera de IoT Hub. La principal desventaja de este enfoque es que las entradas (incluido el texto del script o los comandos) y las salidas (incluida cualquier salida de consola capturada) están limitadas a 4 KB.

    Para scripts más largos, puede almacenar el script en otro lugar (como GitHub) y llamarlo desde un comando contenedor mínimo que pase a OSConfig a través del gemelo. Para obtener ejemplos, consulte: Configuración personalizada e informes con Azure IoT y OSConfig. Independientemente del tamaño, es posible que también prefiera administrar los scripts en GitHub o similares, con contenido gemelo simplemente apuntando a ellos.

    En el caso de los scripts o comandos cuya salida de consola es demasiado grande para el gemelo, puede incluir lógica en el script para enviar resultados al almacenamiento local o en la nube en lugar de a stdout. Para obtener ejemplos, consulte: Configuración personalizada e informes con Azure IoT y OSConfig.

  2. Uso de comandos o scripts independientes y no interactivos

    Menos viajes de ida y vuelta son mejores, un viaje de ida y vuelta es mejor. OSConfig y CommandRunner están optimizados para la interactividad de escala. Aunque es posible usar CommandRunner en serie (un comando después de otro, similar a un terminal sincrónico activo), la experiencia no es óptima. No hay ninguna manera de controlar los mensajes de shell interactivos, debe asignar una commandId a cada solicitud, debe esperar a la sincronización de gemelos, etc.

    En su lugar, piense en CommandRunner como una manera de lograr la configuración personalizada y los informes a escala. Puede distribuir de forma asincrónica un script no interactivo (o una acción predefinida como reiniciar) a un dispositivo o millones de dispositivos, y puede informar sobre los resultados incluso cuando evolucionan con el tiempo (a medida que los nuevos dispositivos se unen a la flota, por ejemplo).

    En otras palabras, supongamos que necesita ejecutar cuatro comandos en todos los dispositivos Ubuntu 20.04 actuales y futuros en España. No piense en eso como 4 usos secuenciales discretos de CommandRunner, piense en él como un único uso de CommandRunner donde la carga contiene los cuatro comandos. Mientras tanto, un flujo de trabajo en la nube, como IoT Hub Configuraciones, puede garantizar que se distribuya a todos los dispositivos actuales y futuros que deben estar en el ámbito.

Modelo de objetos completo

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.

La siguiente información se aplica a las vistas deseadas o notificadas sin formato del modelo de objetos, así como a las vistas mejoradas de DTDL. Para obtener más información, consulte Qué usuarios de OSConfig necesitan saber sobre las cadenas de herramientas "sin formato deseadas o notificadas" frente a las cadenas de herramientas "mejoradas de DTDL".

commandArguments (establecido por administrador)

  • Descripción: la entrada del administrador desencadena una nueva solicitud de comando o desencadena la actualización de commandStatus.

  • Ruta de acceso: properties.desired.CommandRunner.commandArguments (CommandRunner componente -->commandArguments propiedad grabable)

  • Miembros

    Nombre Tipo Notas
    commandId string • Identificador de solicitud especificado por el autor de la llamada; ver más arriba para obtener información general
    • commandArguments se omite cuando commandId está en blanco
    • Para la interacción entre commandId y action, consulte lo siguiente:
    action enum/int El siguiente debe acoplarse con un nuevo valor de commandId:
    • 1 (reinicio)
    • 2 (apagado)
    • 3 (runCommand); inicia el comando o el script del shell para la configuración personalizada o los informes

    Lo siguiente debe acoplarse con un CommandID usado anteriormente:
    • 4 (refreshCommandStatus) hace que commandStatus describa una solicitud específica identificada por commandId.
    argumentos string • Cuando la acción es 1 (reinicio) o 2 (apagado), un número opcional de segundos para retrasar antes de desencadenar la acción
    • Cuando la acción es 3 (RunCommand), la línea de comandos que se va a ejecutar, por ejemplo. ping -c 2 example.com
    • Se omite para cualquier otro tipo de acción
    • Tamaño de commandArguments (normalmente dominado por el texto de argumentos) en gemelos de Azure IoT en limitado a 4 KB; para ver scripts más largos, consulte Procedimientos recomendados
    singleLineTextResult boolean • Cuando la acción es 3 (RunCommand), alternar opcional para especificar si las líneas nuevas deben quitarse de la salida de la consola.
    • Se omite para cualquier otro tipo de acción
    timeout int • Cuando la acción es 3 (runCommand), las solicitudes de larga duración se eliminan después de estos muchos segundos.
    • Opcional (el valor predeterminado es 30)
    • Se omite para cualquier otro tipo de acción

  • Ejemplos de dispositivos IoT Hub y reales

    • Solicitud de reinicio:

      "CommandRunner": {
   "__t": "c",
   "commandArguments": {
      "commandId": "my_reboot_cmd",
      "arguments": "",
      "timeout": 30,
      "singleLineTextResult": false,
      "action": 1
   }
}

    • Solicitud de configuración personalizada (zona horaria):

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

    • Para obtener ejemplos adicionales, consulte:

commandArguments (confirmación del dispositivo)

  • Descripción: esta es la confirmación del agente OSConfig en el dispositivo que ha recibido el valor commandArguments del lado administrador.

  • Ruta de acceso: properties.reported.CommandRunner.commandArguments (la parte de confirmación del dispositivo de la commandArguments propiedad grabable)

  • Miembros:

    Nombre Tipo Notas
    value mapa Debe reflejar properties.desired.CommandRunner.commandArguments, que indica el dispositivo en línea y ha recibido la solicitud.
    ac int Código de estado, el caso nominal es el valor 200

commandStatus

  • Descripción: proporciona el estado y la salida de una solicitud enviada previamente a través de commandArguments.

  • Ruta de acceso: properties.reported.CommandRunner.commandStatus (CommandRunner componente -->commandStatus propiedad de solo lectura)

  • Miembros

    Nombre Tipo Notas
    commandId string • Identifica qué solicitud recibida previamente se describe actualmente mediante Commandstatus.
    • De forma predeterminada, la solicitud más reciente se representa
    • El autor de la llamada puede cambiar este enfoque para describir una solicitud específica a través del mecanismo refreshCommandStatus descrito anteriormente.
    resultCode int Código de salida del comando solicitado. Análogo a echo $? en Bash
    currentState enum/int • El valor de mayúsculas y minúsculas nominales 2 (succeeded)
    • Consulte los metadatos para obtener una lista completa de los valores posibles.
    textResult string • Salida de la consola del comando solicitado
    • Tamaño de commandStatus (normalmente dominado por el componente textResult) en gemelos de Azure IoT en limitado a 4 KB; para obtener salidas más largas, consulte Procedimientos recomendados.

  • Ejemplos de dispositivos IoT Hub y reales

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, consulte: Los nombres de miembro pasan de PascalCase a camelCase en la versión 1.0.3.

Pasos siguientes

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

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