Partager via

Configuration et création de rapports personnalisées avec Azure IoT et OSConfig

  • Article

Important

La version 1.0.3 (publiée le 28 juin 2022) inclut des modifications cassants apportées aux noms de membres susceptibles d’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

Cet article est conçu pour prendre en charge les personnes qui approvisionnent ou gèrent des appareils avec Azure IoT. Si cela ne vous ressemble pas, examinez la documentation Audiences pour OSConfig.

La fonctionnalité CommandRunner -->RunCommand vous permet d’échanger une certaine simplicité pour gagner en flexibilité. Quand vous en avez besoin, vous pouvez supprimer un niveau d’abstraction pour effectuer des rapports et une configuration personnalisés.

Exemples courants de création de rapports et de configuration personnalisés

  • Vérifier la connectivité des appareils aux points de terminaison clés
  • Vérifier que des démons spécifiques sont en cours d’exécution
  • Déboguer ou dépanner des appareils, par exemple en collectant des fichiers journaux et en les chargeant dans le stockage cloud
  • Configurez tous les appareils pour utiliser le fuseau horaire souhaité lors de la journalisation des données, la génération d’horodatages, etc.
  • Signaler (ou configurer) vos propres composants d’appareil uniques que OSConfig ne connaîtrait jamais
  • Les possibilités sont infinies, presque n’importe quelle tâche que vous pouvez effectuer dans un interpréteur de commandes pour un seul appareil. Vous pouvez le faire avec Azure IoT et OSConfig CommandRunner pour les flottes d’appareils

Conseil

Cet article se concentre sur des exemples pratiques avec une explication minimale. Pour plus d’informations techniques sur CommandRunner, consultez : Comment interagir avec la fonctionnalité CommandRunner de OSConfig et d’Azure IoT.

Exemples de cas d’usage

Ces exemples peuvent servir de points de départ pour vous permettre d’adapter votre environnement unique.

Chaque exemple inclut des étapes et des captures d’écran pour travailler dans le Portail Azure et pour travailler dans Bash avec Azure CLI.

Chaque exemple inclut également des variantes pour un appareil (par exemple, un scénario de résolution des problèmes) ou pour de nombreux appareils (par exemple, un provisionnement de configuration ou un scénario de création de rapports).

Qu’attendez-vous :

Dans les instructions d’un seul appareil, vous allez lire et écrire les propriétés signalées et souhaitées directement dans le jumeau OSConfig d’un appareil. Dans les instructions à grande échelle, vous allez utiliser IoT Hub Configurations (également appelées Automatique Gestion des appareils ou ADM) pour envoyer (push) les propriétés souhaitées à de nombreux jumeaux, et utiliser des requêtes IoT Hub (indépendamment, ou attachées aux configurations en tant que métriques) pour observer les résultats provenant des appareils.

Conditions préalables pour les exemples suivants

Si vous utilisez cet article pour référence (par exemple, vous êtes ici pour copier un nom de propriété), il n’existe aucune condition préalable.

Si vous souhaitez essayer les exemples sur les systèmes en direct (recommandé), alors :

  1. Vous aurez besoin d’un compte Azure avec un IoT Hub

    Cet article suppose une certaine connaissance des IoT Hub et des outils connexes. Par exemple, il suppose que vous êtes à l’aise avec la création d’IoT Hubs et l’attachement d’appareils. Si vous préférez une présentation pas à pas plus prescriptive de l’installation et de l’utilisation de OSConfig à partir de zéro, consultez : Démarrage rapide : Gérer un seul appareil IoT virtuel à l’aide d’Azure CLI à la place.

  2. Vous aurez besoin d’au moins un appareil Linux avec l’agent OSConfig installé et connecté à Azure IoT.

    Pour plus d’informations, consultez : Comment et où installer l’agent OSConfig pour Linux.

  3. Vous utiliserez le portail Azure ou Azure CLI pour interagir avec les appareils via votre IoT Hub

    Pour obtenir d’autres étapes, choisissez votre expérience préférée :

  1. Vérifiez que vous êtes connecté au portail Azure et que vous pouvez accéder à la page vue d’ensemble de votre IoT Hub capture d’écran montrant IoT Hub et les appareils à partir du portail Azure

Conseil

Il existe deux choses que vous devez savoir sur le comportement de CommandRunner pour réussir à l’aide de ces exemples :

  • Comme illustré dans les exemples, chaque nouvelle requête doit inclure une nouvelle valeur pour commandId (il peut s’agir de n’importe quelle chaîne, par exemple « MyCmd01 », « MyCmd02 »).
  • Le processus est asynchrone. Les résultats ne sont donc pas disponibles instantanément. La procédure la plus simple consiste à attendre environ une minute après avoir lancé une requête CommandRunner. Après cette minute, sans aucune étape supplémentaire de votre part, les résultats sont disponibles en properties.reported.CommandRunner.commandStatus. Pour plus d’informations sur le comportement d’actualisation, les mises à jour d’état asynchrones, etc., consultez : Comment interagir avec la fonctionnalité CommandRunner d’OSConfig et d’Azure IoT.

Exemple 1. Vérifier la connectivité des appareils à des points de terminaison spécifiques

Dans cet exemple, nous demandons au ou aux appareils d’effectuer un test ping www.github.com 3 fois. Nous observons le code de sortie de ping (réussite ou échec) et nous pouvons observer la sortie textuelle de la commande ping.

  1. Dans la page du portail de votre IoT Hub, accédez au jumeau de module OSConfig pour l’appareil que vous souhaitez gérer. Ajoutez ensuite ce qui suit à la properties.desired section (suivie d’une virgule pour la séparer de l’élément suivant dans properties.desired).

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

    Capture d’écran montrant le contenu de jumeau souhaité pour une commande ping à l’aide du module OSConfig pour un seul appareil à partir du portail Azure

  2. Vous pouvez vérifier la connectivité de l’appareil en vérifiant la réponse à la commande ping à partir du jumeau de module OSConfig lui-même. Faites défiler vers le bas le jumeau de module pour rechercher les propriétés signalées pour CommandRunner. Recherchez resultCode : 0 qui indique que la commande a réussi et textResult qui affiche la sortie de la commande ping .

    Capture d’écran montrant le contenu du jumeau signalé pour une commande ping à l’aide du module OSConfig pour un seul appareil à partir du portail Azure

Exemple 2. Obtenir le contenu de /etc/ssh/sshd_config

Dans cet exemple, nous utilisons CommandRunner pour capturer le contenu d’un fichier à partir de chaque appareil. Dans cet exemple, nous ne chargeons pas explicitement le fichier dans n’importe quel service de stockage cloud, mais capturez simplement son contenu dans le jumeau.

Important

Les mises à jour des propriétés de jumeau sont limitées à 4 Ko. L’approche indiquée ici capture le contenu du fichier (à partir de cat) inline dans le jumeau. Pour les fichiers très petits, cette approche offre l’avantage de ne pas nécessiter de services de stockage ou d’informations d’identification externes. Pour les fichiers plus volumineux, cette approche n’est pas applicable. Au lieu de cela, vous incluez la logique dans votre script/commande pour charger le fichier dans le stockage local ou cloud de votre choix. Par exemple, vous pouvez vous connecter à un partage cifs et copier le fichier, ou envoyer le contenu du fichier au Stockage Azure.

  1. À partir de la page du portail de votre IoT Hub, accédez au jumeau OSConfig pour l’appareil que vous souhaitez gérer. Ajoutez ensuite ce qui suit à la properties.desired section (suivie d’une virgule pour la séparer de l’élément suivant dans properties.desired). Vous pouvez remplacer le nom de fichier de votre choix dans le champ arguments ci-dessous.

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

    Capture d’écran montrant comment définir la propriété souhaitée du jumeau de module OSConfig pour lire le contenu du fichier à partir d’un seul appareil à l’aide du module OSConfig à partir du portail Azure

  2. Vous pouvez voir le contenu du fichier à partir du jumeau de module lui-même. Faites défiler le jumeau de module pour rechercher commandStatus sous les propriétés signalées pour CommandRunner, ici, vous verrez cela dans le texteResult. Recherchez resultCode : 0 qui indique que la commande a réussi et textResult qui affiche le contenu du fichier souhaité.

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

    Capture d’écran montrant le jumeau de module OSConfig qui affiche le contenu du fichier demandé à partir d’un seul appareil à partir du portail Azure

Exemple 3. Déployer un script inline simple pour définir le fuseau horaire sur UTC et signaler sur le fuseau horaire

Cet exemple illustre un cas d’usage simple où le script et les résultats peuvent être gérés inline dans le cadre du jumeau. L’exemple ici définit le fuseau horaire UTC, puis interroge le fuseau horaire une fois qu’il est défini.

  1. À partir de la page du portail de votre IoT Hub, accédez au jumeau OSConfig pour l’appareil que vous souhaitez gérer, puis ajoutez ce qui suit à la properties.desired section, suivi d’une virgule pour la séparer de l’élément suivant dans properties.desired. action=3 ci-dessous spécifie l’action RunCommand .

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

    Capture d’écran montrant comment définir la propriété souhaitée pour mettre à jour le fuseau horaire sur un appareil à l’aide du module OSConfig à partir du portail Azure

  2. Une fois la commande exécutée, faites défiler le jumeau de module pour rechercher commandStatus sous les propriétés signalées pour CommandRunner, ici, vous verrez le texteResult afficher le fuseau horaire actuel défini sur l’appareil.

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

    Capture d’écran montrant la réponse de la définition de la commande timezone sur un seul appareil à partir du portail Azure

Exemple 4. Déployer un script de création de rapports personnalisé à partir d’un référentiel en ligne

Cet exemple illustre l’appel d’un script situé en dehors du jumeau. Par exemple, vous pouvez placer vos scripts dans GitHub. Ce modèle peut se produire hors de nécessité (le script est trop grand pour le jumeau), ou hors de préférence. La commande dans le jumeau est un wrapper simple. Il télécharge le script principal et l’exécute.

Important

Pour prendre en charge ce document, nous avons publié un exemple de script. Cet exemple de script est fourni en tant que stand-in pour votre propre script dans GitHub ou ailleurs. Il collecte quelques points de données à partir de l’appareil, y compris un horodatage, un état démon et un espace disque libre. Vous devez inspecter les scripts à partir d’Internet, y compris celui-ci, avant de les exécuter sur vos appareils.

  1. Dans la page du portail de votre IoT Hub, accédez au jumeau OSConfig de l’appareil que vous souhaitez gérer, puis ajoutez ce qui suit à la properties.desired section, suivi d’une virgule pour la séparer de l’élément suivant dans 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
   }
}

    Capture d’écran montrant comment mettre à jour le contenu du jumeau pour exécuter un script personnalisé sur un seul appareil à l’aide du portail Azure

  2. Faites défiler vers le bas le jumeau de module pour rechercher CommandRunner -->commandStatus dans la section propriétés signalées du jumeau. Recherchez resultCode : 0 qui indique que la commande a réussi et textResult qui affiche la sortie du script exécuté. Voici un exemple de sortie extrait du jumeau OSConfig d’un appareil :

    "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
   },
}

    Capture d’écran montrant comment vérifier le contenu du jumeau après l’exécution d’un script personnalisé sur un seul appareil à l’aide du portail Azure

Étapes suivantes

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

Pour obtenir des exemples pratiques spécifiques, consultez :