Comment interagir avec la fonctionnalité CommandRunner d’OSConfig et d’Azure IoT

La plupart des propriétés d’appareil exposées par OSConfig sont discrètes et extraites des détails de l’implémentation. Par exemple, lorsque vous utilisez HostName.desiredName pour définir le nom d’hôte d’un appareil, vous n’avez pas besoin de vous soucier de la saveur du système d’exploitation, des dépendances d’exécution de scripts ou des nuances de minutage.

Parfois, toutefois, vous pouvez vouloir échanger la simplicité pour la flexibilité. Par exemple :

• Vous devez récupérer des informations personnalisées à partir de l’appareil, par exemple si vous souhaitez rendre compte des résultats de du point de vue de ping example.com l’appareil
• Vous devez configurer un élément sur l’appareil où il n’existe aucune propriété osConfig souhaitée/accessible en écriture

La fonctionnalité CommandRunner d’OSConfig permet la configuration personnalisée et la création de rapports via des commandes/scripts d’interpréteur de commandes. Il inclut également certaines actions prédéfinies (arrêt, redémarrage) qui ne nécessitent aucun script.

Conseil

Cet article de référence décrit les concepts commandRunner, le modèle d’interaction, etc. Pour obtenir des exemples d’utilisation concrets, consultez :

• Redémarrer ou arrêter des appareils avec Azure IoT et OSConfig
• Configuration et création de rapports personnalisés avec Azure IoT et OSConfig

Le modèle d’interaction et les propriétés/champs clés

Résumé du modèle d’interaction

Bien que l’utilisation plus nuancée soit possible (et décrite plus loin dans cet article), le modèle d’interaction de base est simple :

• Vous lancez une demande de commande en écrivant dans commandArguments le jumeau.
• Vous obtenez les résultats en lisant les rapports commandStatus du jumeau.

Important

Les charges utiles présentées dans ce diagramme sont supprimées pour mettre en évidence le flux d’entrée/sortie. Pour le modèle objet complet, y compris les membres requis non indiqués ici, consultez : Le modèle objet complet

L’identificateur d’aller-retour est : commandId

Dans le diagramme ci-dessus, notez que et commandArgumentscommandStatus incluent un champ appelé commandId. Il s’agit de l’identificateur d’aller-retour qui lie la demande et le résultat tout au long de cette opération asynchrone.

L’appelant (chaîne d’outils administrateur ou administrateur) choisit la valeur commandId.

Conseil

commandId est requis dans commandArguments. Les appelants utilisent généralement l’un de ces modèles lors du choix des valeurs :

• Valeurs monotones comme « 1 » (pour la première requête), « 2 » (pour la deuxième requête), etc. ou des valeurs descriptives comme « my_ping_command »

  Celles-ci sont bien adaptées à l’exploration ad hoc; ils ne nécessitent pas de planification et peuvent être facilement tapés lors de la modification du contenu de jumeau

• Valeurs générées automatiquement par une entropie élevée, telles que les UUID

  Ceux-ci sont bien adaptés à une utilisation programmatique à grande échelle où un back-end de solution cloud crée et effectue le suivi des valeurs par programmation

Nouvelle valeur de commandId dans commandArguments signale qu’il s’agit d’une nouvelle requête. Dans le contexte d’un jumeau d’appareil unique, le remplissage d’un nouveau commandId est à peu près analogue à l’action « Entrée » dans un environnement d’interpréteur de commandes.

commandId permet également de suivre plusieurs demandes. CommandRunner sur chaque appareil peut recevoir (et signaler status sur) plusieurs requêtes au fil du temps. Pendant ce temps, les commandArguments composants et commandStatus dans le jumeau de chaque appareil ne peuvent décrire qu’une seule requête à tout moment. commandId est l’identificateur d’aller-retour permettant à l’appelant de comprendre (et de contrôler) quelle requête précédente est actuellement décrite par commandStatus. En effet, commandStatus communique « pour votre demande où l’ID était 'foo', le status est <...> ».

Quand est-il commandStatus mis à jour ?

Il existe deux déclencheurs permettant à CommandRunner sur l’appareil de mettre à jour commandStatus.

1. Actualisation en arrière-plan

   commandStatus est mis à jour à intervalles réguliers (la valeur par défaut est de 30 secondes). Par défaut, cette actualisation en arrière-plan représente le status de la requête la plus récente.

   Dans la pratique, cela signifie qu’après avoir envoyé une requête via commandArguments, vous pouvez vous attendre à voir les status correspondants dans commandStatus après environ 30 à 60 secondes.

2. refreshCommandStatus

   refreshCommandStatus est un mécanisme qui traite deux cas d’usage avancés :

   1. Vous avez émis plusieurs demandes au fil du temps via commandArguments, et vous souhaitez voir les status pour une demande spécifique, et non la demande la plus récente
   2. Vous ne souhaitez pas attendre l’actualisation en arrière-plan, même si vous n’êtes intéressé que par la dernière requête

   Pour déclencher ce mécanisme, consultez la documentation du modèle objet ci-dessous pour commandArguments.

Bonnes pratiques pour la configuration personnalisée et la création de rapports avec CommandRunner

1. Considérations en matière de taille

   Pour les commandes/scripts courts et les sorties courtes, vous pouvez travailler directement en ligne via le jumeau. Cette approche présente des avantages, en particulier l’absence de dépendance de réseau ou d’authentification en dehors de IoT Hub. Le principal inconvénient de cette approche est que les entrées (y compris le texte de votre script/commandes) et les sorties (y compris toute sortie de console capturée) sont chacune limitées à 4 Ko.

   Pour les scripts plus longs, vous pouvez stocker le script ailleurs (par exemple, GitHub) et l’appeler à partir d’une commande wrapper minimale que vous passez à OSConfig via le jumeau. Pour obtenir des exemples, consultez Configuration et création de rapports personnalisés avec Azure IoT et OSConfig. Indépendamment de la taille, vous pouvez également préférer gérer vos scripts dans GitHub ou similaire, avec un contenu de jumeau pointant simplement vers ceux-ci.

   Pour les scripts/commandes dont la sortie de la console est trop importante pour le jumeau, vous pouvez inclure une logique dans le script pour envoyer les résultats au stockage local ou cloud plutôt qu’à stdout. Pour obtenir des exemples, consultez Configuration et création de rapports personnalisés avec Azure IoT et OSConfig.

2. Utiliser des commandes/scripts autonomes et non interactifs

   Moins d’allers-retours sont préférables, un aller-retour est préférable. OSConfig et CommandRunner sont optimisés pour la mise à l’échelle et non pour l’interactivité. Bien qu’il soit possible d’utiliser CommandRunner en série (une commande après l’autre, similaire à un terminal synchrone en direct), l’expérience n’est pas optimale. Il n’existe aucun moyen de gérer les invites d’interpréteur de commandes interactives, vous devez affecter un commandId à chaque requête, vous devez attendre la synchronisation des jumeaux, etc.

   Au lieu de cela, considérez CommandRunner comme un moyen d’obtenir une configuration et des rapports personnalisés à grande échelle. Vous pouvez distribuer de façon asynchrone un script non interactif (ou une action prédéfinie comme le redémarrage) à un ou plusieurs millions d’appareils, et vous pouvez rendre compte des résultats même s’ils évoluent au fil du temps (à mesure que de nouveaux appareils rejoignent la flotte, par exemple).

   En d’autres termes, supposons que vous devez exécuter quatre commandes sur tous les appareils Ubuntu 20.04 actuels et futurs en Espagne. Ne considérez pas cela comme 4 utilisations séquentielles discrètes de CommandRunner, considérez-le comme une utilisation unique de CommandRunner où la charge utile contient vos quatre commandes. Pendant ce temps, un flux de travail cloud tel que IoT Hub Configurations peut garantir qu’il est distribué à tous les appareils actuels et futurs qui doivent être dans l’étendue.

Modèle objet complet

Important

La version 1.0.3 (publiée le 28 juin 2022) inclut des modifications cassants apportées aux noms des membres qui peuvent avoir un impact sur les utilisateurs existants. Pour plus d’informations, consultez : Transition des noms de membres de PascalCase à camelCase dans la version 1.0.3

Les informations suivantes s’appliquent aux vues simples souhaitées/signalées du modèle objet, ainsi qu’aux vues améliorées DTDL. Pour plus d’informations, consultez Ce que les utilisateurs OSConfig doivent savoir sur les chaînes d’outils « plain desired/reported » et « DTDL enhanced ».

commandArguments (défini par l’administrateur)

• Description : entrée de l’administrateur, déclenche une nouvelle demande de commande ou déclenche l’actualisation de commandStatus.

• Chemin : properties.desired.CommandRunner.commandArguments (CommandRunner component -->commandArguments writable property)

• Members (Membres)

  Nom	Type	Notes
  commandId	string	• ID de demande spécifié par l’appelant ; voir ci-dessus pour connaître l’arrière-plan • commandArguments est ignoré lorsque commandId est vide • Pour l’interaction entre commandId et action, consultez les rubriques suivantes
  action	enum/int	Les éléments suivants doivent être associés à une nouvelle valeur commandId : • 1 (redémarrage) • 2 (arrêt) • 3 (runCommand) ; initie la commande/le script shell pour la configuration ou la création de rapports personnalisés Les éléments suivants doivent être associés à un CommandID précédemment utilisé : • 4 (refreshCommandStatus) amène commandStatus à décrire une requête spécifique identifiée par commandId
  arguments	string	• Lorsque l’action est 1 (redémarrage) ou 2 (arrêt), un nombre de secondes facultatif à retarder avant de déclencher l’action • Lorsque l’action est 3 (RunCommand), la ligne de commande à exécuter, par exemple ping -c 2 example.com • Ignoré pour tout autre type d’action • Taille des arguments CommandArguments (généralement dominés par le texte des arguments) dans les jumeaux Azure IoT dans une limite de 4 Ko ; pour des scripts plus longs , consultez Bonnes pratiques
  singleLineTextResult	boolean	• Lorsque l’action a la valeur 3 (RunCommand), bascule facultative pour spécifier si les nouvelles lignes doivent être supprimées de la sortie de la console • Ignoré pour tout autre type d’action
  timeout	int	• Lorsque l’action a la valeur 3 (runCommand), les requêtes de longue durée sont tuées après ce nombre de secondes • Facultatif (la valeur par défaut est 30) • Ignoré pour tout autre type d’action

• Exemples d’appareils IoT Hub et réels

  • Demande de redémarrage :

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

  • Demande de configuration personnalisée (fuseau horaire) :

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

  • Pour obtenir d’autres exemples, consultez :

    • Redémarrer ou arrêter des appareils avec Azure IoT et OSConfig
    • Configuration et création de rapports personnalisés avec Azure IoT et OSConfig

commandArguments (accusé de réception de l’appareil)

• Description : il s’agit de l’accusé de réception de l’agent OSConfig sur l’appareil qu’il a reçu la valeur commandArguments du côté administrateur

• Chemin d’accès : properties.reported.CommandRunner.commandArguments (la partie d’accusé de réception de l’appareil de la commandArguments propriété accessible en écriture)

• Membres :

  Nom	Type	Notes
  value	carte	Doit miroir properties.desired.CommandRunner.commandArguments, indiquant l’appareil en ligne et a reçu la demande
  clim	int	Code d’état, cas nominal est valeur 200

commandStatus

• Description : donne la status et la sortie d’une requête précédemment soumise via commandArguments

• Chemin d’accès : properties.reported.CommandRunner.commandStatus (CommandRunner composant -->commandStatus propriété en lecture seule)

• Members (Membres)

  Nom	Type	Notes
  commandId	string	• Identifie la demande précédemment reçue est actuellement décrite par Commandstatus • Par défaut, la demande la plus récente est représentée • L’appelant peut modifier ce focus pour décrire une requête spécifique via le mécanisme refreshCommandStatus décrit ci-dessus
  resultCode	int	Code de sortie de la commande demandée. Analogue à echo $? dans bash
  Currentstate	enum/int	• La casse nominale est la valeur 2 (succeeded) • Consultez les métadonnées pour obtenir la liste complète des valeurs possibles
  textResult	string	• Sortie console de la commande demandée • Taille de commandStatus (généralement dominé par le composant textResult) dans les jumeaux Azure IoT dans une limite de 4 Ko ; pour des sorties plus longues , consultez Bonnes pratiques

• Exemples d’appareils IoT Hub et réels

  • Résultat du redémarrage

    "CommandRunner": {
        "__t": "c",
        "commandStatus": {
           "commandId": "my_reboot_cmd",
           "resultCode": 0,
           "textResult": "",
           "currentState": 2
        }
    }
    

  • Résultat de la configuration personnalisée (fuseau horaire) :

    "CommandRunner": {
       "__t": "c",
       "commandStatus": {
          "commandId": "my_timezone_cmd",
          "testResult": "Time zone: UTC",
          "statusCode": 0
       }
    }
    

  • Pour obtenir d’autres exemples, consultez :

    • Redémarrer ou arrêter des appareils avec Azure IoT et OSConfig
    • Configuration et création de rapports personnalisés avec Azure IoT et OSConfig

Important

La version 1.0.3 (publiée le 28 juin 2022) inclut des modifications cassants des noms de membres qui peuvent avoir un impact sur les utilisateurs existants. Pour plus d’informations, consultez : Transition des noms de membres de PascalCase à camelCase dans la version 1.0.3

Étapes suivantes

Pour obtenir une vue d’ensemble des scénarios et des fonctionnalités OSConfig, consultez :

• Présentation d’OSconfig pour IoT

Pour obtenir des exemples pratiques spécifiques, consultez :

• Créer un environnement de laboratoire OSConfig (avec Azure IoT) en 5 minutes
• Démarrage rapide : Exemples de requêtes pour bien démarrer avec OSConfig et Azure IoT
• Que puis-je provisionner et gérer ?