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.
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:
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.
Sie benötigen mindestens ein Linux-Gerät mit dem OSConfig-Agent, der installiert und mit Azure IoT verbunden ist.
Stellen Sie sicher, dass Sie beim Azure-Portal angemeldet sind und auf die Übersichtsseite Ihres IoT Hub zugreifen können anzeigt.
Melden Sie sich beim Azure-Portal mit dem Konto an, das Sie verwenden möchten
Starten von Azure Cloud Shell im Bashmodus
(optional) Verwenden Sie den Befehl az account show , um sicherzustellen, dass Sie im Kontext angemeldet sind, den Sie für die Beispiele verwenden möchten.
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.
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).
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.
Wählen Sie auf der Portalseite Ihres Azure IoT Hub Geräteverwaltung --Konfigurationen -->Modulkonfigurationen -->Modulkonfigurationen hinzufügen.
Geben Sie einen Namen an, und legen Sie die Twin-Einstellungen mit der gewünschten Paket-Manager-Konfiguration fest. Legen Sie die Module Twin-Eigenschaft auf und legen Sie den Inhalt der Module Twin-Eigenschaft auf properties.desired.CommandRunner folgendes fest:
Erstellen Sie eine benutzerdefinierte Metrik mit erfolgreichen Namen und den Metrikkriterien wie unten dargestellt. Diese Metrikabfrage identifiziert alle Geräte, die den Endpunkt erfolgreich angepingt haben.
SELECT deviceId FROM devices.modules
WHERE properties.reported.CommandRunner.commandStatus.resultCode = 0
AND properties.reported.CommandRunner.commandStatus.commandId = 'pingcmd'
Geben Sie für die Zielmodule die Kriterien an, für die Geräte im Bereich sind. In diesem Beispiel zielen wir auf alle OSConfig-aktivierten Geräte ab, indem wir eine Zielbedingung angeben. FROM devices.modules where moduleId='osconfig'
Um zu beobachten, welche Zwillinge von Geräten mit dem gewünschten Twin-Eigenschaftsinhalt (Cloudseite) aktualisiert wurden, finden Sie in der Angewendeten Metrik (auch als appliedCount bezeichnet)
Um zu beobachten, welche Geräte den Endpunkt erfolgreich angepingt haben, finden Sie die benutzerdefinierte Erfolgreichpings-Metrik , die oben erstellt wurde.
Sie können auch die Ausgabe des in diesem Beispiel verwendeten Pingbefehls mithilfe der folgenden Abfrage überprüfen. Wählen Sie auf der Portalseite Ihres Azure IoT Hub die Option "Geräteverwaltung "->Abfragen" in der linken Navigation aus.
SELECT deviceId, properties.reported.CommandRunner.commandStatus
FROM devices.modules
WHERE properties.reported.CommandRunner.commandStatus.commandId = 'pingcmd'
Verwenden Sie den folgenden Beispielbefehl, um den OSConfig-Twin eines einzelnen Geräts festzulegen, geräte-ID> und/oder Hubname zu ersetzen<, um Ihrer Umgebung zu entsprechen.><
Sie können die Gerätekonnektivität überprüfen, indem Sie die Antwort auf den Pingbefehl überprüfen. Verwenden Sie den folgenden Beispielbefehl, der das Ergebnis des Pingbefehls abruft, geräte-ID> und/oder Hubname ersetzt,< um Ihrer Umgebung zu entsprechen.>< Suchen Sie nach resultCode: 0 , der angibt, dass der Befehl erfolgreich war und textResult , das die Ausgabe des Pingbefehls anzeigt.
az iot hub query -q \
"SELECT properties.reported.CommandRunner.commandStatus.resultCode,
properties.reported.CommandRunner.commandStatus.textResult
FROM devices.modules
WHERE moduleId='osconfig'
AND deviceId='<device id>'" --hub-name <hub name> --output table
Verwenden Sie den folgenden Beispielbefehl, um eine IoT Hub Konfiguration zu erstellen, um die Netzwerkverbindung für eine Flotte von Geräten zu überprüfen, die mit einem IoT Hub verbunden sind. Diese Konfiguration umfasst Zielkriterien, benutzerdefinierte Metriken und die gewünschte Konfiguration. Achten Sie darauf, den Hubnamen durch Ihren< IoT Hub Namen> zu ersetzen.
az iot hub configuration create -c "checkconnectivity_devicefleet" --content \
'{"moduleContent":
{"properties.desired.CommandRunner":
{"commandArguments":
{"commandId": "checkconnectivity_devicefleet",
"arguments": "ping -c 3 www.github.com",
"timeout": 120,
"singleLineTextResult": false,
"action": 3
}}}}' \
--target-condition "from devices.modules where moduleId='osconfig'" --priority 10 \
--metrics "{\"metrics\": {\"queries\": {\"successfulpings\":\"select deviceId from devices.modules \
where moduleId='osconfig' AND properties.reported.CommandRunner.commandStatus.resultCode=0 \
and properties.reported.CommandRunner.commandStatus.commandId='checkconnectivity_devicefleet'\"}}}" \
--hub-name <hub name>
Um zu beobachten, welche Zwillinge von Geräten mit dem gewünschten Twin-Eigenschaftsinhalt (Cloudseite) aktualisiert wurden, finden Sie in der Angewendeten Metrik (auch als appliedCount bezeichnet). Um zu beobachten, welche Geräte den Endpunkt erfolgreich angepingt haben, finden Sie die benutzerdefinierte Erfolgreichpings-Metrik , die oben erstellt wurde.
Verwenden Sie die folgenden Befehle, um sowohl nach angewendeten als auch benutzerdefinierten Metriken zu überprüfen, die erfolgreich ausgeführt werden.
az iot hub configuration show-metric --metric-id appliedCount \
-c "checkconnectivity_devicefleet" \
-n <hub name> --metric-type system
az iot hub configuration show-metric --metric-id successfulpings \
-c "checkconnectivity_devicefleet" \
-n <hub name> --metric-type user
Mithilfe des folgenden Befehls können Sie die Ergebnisse aus dem Pingbefehl für jedes Gerät überprüfen, um festzustellen, ob es erfolgreich war oder nicht. Suchen Sie nach resultCode: 0 , der angibt, dass der Befehl erfolgreich war und textResult , das die Ausgabe des Pingbefehls anzeigt.
az iot hub query -q \
"SELECT deviceId, properties.reported.CommandRunner.commandStatus.resultCode,
properties.reported.CommandRunner.commandStatus.textResult
FROM devices.modules
WHERE moduleId='osconfig'" \
--output table --hub-name <hub name> --output table
Sie können auch die Ausgabe des in diesem Beispiel verwendeten Pingbefehls mithilfe der folgenden Abfrage überprüfen. Wählen Sie auf der Portalseite Ihres Azure IoT Hub die Option "Geräteverwaltung "->Abfragen" in der linken Navigation aus.
textResult aus der Ausgabe zeigt den gewünschten Dateiinhalt an.
SELECT deviceId, properties.reported.CommandRunner.commandStatus
FROM devices.modules
WHERE properties.reported.CommandRunner.commandStatus.commandId = 'checkconnectivity_devicefleet'
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.
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.
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.
Wählen Sie auf der Portalseite Ihrer Azure IoT Hub die Option Geräteverwaltung -->Konfigurationen -->Modulkonfigurationen hinzufügen.
Geben Sie einen Namen an, und legen Sie die Twin-Einstellungen mit der gewünschten Paket-Manager-Konfiguration fest. Legen Sie "Module Twin"-Eigenschaft auf properties.desired.CommandRunner folgendes fest, und legen Sie den Inhalt der Module Twin-Eigenschaft auf folgendes fest:
Geben Sie für die Zielmodule die Kriterien an, für die sich Geräte im Bereich befinden. In diesem Beispiel werden alle OSConfig-fähigen Geräte durch Angeben einer Zielbedingung von FROM devices.modules where moduleId='osconfig'
Um zu beobachten, welche Zwillinge von Geräten mit dem gewünschten Twin-Eigenschaftsinhalt (cloudseitig) aktualisiert wurden, finden Sie in der Angewendeten Metrik (auch als "appliedCount" bezeichnet)
Sie können den Dateiinhalt in diesem Beispiel auch mithilfe der folgenden Abfrage lesen. Wählen Sie auf der Portalseite Ihrer Azure IoT Hub die Geräteverwaltung –->Abfragen in der linken Navigation aus. Tatsächlicher Dateiinhalt kann in commandStatus.textResult angezeigt werden.
SELECT deviceId, properties.reported.CommandRunner.commandStatus
FROM devices.modules
WHERE properties.reported.CommandRunner.commandStatus.commandId = 'sshdconfigfile_contents'
Verwenden Sie den folgenden Beispielbefehl, um die Anforderung zu initiieren (indem Sie Ihre Anforderung im properties.desired Abschnitt des Zwillings platzieren).
Verwenden Sie den folgenden Befehl, um die Ergebnisse anzuzeigen. Suchen Sie nach resultCode: 0 , der angibt, dass der Befehl erfolgreich war, und textResult , das den gewünschten Dateiinhalt anzeigt.
az iot hub query --output table -q \
"SELECT properties.reported.CommandRunner.commandStatus.resultCode,
properties.reported.CommandRunner.commandStatus.textResult
FROM devices.modules
WHERE moduleId='osconfig'
AND deviceID='<device id>'" --hub-name <hub name>
Verwenden Sie den folgenden Beispielbefehl, um eine IoT Hub Konfiguration zu erstellen. Diese Konfiguration umfasst Zielkriterien, die gewünschte Konfiguration. Ersetzen Sie den Hubnamen unbedingt durch Ihren IoT Hub Namen.
Verwenden Sie den folgenden Befehl, um die Ergebnisse anzuzeigen. Überprüfen Sie auf resultCode: 0 , der angibt, dass der Befehl erfolgreich war und textResult , das den Dateiinhalt anzeigt.
az iot hub query -q \
"SELECT deviceId, properties.reported.CommandRunner.commandStatus.resultCode,
properties.reported.CommandRunner.commandStatus.textResult
FROM devices.modules
WHERE moduleId='osconfig'" \
--output table --hub-name <hub name>
Um zu beobachten, welche Zwillinge von Geräten mit dem gewünschten Twin-Eigenschaftsinhalt (Cloudseite) aktualisiert wurden, finden Sie in der Angewendeten Metrik (auch als "appliedCount" bezeichnet).
Verwenden Sie den folgenden Befehl, um nach der angewendeten Metrik zu suchen.
az iot hub configuration show-metric --metric-id appliedCount \
-c "sshdconfigfile_contents" \
-n <hub name> --metric-type system
Sie können den Dateiinhalt auch mithilfe der folgenden Abfrage lesen. Wählen Sie auf der Portalseite Ihrer Azure IoT Hub die Geräteverwaltung –->Abfragen in der linken Navigation aus.
SELECT deviceId, properties.reported.CommandRunner.commandStatus,
properties.reported.CommandRunner.commandStatus.textResult
FROM devices.modules
WHERE properties.reported.CommandRunner.commandStatus.commandId = 'sshdconfigfile_contents'
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.
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.
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.
Um die Zeitzone für eine Flotte von Geräten auf UTC festzulegen oder zu aktualisieren, wie in diesem Beispiel, erstellen Sie eine IoT Hub Konfiguration (auch bekannt als IoT Hub Automatic Geräteverwaltung [ADM]).
Wählen Sie auf der Portalseite Ihrer Azure IoT Hub die Option Geräteverwaltung -->Konfigurationen -->Modulkonfigurationen hinzufügen.
Geben Sie einen Namen an, und legen Sie die Twin-Einstellungen mit der gewünschten Paket-Manager-Konfiguration fest. Legen Sie "Module Twin"-Eigenschaft auf properties.desired.CommandRunner folgendes fest, und legen Sie den Inhalt der Module Twin-Eigenschaft auf folgendes fest:
Geben Sie für die Zielmodule die Kriterien an, für die sich Geräte im Bereich befinden. In diesem Beispiel werden alle OSConfig-fähigen Geräte durch Angeben einer Zielbedingung von FROM devices.modules where moduleId='osconfig'
Erstellen Sie eine benutzerdefinierte Metrik mit erfolgreich konfiguriertem Namen und den Metrikkriterien wie unten dargestellt. Diese Metrikabfrage identifiziert alle Geräte, die die Zeitzone erfolgreich aktualisiert haben.
SELECT deviceId FROM devices.modules
WHERE properties.reported.CommandRunner.commandStatus.resultCode = 0
AND properties.reported.CommandRunner.commandStatus.commandId = 'settimezone_config'
Sobald die Konfiguration auf die Geräte angewendet wurde, können Sie überprüfen, welche Zwillinge der Geräte mit dem gewünschten Twin-Eigenschaftsinhalt (cloudseitig) aktualisiert wurden, indem Sie die Angewendete Metrik (auch als appliedCount bezeichnet) überprüfen. Informationen dazu, welche Geräte die Zeitzone erfolgreich aktualisiert haben, finden Sie in der oben erstellten benutzerdefinierten erfolgreich konfigurierten Metrik.
Sie können auch die aktuelle Zeitzone auf diesen Geräten mithilfe der folgenden Abfrage lesen. Wählen Sie auf der Portalseite Ihrer Azure IoT Hub die Geräteverwaltung –->Abfragen in der linken Navigation aus. Sie können die aktuelle Zeitzone auf diesen Geräten über commandStatus.textResult überprüfen.
SELECT deviceId, properties.reported.CommandRunner.commandStatus
FROM devices.modules
WHERE properties.reported.CommandRunner.commandStatus.commandId = 'settimezone_config'
Verwenden Sie das folgende Beispiel, um die Zeitzone auf dem Gerät festzulegen und dann die aktuelle Zeitzone zu lesen.
action=3 unten gibt die RunCommand-Aktion an. Ersetzen sie <die Geräte-ID> und/oder <den Hubnamen> , um Ihrer Umgebung zu entsprechen..
Sie können das Ergebnis des obigen Befehls abfragen und die aktuelle Zeitzone auf dem Gerät mithilfe des folgenden Beispiels überprüfen. Überprüfen Sie auf resultCode: 0 , der angibt, dass der Befehl erfolgreich war, und textResult zeigt die aktuelle Zeitzone an.
az iot hub query -q \
"SELECT properties.reported.CommandRunner.commandStatus.resultCode,
properties.reported.CommandRunner.commandStatus.textResult
FROM devices.modules
WHERE moduleId='osconfig'
AND deviceID='<device id>'" --hub-name <hub name> --output table
Verwenden Sie den folgenden Beispielbefehl, um eine IoT Hub Konfiguration zu erstellen. Diese Konfiguration umfasst Zielkriterien, die gewünschte Konfiguration. Achten Sie darauf, den Hubnamen durch Ihren IoT Hub Namen zu ersetzen.
az iot hub configuration create -c "settimezone_config" --content \
'{"moduleContent":
{"properties.desired.CommandRunner":
{"commandArguments":
{"commandId": "settimezone_cmd",
"arguments": "timedatectl set-timezone Etc/UTC | timedatectl | grep Time",
"timeout": 30,
"singleLineTextResult": false,
"action": 3
}}}}' \
--target-condition "from devices.modules where moduleId='osconfig'" --priority 10 \
--metrics "{\"metrics\": {\"queries\": {\"successfullyconfigured\":\"select deviceId from devices.modules \
where moduleId='osconfig' AND properties.reported.CommandRunner.commandStatus.resultCode=0 \
and properties.reported.CommandRunner.commandStatus.commandId='settimezone_cmd'\"}}}" \
--hub-name <hub-name>
Sie können abfragen, dass die Zeitzone auf den Geräten mit dem folgenden Beispiel festgelegt wird. Die aktuelle Zeitzone kann in commandStatus.textResult angezeigt werden.
az iot hub query -q \
"SELECT deviceId, properties.reported.CommandRunner.commandStatus.textResult
FROM devices.modules
WHERE moduleId='osconfig'" \
--output table --hub-name <hub name>
Um zu beobachten, welche Zwillinge von Geräten mit dem gewünschten Twin-Eigenschaftsinhalt (Cloudseite) aktualisiert wurden, finden Sie in der Angewendeten Metrik (auch als "appliedCount" bezeichnet). Um zu beobachten, welche Geräte den Endpunkt erfolgreich angepingt haben, lesen Sie die benutzerdefinierte erfolgreich konfigurierte Metrik, die oben erstellt wurde.
Verwenden Sie die folgenden Befehle, um nach beiden Metriken zu suchen.
az iot hub configuration show-metric --metric-id appliedCount \
-c "settimezone_config" \
-n <hub name> --metric-type system
az iot hub configuration show-metric --metric-id successfullyconfigured \
-c "settimezone_config" \
-n <hub name> --metric-type user
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.
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.
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:
Um eine App herunterzuladen und zu installieren oder ein Skript auf einer Flotte von Geräten auszuführen, wie in diesem Beispiel, erstellen Sie eine IoT Hub Configuration (auch als IoT Hub Automatic Geräteverwaltung [ADM]bezeichnet).
Wählen Sie auf der Portalseite Ihres Azure IoT Hub Geräteverwaltung --Konfigurationen -->Modulkonfigurationen -->Modulkonfigurationen hinzufügen.
Geben Sie einen Namen an, und legen Sie die Twin-Einstellungen mit der gewünschten Paket-Manager-Konfiguration fest. Legen Sie "Module Twin"-Eigenschaft auf properties.desired.CommandRunner den folgenden Wert fest, und legen Sie den Inhalt der Modul-Twin-Eigenschaft auf folgendes fest.
Geben Sie für die Zielmodule die Kriterien an, für die Geräte im Bereich sind. In diesem Beispiel zielen wir auf alle OSConfig-aktivierten Geräte ab, indem wir eine Zielbedingung angeben. FROM devices.modules where moduleId='osconfig'
Erstellen Sie eine benutzerdefinierte Metrik mit dem Namen erfolgreich ausgeführt und die Metrikkriterien wie unten dargestellt. Diese Metrikabfrage identifiziert alle Geräte, auf denen das Skript erfolgreich ausgeführt oder ausgeführt wurde.
SELECT deviceId
FROM devices.modules
WHERE properties.reported.CommandRunner.commandStatus.resultCode = 0
AND properties.reported.CommandRunner.commandStatus.commandId = 'runcustomscript_configuration'
Nachdem die Konfiguration auf die Geräte angewendet wurde, können Sie überprüfen, welche Zwillinge der Geräte mit dem gewünschten Twin-Eigenschaftsinhalt (cloudseitiger Inhalt) aktualisiert wurden, indem Sie nach der Angewendeten Metrik (auch als appliedCount bezeichnet) überprüfen. Informationen dazu, welche Geräte die Zeitzone erfolgreich aktualisiert haben, finden Sie in der benutzerdefinierten erfolgreich ausgeführten Metrik, die oben erstellt wurde.
Sie können auch überprüfen, ob die obige Konfiguration erfolgreich angewendet wurde und dass die Installation erfolgreich war, indem Sie die folgende Abfrage verwenden. Wählen Sie auf der Portalseite Ihres Azure IoT Hub die Option "Geräteverwaltung "->Abfragen" in der linken Navigation aus. Suchen Sie nach resultCode: 0 , der angibt, dass der Befehl erfolgreich war und textResult , das die Ausgabe aus dem Skript anzeigt.
SELECT deviceId, properties.reported.CommandRunner.commandStatus.textResult
FROM devices.modules
WHERE properties.reported.CommandRunner.commandStatus.commandId = 'runcustomscript_configuration'
Das folgende Beispiel zeigt den Download und die Ausführung eines einfachen Skripts auf einem bestimmten Gerät. Ersetzen Sie <die Geräte-ID> und/oder <den Hubnamen> , um Ihrer Umgebung zu entsprechen..
Sie können das Ergebnis des obigen Skripts auf dem Gerät mithilfe des folgenden Beispiels abfragen. Suchen Sie nach resultCode: 0 , der angibt, dass der Befehl erfolgreich war und textResult , das die Ausgabe des Skripts anzeigt.
az iot hub query -q \
"SELECT properties.reported.CommandRunner.commandStatus.resultCode,
properties.reported.CommandRunner.commandStatus.textResult
FROM devices.modules
WHERE moduleId='osconfig' AND properties.reported.CommandRunner.commandStatus.commandId = 'runcustomscript'
AND deviceId = '<device id>'" \
--hub-name <hub name> --output table
Verwenden Sie den folgenden Beispielbefehl, um eine IoT Hub Konfiguration zu erstellen, um ein benutzerdefiniertes Skript auf mehreren Geräten herunterzuladen und auszuführen. Diese Konfiguration umfasst Zielkriterien und die gewünschte Konfiguration. Achten Sie darauf, den Hubnamen durch Ihren IoT Hub Namen zu ersetzen.
az iot hub configuration create -c "runcustomscript_multipledevices" --content \
'{"moduleContent":
{"properties.desired.CommandRunner":
{"commandArguments":
{"commandId": "runcustomscript_multipledevices",
"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
}}}}' \
--target-condition "from devices.modules where moduleId='osconfig'" --priority 10 \
--metrics "{\"metrics\": {\"queries\": {\"successfulruns\":\"select deviceId from devices.modules \
where moduleId='osconfig' AND properties.reported.CommandRunner.commandStatus.resultCode=0 \
and properties.reported.CommandRunner.commandStatus.commandId='runcustomscript_multipledevices'\"}}}" \
--hub-name <hub-name>
Sie können das Ergebnis der Skriptausführung auf den Geräten überprüfen, indem Sie das folgende Beispiel verwenden. Suchen Sie nach resultCode: 0 , der angibt, dass der Befehl erfolgreich war und textResult , die die Ausgabe des ausgeführten Skripts anzeigt.
az iot hub query -q \
"SELECT deviceId, properties.reported.CommandRunner.commandStatus.resultCode,
properties.reported.CommandRunner.commandStatus.textResult
FROM devices.modules
WHERE moduleId='osconfig' AND properties.reported.CommandRunner.commandStatus.commandId = 'runcustomscript_multipledevices'" \
--output table --hub-name <hub name>
Nächste Schritte
Eine Übersicht über OSConfig-Szenarien und -Funktionen finden Sie unter: