Freigeben über

Benutzerdefinierte Konfiguration und Berichterstellung mit Azure IoT und OSConfig

  • Artikel

Wichtig

Version 1.0.3 (veröffentlicht am 28. Juni 2022) umfasst die Unterbrechung von Änderungen an Membernamen, die sich auf vorhandene Benutzer auswirken können. Weitere Informationen finden Sie unter: Membernamen Übergang von PascalCase zu CamelCase in Version 1.0.3

Dieser Artikel soll Personen unterstützen, die Geräte mit Azure IoT bereitstellen oder verwalten . Wenn dies nicht wie Sie klingt, sollten Sie sich die Zielgruppe für die OSConfig-Dokumentation ansehen.

Das CommandRunner --RunCommand-Feature> ermöglicht Es Ihnen, einige Einfachheit zu nutzen, um Flexibilität zu erhalten. Wenn Sie müssen, können Sie eine Abstraktionsebene auflisten, um benutzerdefinierte Berichte und Konfigurationen auszuführen.

Allgemeine Beispiele für benutzerdefinierte Berichte und Konfigurationen

  • Überprüfen der Gerätekonnektivität mit wichtigen Endpunkten
  • Überprüfen, ob bestimmte Daemons ausgeführt werden
  • Debuggen oder Beheben von Geräten, z. B. durch Sammeln von Protokolldateien und Hochladen auf Cloudspeicher
  • Konfigurieren Sie alle Geräte, um die gewünschte Zeitzone beim Protokollieren von Daten zu verwenden, Zeitstempel zu generieren usw.
  • Melden Sie sich an (oder konfigurieren) Ihrer eigenen eindeutigen Gerätekomponenten, die OSConfig sonst nie wissen würde.
  • Die Möglichkeiten sind endlos, fast jede Aufgabe, die Sie in einer Shell für ein Gerät ausführen können - Sie können mit Azure IoT und OSConfig CommandRunner für Flotten von Geräten arbeiten.

Tipp

Dieser Artikel konzentriert sich auf praktische Beispiele mit minimaler Erläuterung. Technische Hintergrundinformationen zu CommandRunner finden Sie unter: Interagieren mit dem CommandRunner-Feature von OSConfig und Azure IoT.

Beispiele für Anwendungsfälle

Diese Beispiele können als Ausgangspunkte dienen, um sich für Ihre einzigartige Umgebung anzupassen.

Jedes Beispiel enthält Schritte und Bildschirmaufnahmen für die Arbeit in den Azure-Portal und zum Arbeiten in Bash mit Azure CLI.

Jedes Beispiel enthält auch Variationen für ein Gerät (z. B. ein Problembehandlungsszenario) oder für viele Geräte (z. B. eine Konfigurationsbereitstellung oder ein Berichtsszenario).

Was erwartet werden soll:

In den einzelnen Geräteanweisungen lesen und schreiben Sie gemeldete und gewünschte Eigenschaften direkt im OSConfig-Twin für ein Gerät. In den Anweisungen zur Skalierung verwenden Sie IoT Hub Konfigurationen (auch als Automatische Geräteverwaltung oder ADM bezeichnet), um gewünschte Eigenschaften an viele Zwillinge zu pushen und IoT Hub Abfragen (unabhängig oder an Konfigurationen als Metriken angefügt) zu verwenden, um die Ergebnisse zu beobachten, die von Geräten zurückkommen.

Voraussetzungen für die folgenden Beispiele

Wenn Sie diesen Artikel für Referenz verwenden (z. B. hier, um einen Eigenschaftennamen zu kopieren), gibt es keine Voraussetzungen.

Wenn Sie die Beispiele für Livesysteme (empfohlen) ausprobieren möchten, dann:

  1. Sie benötigen ein Azure-Konto mit einem IoT Hub

    In diesem Artikel wird davon ausgegangen, dass IoT Hub und verwandte Tools vertraut sind. Es wird z. B. davon ausgegangen, dass Sie IoT Hubs und Anfügen von Geräten bequem erstellen. Wenn Sie eine schrittweisere Einführung in die Installation und Verwendung von OSConfig von Grund auf bevorzugen, lesen Sie: Schnellstart: Verwalten eines einzelnen virtuellen IoT-Geräts mithilfe von Azure CLI stattdessen.

  2. Sie benötigen mindestens ein Linux-Gerät mit dem OSConfig-Agent, der installiert und mit Azure IoT verbunden ist.

    Weitere Informationen finden Sie unter: How and where to install the OSConfig agent for Linux.

  3. Sie verwenden Azure Portal oder Azure CLI zum Interagieren mit den Geräten über Ihre IoT Hub

    Wenn Sie weitere Schritte ausführen möchten, wählen Sie Ihre bevorzugte Erfahrung aus:

  1. Stellen Sie sicher, dass Sie beim Azure-Portal angemeldet sind und auf die Übersichtsseite Ihres IoT Hub zugreifen können, der IoT Hub und Geräte aus dem Azure-Portal anzeigt.

Tipp

Es gibt zwei Dinge, die Sie über das CommandRunner-Verhalten wissen sollten, um erfolgreich zu sein, indem Sie folgende Beispiele verwenden:

  • Wie in den Beispielen gezeigt, muss jede neue Anforderung einen neuen Wert commandId für (es kann eine beliebige Zeichenfolge sein, z. B. "MyCmd01", "MyCmd02").
  • Der Prozess ist asynchron, sodass Ergebnisse sofort nicht verfügbar sind. Die einfachste Prozedur besteht darin, ca. eine Minute zu warten, nachdem Sie eine CommandRunner-Anforderung initiiert haben. Nach dieser Minute stehen die Ergebnisse ohne zusätzliche Schritte auf Ihrem Teil zur properties.reported.CommandRunner.commandStatusVerfügung. Weitere Informationen zum Aktualisierungsverhalten, asynchronen Statusupdates usw. finden Sie unter: Interagieren mit dem CommandRunner-Feature von OSConfig und Azure IoT.

Beispiel 1: Überprüfen der Gerätekonnektivität mit bestimmten Endpunkten

In diesem Beispiel bitten wir das Gerät, www.github.com 3 Mal zu pingen. Wir beobachten den Exitcode des Pings (Erfolg oder Fehler), und wir können die Textausgabe des ping-Befehls beobachten.

  1. Navigieren Sie auf der Portalseite Ihres IoT Hub zum OSConfig-Modul-Twin für das Gerät, das Sie verwalten möchten. Fügen Sie dann dem properties.desired Abschnitt folgendes hinzu (gefolgt von einem Komma, um es vom nächsten Element zu properties.desiredtrennen).

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

    Bildschirmaufnahme mit den gewünschten Zwillingsinhalten für einen Pingbefehl mithilfe des OSConfig-Moduls für ein einzelnes Gerät aus Azure Portal

  2. Sie können die Gerätekonnektivität überprüfen, indem Sie die Antwort auf den Ping-Befehl aus dem OSConfig-Modul twin selbst überprüfen. Scrollen Sie nach unten, um gemeldete Eigenschaften für CommandRunner zu finden. Suchen Sie nach resultCode: 0 , der angibt, dass der Befehl erfolgreich war und textResult , das die Ausgabe des Pingbefehls anzeigt.

    Bildschirmaufnahme mit gemeldeten Twin-Inhalten für einen Ping-Befehl mithilfe des OSConfig-Moduls für ein einzelnes Gerät aus Azure Portal

Beispiel 2: Abrufen von Inhalten von /etc/ssh/sshd_config

In diesem Beispiel verwenden wir CommandRunner, um den Inhalt einer Datei von jedem Gerät zu erfassen. In diesem Beispiel laden wir die Datei nicht explizit in einen Cloudspeicherdienst hoch, sondern erfassen einfach den Inhalt im Zwilling.

Wichtig

Twin-Eigenschaftsupdates sind auf 4 KB begrenzt. Der hier gezeigte Ansatz erfasst den Dateiinhalt (von cat) inline in den Zwilling. Für sehr kleine Dateien hat dieser Ansatz den Vorteil, dass keine externen Speicherdienste oder Anmeldeinformationen erforderlich sind. Für größere Dateien ist dieser Ansatz nicht anwendbar. Stattdessen würden Sie Logik in Ihr Skript/Befehl einschließen, um die Datei in den lokalen oder Cloudspeicher Ihrer Wahl hochzuladen. Sie können z. B. eine Verbindung mit einer Cifs-Freigabe herstellen und die Datei dort kopieren oder den Dateiinhalt in Azure Storage verschieben.

  1. Navigieren Sie auf der Portalseite Ihrer IoT Hub zum OSConfig-Zwilling für das Gerät, das Sie verwalten möchten. Fügen Sie dann dem properties.desired Abschnitt Folgendes hinzu (gefolgt von einem Komma, um es vom nächsten Element zu properties.desiredtrennen). Sie können den Dateinamen Ihrer Wahl im folgenden Argumentfeld ersetzen.

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

    Bildschirmaufnahme, die zeigt, wie Sie die gewünschte Eigenschaft des OSConfig-Moduls twin festlegen, um Dateiinhalte von einem einzelnen Gerät mithilfe des OSConfig-Moduls aus Azure Portal zu lesen

  2. Sie können die Dateiinhalte aus dem Modul-Twin selbst sehen. Scrollen Sie nach unten im Modul twin, um commandStatus unter gemeldeten Eigenschaften für CommandRunner zu finden, hier sehen Sie dies im textResult. Suchen Sie nach resultCode: 0 , der angibt, dass der Befehl erfolgreich war, und textResult , das den gewünschten Dateiinhalt anzeigt.

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

    Bildschirmaufnahme mit dem Twin des OSConfig-Moduls, das die angeforderten Dateiinhalte von einem einzelnen Gerät aus dem Azure Portal anzeigt

Beispiel 3: Bereitstellen eines einfachen Inlineskripts zum Festlegen der Zeitzone auf UTC und Bericht über Zeitzone

In diesem Beispiel wird ein einfacher Anwendungsfall veranschaulicht, in dem sowohl das Skript als auch die Ergebnisse als Teil des Zwillings inline behandelt werden können. Das folgende Beispiel legt die Zeitzone auf UTC fest und fragt dann nach dem Festlegen der Zeitzone ab.

  1. Navigieren Sie auf der Portalseite Ihrer IoT Hub zum OSConfig-Zwilling für das Gerät, das Sie verwalten möchten, und fügen Sie dem properties.desired Abschnitt folgendes hinzu, gefolgt von einem Komma, um es vom nächsten Element properties.desiredzu trennen. action=3 unten gibt die RunCommand-Aktion an.

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

    Bildschirmaufnahme mit dem Festlegen der gewünschten Eigenschaft zum Aktualisieren der Zeitzone auf einem Gerät mithilfe des OSConfig-Moduls aus dem Azure Portal

  2. Nachdem der Befehl ausgeführt wurde, scrollen Sie nach unten, um den CommandStatus unter den gemeldeten Eigenschaften für CommandRunner zu finden, hier wird das textResult die aktuelle Zeitzone angezeigt, die auf dem Gerät festgelegt ist.

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

    Bildschirmaufnahme mit der Antwort auf das Festlegen des Befehls

Beispiel 4. Bereitstellen eines benutzerdefinierten Berichterstellungsskripts aus einem Online-Repository

In diesem Beispiel wird das Aufrufen eines Skripts außerhalb des Zwillings veranschaulicht. Beispielsweise können Sie Ihre Skripts in GitHub platzieren. Dieses Muster kann aus der Notwendigkeit entstehen (Skript ist zu groß für Zwillinge) oder aus der Vorzugseinstellung heraus. Der Befehl im Zwilling ist ein einfacher Wrapper. Es lädt das Hauptskript herunter und führt es aus.

Wichtig

Um dieses Dokument zu unterstützen, haben wir ein Beispielskript veröffentlicht. Dieses Beispielskript wird als Stand-In für Ihr eigenes Skript in GitHub oder an anderer Stelle bereitgestellt. Es sammelt ein paar Datenpunkte vom Gerät, einschließlich zeitstempel, Daemonstatus und freier Speicherplatz. Sie sollten Skripts aus dem Internet überprüfen, einschließlich dieser, bevor Sie sie auf Ihren Geräten ausführen.

  1. Navigieren Sie auf der Portalseite Ihres IoT Hub zum OSConfig-Twin für das Gerät, das Sie verwalten möchten, und fügen Sie dem properties.desired Abschnitt gefolgt von einem Komma ein Komma hinzu, um sie vom nächsten Element zu properties.desiredtrennen.

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

    Bildschirmaufnahme, die zeigt, wie Sie zwei Inhalte aktualisieren, um ein benutzerdefiniertes Skript auf einem einzelnen Gerät mit Azure Portal auszuführen

  2. Scrollen Sie nach unten, um CommandRunner -->commandStatus im Abschnitt "gemeldete Eigenschaften" des Twin zu finden. Suchen Sie nach resultCode: 0 , der angibt, dass der Befehl erfolgreich war und textResult , die die Ausgabe aus dem ausgeführten Skript anzeigt. Im folgenden Beispiel wird die Ausgabe aus dem OSConfig-Twin eines Geräts abgerufen:

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

    Bildschirmaufnahme, die zeigt, wie Sie zwei Inhalte überprüfen, nachdem ein benutzerdefiniertes Skript auf einem einzelnen Gerät mit Azure Portal ausgeführt wird

Nächste Schritte

Eine Übersicht über OSConfig-Szenarien und -Funktionen finden Sie unter:

Spezifische praktische Beispiele finden Sie unter: