Interagieren mit dem CommandRunner-Feature von OSConfig und Azure IoT

Die meisten von OSConfig verfügbar gemachten Geräteeigenschaften sind diskret und von Implementierungsdetails abstrahiert. Wenn Sie HostName.desiredName beispielsweise verwenden, um den Hostnamen eines Geräts festzulegen, müssen Sie sich keine Gedanken über die Betriebssystemvariante, die Skriptlaufzeitabhängigkeiten oder die Zeitlichen Nuancen machen.

In manchen Fällen möchten Sie jedoch die Einfachheit für Flexibilität eintauschen. Beispiel:

• Sie müssen benutzerdefinierte Informationen vom Gerät abrufen, z. B. die Ergebnisse von aus Sicht des ping example.com Geräts melden möchten.
• Sie müssen etwas auf dem Gerät konfigurieren, auf dem keine gewünschte/schreibbare OSConfig-Eigenschaft vorhanden ist.

Das CommandRunner-Feature von OSConfig ermöglicht benutzerdefinierte Konfiguration und Berichterstellung über Shellbefehle/Skripts. Es umfasst auch bestimmte vordefinierte Aktionen (Herunterfahren, Neustart), die keine Skripterstellung erfordern.

Tipp

In diesem Referenzartikel werden CommandRunner-Konzepte, Interaktionsmodell usw. beschrieben. Konkrete Anwendungsbeispiele finden Sie unter:

• Neustarten oder Herunterfahren von Geräten mit Azure IoT und OSConfig
• Benutzerdefinierte Konfiguration und Berichterstellung mit Azure IoT und OSConfig

Das Interaktionsmodell und die wichtigsten Eigenschaften/Felder

Zusammenfassung des Interaktionsmodells

Obwohl eine differenziertere Verwendung möglich ist (und weiter unten in diesem Artikel beschrieben), ist das Kerninteraktionsmodell einfach:

• Sie initiieren eine Befehlsanforderung, indem Sie an den Gewünschten commandArguments in den Zwilling schreiben.
• Sie erhalten die Ergebnisse, indem Sie vom Zwilling gemeldet lesen commandStatus .

Wichtig

Die in diesem Diagramm dargestellten Nutzlasten werden entfernt, um den In-/Out-Fluss zu betonen. Informationen zum vollständigen Objektmodell einschließlich der erforderlichen Elemente, die hier nicht angezeigt werden, finden Sie unter Das vollständige Objektmodell.

Der Roundtripbezeichner lautet: commandId

Beachten Sie im obigen Diagramm, dass sowohl als commandStatus auch commandArguments ein Feld mit dem Namen enthaltencommandId. Dies ist die Roundtripbezeichner-Verknüpfungsanforderung und das Ergebnis dieses asynchronen Vorgangs.

Der Aufrufer (Administrator- oder Administratortoolkette) wählt den Wert commandId aus.

Tipp

commandId ist in commandArgumentserforderlich. Aufrufer verwenden bei der Auswahl von Werten in der Regel eines der folgenden Muster:

• Monotone Werte wie "1" (für die erste Anforderung), "2" (für die zweite Anforderung) usw. oder beschreibende Werte wie "my_ping_command"

  Diese eignen sich gut für die Ad-hoc-Untersuchung; Sie erfordern keine Planung, und sie können beim Bearbeiten von Zwillingsinhalten einfach eingegeben werden.

• Hohe automatisch generierte Entropiewerte wie UUIDs

  Diese eignen sich gut für eine umfangreiche programmgesteuerte Nutzung, bei der ein Cloudlösungs-Back-End programmgesteuert Werte erstellt und nachverfolgt.

Der neue Wert in commandIdcommandArguments signalisiert, dass es sich um eine neue Anforderung handelt. Im Kontext des Zwillings eines einzelnen Geräts entspricht das Auffüllen eines neuen commandId in etwa dem Drücken der Eingabetaste in einer Shellumgebung.

commandId ermöglicht auch das Nachverfolgen mehrerer Anforderungen. CommandRunner kann auf jedem Gerät im Laufe der Zeit mehrere Anforderungen empfangen (und status melden). In der Zwischenzeit können die commandArguments Komponenten und commandStatus im Zwilling jedes Geräts nur eine Anforderung zu einem beliebigen Zeitpunkt beschreiben. commandId ist der Roundtripbezeichner, der dem Aufrufer ermöglicht, zu verstehen (und zu steuern), welche vorherige Anforderung derzeit von commandStatusbeschrieben wird. In der Tat kommuniziert "für Ihre Anforderung, commandStatus bei der die ID 'foo' war, die status ist <...>".

Wann wird commandStatus aktualisiert?

Es gibt zwei Trigger für CommandRunner auf dem Gerät, um zu aktualisieren commandStatus.

1. Hintergrundaktualisierung

   commandStatus wird in regelmäßigen Abständen aktualisiert (Standardwert: 30 Sekunden). Standardmäßig stellt diese Hintergrundaktualisierung die status der letzten Anforderung dar.

   In der Praxis bedeutet dies, dass Sie nach dem Übermitteln einer Anforderung über commandArguments nach etwa 30 bis 60 Sekunden mit entsprechenden status in commandStatus rechnen können.

2. refreshCommandStatus

   refreshCommandStatus ist ein Mechanismus, der zwei erweiterte Anwendungsfälle behandelt:

   1. Sie haben im Laufe der Zeit mehrere Anforderungen über commandArgumentsausgestellt, und Sie möchten die status für eine bestimmte Anforderung anzeigen, nicht die neueste Anforderung.
   2. Sie möchten nicht auf die Hintergrundaktualisierung warten, auch wenn Sie nur an der neuesten Anforderung interessiert sind.

   Informationen zum Auslösen dieses Mechanismus finden Sie in der Dokumentation zum Objektmodell weiter unten für commandArguments.

Bewährte Methoden für die benutzerdefinierte Konfiguration und Berichterstellung mit CommandRunner

1. Überlegungen zu Größen

   Für kurze Befehle/Skripts und kurze Ausgaben können Sie direkt inline über den Zwilling arbeiten. Dieser Ansatz hat Vorteile, insbesondere ohne Netzwerk- oder Authentifizierungsabhängigkeit außerhalb von IoT Hub. Der Hauptnachteil dieses Ansatzes besteht darin, dass die Eingaben (einschließlich Des Skripts/Befehlstexts) und Ausgaben (einschließlich aller erfassten Konsolenausgaben) jeweils auf 4 KB beschränkt sind.

   Bei längeren Skripts können Sie das Skript an einer anderen Stelle (z. B. GitHub) speichern und über einen minimalen Wrapperbefehl aufrufen, den Sie über den Zwilling an OSConfig übergeben. Beispiele finden Sie unter Benutzerdefinierte Konfiguration und Berichterstellung mit Azure IoT und OSConfig. Unabhängig von der Größe können Sie es auch vorziehen, Ihre Skripts in GitHub oder ähnlich zu verwalten– mit Zwillingsinhalten, die einfach auf diese verweisen.

   Bei Skripts/Befehlen, deren Konsolenausgabe für den Zwilling zu groß ist, können Sie Logik in das Skript einschließen, um Ergebnisse an den lokalen speicher oder cloudbasierten Speicher zu senden und nicht an stdout. Beispiele finden Sie unter Benutzerdefinierte Konfiguration und Berichterstellung mit Azure IoT und OSConfig.

2. Verwenden eigenständiger, nicht interaktiver Befehle/Skripts

   Weniger Hin- und Rückflüge sind besser, eine Hin- und Rückfahrt ist am besten. OSConfig und CommandRunner sind für Skalierung und nicht für Interaktivität optimiert. Obwohl es möglich ist, CommandRunner seriell zu verwenden (ein Befehl nach dem anderen, ähnlich wie bei einem synchronen Liveterminal), ist die Erfahrung nicht optimal. Es gibt keine Möglichkeit, interaktive Shelleingabeaufforderungen zu verarbeiten, Sie müssen jeder Anforderung eine commandId zuweisen, Sie müssen auf die Zwillingssynchronisierung warten usw.

   Stellen Sie sich Stattdessen CommandRunner als eine Möglichkeit vor, benutzerdefinierte Konfigurationen und Berichte im großen Stil zu erreichen. Sie können ein nicht interaktives Skript (oder eine vordefinierte Aktion wie neustarten) asynchron auf ein Gerät oder Millionen von Geräten verteilen und die Ergebnisse auch dann melden, wenn sie sich im Laufe der Zeit weiterentwickeln (z. B. wenn neue Geräte der Flotte beitreten).

   Angenommen, Sie müssen vier Befehle auf allen aktuellen und zukünftigen Ubuntu 20.04-Geräten in Spanien ausführen. Stellen Sie sich dies nicht als vier diskrete sequenzielle Verwendungen von CommandRunner vor, stellen Sie sich dies als eine einzelne Verwendung von CommandRunner vor, bei der die Nutzlast Ihre vier Befehle enthält. In der Zwischenzeit kann ein Cloudworkflow wie IoT Hub-Konfigurationen sicherstellen, dass dieser auf alle aktuellen und zukünftigen Geräte verteilt wird, die sich im Gültigkeitsbereich befinden sollten.

Das vollständige Objektmodell

Wichtig

Version 1.0.3 (veröffentlicht am 28. Juni 2022) enthält breaking changes an Membernamen, die sich auf vorhandene Benutzer auswirken können. Weitere Informationen finden Sie unter: Membernamen übergangen von PascalCase zu camelCase in Version 1.0.3

Die folgenden Informationen gelten für einfache gewünschte/gemeldete Ansichten des Objektmodells sowie für erweiterte DTDL-Ansichten. Weitere Informationen finden Sie unter What OSConfig users need to know about "plain desired/reported" vs "DTDL enhanced" toolchains.For more information, see What OSConfig users need to know about "plain desired/reported" vs "DTDL enhanced" toolchains.

commandArguments (vom Administrator festgelegt)

• Beschreibung: Eingabe vom Administrator löst eine neue Befehlsanforderung aus oder löst eine Aktualisierung von commandStatus aus.

• Pfad: properties.desired.CommandRunner.commandArguments (CommandRunner Komponente -->commandArguments beschreibbare Eigenschaft)

• Mitglieder

  Name	Typ	Hinweise
  commandId	Zeichenfolge	• Vom Anrufer angegebene Anforderungs-ID; Siehe oben für den Hintergrund • commandArguments wird ignoriert, wenn commandId leer ist • Informationen zum Zusammenspiel zwischen commandId und Action finden Sie in den folgenden Artikeln.
  action	enum/int	Folgendes sollte mit dem neuen Wert commandId gekoppelt werden: • 1 (Neustart) • 2 (Herunterfahren) • 3 (runCommand); initiiert Shellbefehl/-skript für benutzerdefinierte Konfiguration oder Berichterstellung Folgendes sollte mit einer zuvor verwendeten CommandID gekoppelt werden: • 4 (refreshCommandStatus) bewirkt, dass commandStatus eine bestimmte Anforderung beschreibt, die durch commandId identifiziert wird.
  Argumente	Zeichenfolge	• Wenn die Aktion 1 (Neustart) oder 2 (Herunterfahren) ist, kann eine optionale Anzahl von Sekunden verzögert werden, bevor die Aktion ausgelöst wird. • Wenn aktion 3 (RunCommand) ist, die auszuführende Befehlszeile, z. B. ping -c 2 example.com • Ignoriert für alle anderen Aktionstypen • Größe von commandArguments (in der Regel von Argumenttext dominiert) in Azure IoT-Zwillingen auf 4 KB beschränkt; Informationen zu längeren Skripts finden Sie unter Bewährte Methoden.
  singleLineTextResult	boolean	• Wenn aktion 3 (RunCommand) ist, optional umschalten, um anzugeben, ob Zeilenneulinien aus der Konsolenausgabe entfernt werden sollen • Ignoriert für alle anderen Aktionstypen
  timeout	INT	• Wenn die Aktion 3 (runCommand) ist, werden Anforderungen mit langer Ausführungszeit nach dieser Anzahl von Sekunden beendet. • Optional (Standardwert: 30) • Ignoriert für alle anderen Aktionstypen

• Beispiele von IoT Hub und echten Geräten

  • Neustartanforderung:

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

  • Anforderung für eine benutzerdefinierte Konfiguration (Zeitzone):

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

  • Weitere Beispiele finden Sie unter:

    • Neustarten oder Herunterfahren von Geräten mit Azure IoT und OSConfig
    • Benutzerdefinierte Konfiguration und Berichterstellung mit Azure IoT und OSConfig

commandArguments (Bestätigung vom Gerät)

• Beschreibung: Dies ist die Bestätigung des OSConfig-Agents auf dem Gerät, dass er den Wert commandArguments von der Administratorseite erhalten hat.

• Pfad: properties.reported.CommandRunner.commandArguments (der Gerätebestätigungsteil der commandArguments schreibbaren Eigenschaft)

• Mitglieder:

  Name	Typ	Hinweise
  value	Karte	Sollte Spiegel properties.desired.CommandRunner.commandArguments, die das Gerät in online angibt und die Anforderung empfangen hat
  ac	INT	Statuscode, nominaler Groß-/Kleinschreibung ist Wert 200

commandStatus

• Beschreibung: Gibt die status und Ausgabe einer Anforderung an, die zuvor über commandArguments übermittelt wurde.

• Path: properties.reported.CommandRunner.commandStatus (CommandRunner component -->commandStatus read-only property)

• Mitglieder

  Name	Typ	Hinweise
  commandId	Zeichenfolge	• Gibt an, welche zuvor empfangene Anforderung derzeit von Commandstatus beschrieben wird. • Standardmäßig wird die neueste Anforderung dargestellt. • Der Aufrufer kann diesen Fokus ändern, um eine bestimmte Anforderung über den oben beschriebenen refreshCommandStatus-Mechanismus zu beschreiben.
  resultCode	INT	Der Exitcode des angeforderten Befehls. Analog zu echo $? in bash
  Currentstate	enum/int	• Nominaler Groß-/Kleinschreibungswert 2 (succeeded) • Eine vollständige Liste möglicher Werte finden Sie in den Metadaten .
  textResult	Zeichenfolge	• Die Konsolenausgabe des angeforderten Befehls • Größe von commandStatus (in der Regel von der textResult-Komponente dominiert) in Azure IoT-Zwillingen in einer Beschränkung auf 4 KB; Informationen zu längeren Ausgaben finden Sie unter Bewährte Methoden.

• Beispiele von IoT Hub und echten Geräten

  • Ergebnis des Neustarts

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

  • Ergebnis der benutzerdefinierten Konfiguration (Zeitzone):

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

  • Weitere Beispiele finden Sie unter:

    • Neustarten oder Herunterfahren von Geräten mit Azure IoT und OSConfig
    • Benutzerdefinierte Konfiguration und Berichterstellung mit Azure IoT und OSConfig

Wichtig

Version 1.0.3 (veröffentlicht am 28. Juni 2022) enthält breaking changes an Membernamen, die sich auf vorhandene Benutzer auswirken können. Weitere Informationen finden Sie unter: Membernamen übergangen von PascalCase zu camelCase in Version 1.0.3

Nächste Schritte

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

• Was ist OSconfig für IoT?

Konkrete Praktische Beispiele finden Sie unter:

• Erstellen einer OSConfig-Labumgebung (mit Azure IoT) in fünf Minuten
• Schnellstart: Abfragebeispiele für die ersten Schritte mit OSConfig und Azure IoT
• Was kann ich bereitstellen und verwalten?