Planen und Übertragen von Aufträgen (Azure CLI)

Artikel
03/16/2023

Verwenden Sie Azure IoT Hub zum Planen und Nachverfolgen von Aufträgen, die Millionen von Geräte aktualisieren. Verwenden Sie Aufträge zum:

Aktualisieren gewünschter Eigenschaften
Aktualisieren von Tags
Aufrufen direkter Methoden

Vom Konzept her umschließt ein Auftrag eine dieser Aktionen und verfolgt den Ausführungsfortschritt für eine Gruppe von Geräten nach. Die Geräte, mit denen ein Auftrag interagiert, werden durch eine Gerätezwilling-Abfrage definiert. Mit einem Auftrag kann eine Back-End-App beispielsweise eine Neustartmethode auf 10.000 Geräten aufrufen – angegeben durch eine Gerätezwillingsabfrage und geplant für einen späteren Zeitpunkt. Diese Anwendung kann dann den Fortschritt nachverfolgen, da jedes dieser Geräte die Neustartmethode empfängt und ausführt.

Weitere Informationen zu diesen Funktionen finden Sie in den folgenden Artikeln:

Gerätezwilling und Eigenschaften: Erste Schritte mit Gerätezwillingen (Vorschau) und Verstehen und Verwenden von Gerätezwillingen in IoT Hub
Direkte Methoden:IoT Hub-Entwicklerleitfaden – direkte Methoden

Hinweis

Die in diesem Artikel beschriebenen Features stehen nur im Standard-Tarif von IoT Hub zur Verfügung. Weitere Informationen zu den IoT Hub-Tarifen „Basic“ und „Standard/Free“ finden Sie unter Wählen des richtigen IoT Hub-Tarifs für Ihre Lösung.

In diesem Artikel erfahren Sie, wie Sie zwei Azure CLI-Sitzungen erstellen:

Eine Sitzung, die ein simuliertes Gerät erstellt. Das simulierte Gerät wird so konfiguriert, dass es einen Statuscode und eine JSON-Nutzlast zurückgibt, wenn eine direkte Methode aufgerufen wird.
Die andere Sitzung erstellt zwei geplante Aufträge. Der erste Auftrag ruft eine direkte Methode auf, und der zweite Auftrag aktualisiert eine gewünschte Gerätezwilling-Eigenschaft auf dem simulierten Gerät, das in der anderen Sitzung erstellt wurde.

Voraussetzungen

Azure-Befehlszeilenschnittstelle. Sie können die Befehle in diesem Artikel auch mithilfe von Azure Cloud Shell ausführen. Diese interaktive CLI-Shell kann in Ihrem Browser oder einer Anwendung wie Windows Terminal ausgeführt werden. Bei Verwendung der Cloud Shell müssen Sie nichts installieren. Wenn Sie es vorziehen, die Befehlszeilenschnittstelle lokal zu verwenden, benötigen Sie für diesen Artikel mindestens die Azure CLI-Version 2.36. Führen Sie az --version aus, um die Version zu ermitteln. Informationen zur Installation oder zum Upgrade der Azure CLI finden Sie unter Installieren der Azure CLI.
Ein IoT Hub in Ihrem Azure-Abonnement. Erstellen Sie einen mit der CLI oder dem Azure-Portal.
Stellen Sie sicher, dass der Port 8883 in Ihrer Firewall geöffnet ist. Das Beispielgerät in diesem Artikel verwendet das MQTT-Protokoll, das über Port 8883 kommuniziert. In einigen Netzwerkumgebungen von Unternehmen oder Bildungseinrichtungen ist dieser Port unter Umständen blockiert. Weitere Informationen und Problemumgehungen finden Sie unter Herstellen einer Verbindung mit IoT Hub (MQTT).

Vorbereiten von Cloud Shell

Wenn Sie Azure Cloud Shell verwenden möchten, müssen Sie den Dienst zuerst starten und konfigurieren. Falls Sie die CLI lokal nutzen, können Sie zum Abschnitt Vorbereiten von zwei CLI-Sitzungen springen.

Wählen Sie im Azure-Portal in der Kopfzeile der Seite das Symbol Cloud Shell aus.

Hinweis

Falls Sie die Cloud Shell bisher noch nicht verwendet haben, werden Sie zum Erstellen von Speicher aufgefordert, der für die Nutzung der Cloud Shell erforderlich ist. Wählen Sie ein Abonnement aus, in dem ein Speicherkonto und eine Microsoft Azure Files-Freigabe erstellt werden sollen.
Verwenden Sie die Umgebungsauswahl auf der Cloud Shell-Symbolleiste, um Ihre bevorzugte CLI-Umgebung auszuwählen. In diesem Artikel wird die Bash-Umgebung verwendet. Sie können auch die PowerShell-Umgebung verwenden.

Hinweis

Einige Befehle erfordern eine andere Syntax oder Formatierung in der Bash- und der PowerShell-Umgebung. Weitere Informationen finden Sie unter Tipps zur erfolgreichen Verwendung der Azure CLI.

Vorbereiten von zwei CLI-Sitzungen

Als Nächstes müssen Sie zwei Azure CLI-Sitzungen vorbereiten. Wenn Sie Cloud Shell verwenden, führen Sie diese Sitzungen auf separaten Cloud Shell-Registerkarten aus. Wenn Sie einen lokalen CLI-Client nutzen, führen Sie separate CLI-Instanzen aus. Verwenden Sie die separaten CLI-Sitzungen für die folgenden Aufgaben:

Die erste Sitzung simuliert ein IoT-Gerät, das mit Ihrem IoT-Hub kommuniziert.
In der zweiten Sitzung werden Aufträge für Ihr simuliertes Gerät mit Ihrem IoT-Hub geplant.

Hinweis

Für die Nutzung der Azure CLI müssen Sie bei Ihrem Azure-Konto angemeldet sein. Wenn Sie Cloud Shell verwenden, werden Sie automatisch bei Ihrem Azure-Konto angemeldet. Wenn Sie einen lokalen CLI-Client verwenden, müssen Sie sich bei den einzelnen CLI-Sitzungen anmelden. Die gesamte Kommunikation zwischen Ihrer Azure CLI-Shell-Sitzung und Ihrem IoT-Hub wird authentifiziert und verschlüsselt. Bei diesem Artikel ist daher keine weitere Authentifizierung, z. B. per Verbindungszeichenfolge, wie bei einem echten Gerät erforderlich. Weitere Informationen zum Anmelden mit der Azure-Befehlszeilenschnittstelle finden Sie unter Anmelden mit der Azure CLI.

Führen Sie in der ersten CLI-Sitzung den Befehl az extension add aus. Der Befehl fügt Ihrer CLI-Shell die Microsoft Azure IoT-Erweiterung für Azure CLI hinzu. Die Erweiterung fügt der Azure-Befehlszeilenschnittstelle spezifische Befehle für IoT Hub, IoT Edge und IoT Device Provisioning Service (DPS) hinzu. Nachdem Sie die Erweiterung installiert haben, müssen Sie sie in Cloud Shell-Sitzungen nicht erneut installieren.
```
az extension add --name azure-iot
```
Hinweis

In diesem Artikel wird die neueste Version der Azure IoT-Erweiterung namens azure-iot verwendet. Die Legacy-Version heißt azure-cli-iot-ext. Es sollte jedoch jeweils nur eine Version installiert sein. Sie können den Befehl az extension list verwenden, um die derzeit installierten Erweiterungen zu überprüfen.

Verwenden Sie az extension remove --name azure-cli-iot-ext, um die Legacy-Version der Erweiterung zu entfernen.

Verwenden Sie az extension add --name azure-iot, um die neue Version der Erweiterung hinzuzufügen.

Verwenden Sie az extension list, um die installierten Erweiterungen anzuzeigen.
Öffnen Sie die zweite CLI-Sitzung. Wenn Sie Cloud Shell in einem Browser verwenden, wählen Sie auf der Symbolleiste Ihrer ersten CLI-Sitzung das Symbol Neue Sitzung öffnen aus. Wenn Sie die CLI lokal nutzen, öffnen Sie eine zweite CLI-Instanz.

Erstellen und Simulieren eines Geräts

In diesem Abschnitt erstellen Sie in der ersten CLI-Sitzung eine Geräteidentität für Ihren IoT-Hub und simulieren dann mithilfe dieser Geräteidentität ein Gerät. Das simulierte Gerät reagiert auf die Aufträge, die Sie in der zweiten CLI-Sitzung planen.

Erstellen und starten Sie ein simuliertes Gerät wie folgt:

Führen Sie in der ersten CLI-Sitzung den Befehl az iot hub device-identity create aus, und ersetzen Sie die folgenden Platzhalter durch die entsprechenden Werte. Mit diesem Befehl wird die Geräteidentität für Ihr simuliertes Gerät erstellt.

{DeviceName}. Der Name Ihres simulierten Geräts.

{HubName}. Der Name Ihres IoT-Hubs.
```
az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName} 
```
Führen Sie in der ersten CLI-Sitzung den Befehl az iot device simulate aus, und ersetzen Sie die folgenden Platzhalter durch die entsprechenden Werte. Mit diesem Befehl wird das Gerät simuliert, das Sie im vorherigen Schritt erstellt haben. Das simulierte Gerät wird so konfiguriert, dass es einen Statuscode und eine Nutzlast zurückgibt, wenn eine direkte Methode aufgerufen wird.

{DeviceName}. Der Name Ihres simulierten Geräts.

{HubName}. Der Name Ihres IoT-Hubs.
```
az iot device simulate --device-id {DeviceName} --hub-name {HubName} \
                       --method-response-code 201 \
                       --method-response-payload '{"result":"Direct method successful"}'
```
Tipp

Standardmäßig sendet der Befehl az iot device simulate in einem Intervall von drei Sekunden zwischen Nachrichten 100 Gerät-zu-Cloud-Nachrichten. Die Simulation endet, sobald alle Nachrichten gesendet wurden. Wenn Sie die Simulation länger ausführen möchten, können Sie mithilfe des Parameters --msg-count mehr Nachrichten festlegen. Der Parameter --msg-interval erlaubt es Ihnen, ein längeres Intervall zwischen den Nachrichten festzulegen. Sie können den Befehl auch noch einmal ausführen, um das simulierte Gerät neu zu starten.

Planen eines Auftrags zum Aufrufen einer direkten Methode

In diesem Abschnitt planen Sie einen Auftrag in der zweiten CLI-Sitzung, um eine direkte Methode auf dem simulierten Gerät aufzurufen, das in der ersten CLI-Sitzung ausgeführt wird.

Vergewissern Sie sich, dass das simulierte Gerät in der ersten CLI-Sitzung ausgeführt wird. Wenn nicht, starten Sie es neu, indem Sie den Befehl az iot device simulate aus dem Abschnitt Erstellen und Simulieren eines Geräts noch einmal ausführen.
Führen Sie in der zweiten CLI-Sitzung den Befehl az iot hub job create aus, und ersetzen Sie die folgenden Platzhalter durch die entsprechenden Werte. In diesem Beispiel gibt es keine bereits vorhandene Methode für das Gerät. Der Befehl plant einen Auftrag, der einen beispielhaften Methodennamen auf dem simulierten Gerät aufruft und einen NULL-Wert für die Nutzlast der Methode bereitstellt. Die Methode liefert als Antwort einen Statuscode und eine Nutzlast.

{HubName}. Der Name Ihres IoT-Hubs.

{JobName}. Der Name Ihres geplanten Auftrags. Auftragsnamen sind eindeutig. Wählen Sie daher bei jeder Ausführung dieses Befehls einen anderen Auftragsnamen aus.

{MethodName}. Der Name Ihrer direkten Methode. Das simulierte Gerät verfügt nicht über eine bereits vorhandene Methode, sodass Sie einen beliebigen Namen für diesen Befehl auswählen können.

{DeviceName}. Der Name Ihres simulierten Geräts.
```
az iot hub job create --hub-name {HubName} --job-id {JobName} \
                      --job-type scheduleDeviceMethod \
                      --method-name {MethodName} --method-payload 'null' \
                      --query-condition "deviceId = '{DeviceName}'"
```
Tipp

Wenn Sie mithilfe des Befehl az iot hub job create einen Auftrag planen, der eine direkte Methode aufruft, müssen Sie Werte für die beiden optionalen Parameter „--method-name“ und „--method-payload“ angeben. Geben Sie bei direkten Methoden, die keine Nutzlast akzeptieren, „null“ für den Parameter „--method-payload“ an.
Vergewissern Sie sich in der ersten CLI-Sitzung, dass die Ausgabe den Aufruf der Methode anzeigt. Im folgenden Screenshot haben wir im CLI-Befehl „az iot hub job create“ des vorherigen Schritts „SampleDevice“ und „SampleMethod“ für die Platzhalter „{DeviceName}“ und „{MethodName}“ verwendet.

Planen eines Auftrags zum Aktualisieren der Eigenschaften eines Gerätezwillings

In diesem Abschnitt planen Sie einen Auftrag in der zweiten CLI-Sitzung, um das simulierte Gerät, das in der ersten CLI-Sitzung ausgeführt wird, mit einer erwünschten Gerätezwillingseigenschaft zu aktualisieren.

Vergewissern Sie sich, dass das simulierte Gerät in der ersten CLI-Sitzung ausgeführt wird. Wenn nicht, starten Sie es neu, indem Sie den Befehl az iot device simulate aus dem Abschnitt Erstellen und Simulieren eines Geräts noch einmal ausführen.
Führen Sie in der zweiten CLI-Sitzung den Befehl az iot hub job create aus, und ersetzen Sie die folgenden Platzhalter durch die entsprechenden Werte. In diesem Beispiel planen wir einen Auftrag, um den Wert der gewünschten Zwillingseigenschaft „BuildingNo“ bei unserem simulierten Gerät auf 45 festzulegen.

{HubName}. Der Name Ihres IoT-Hubs.

{JobName}. Der Name Ihres geplanten Auftrags. Auftragsnamen sind eindeutig. Wählen Sie daher bei jeder Ausführung dieses Befehls einen anderen Auftragsnamen aus.

{DeviceName}. Der Name Ihres simulierten Geräts.
```
az iot hub job create --hub-name {HubName} --job-id {JobName} \
                      --job-type scheduleUpdateTwin \
                      --twin-patch '{"properties":{"desired": {"BuildingNo": 45}}}' \
                      --query-condition "deviceId = '{DeviceName}'"
```
Vergewissern Sie sich, dass in der Ausgabe der ersten CLI-Sitzung das erfolgreiche Update für die gemeldete Gerätezwillingseigenschaft anzeigt wird, was zeigt, dass auch die gewünschte aktualisiert wurde.

Nächste Schritte

In diesem Artikel haben Sie die Azure-Befehlszeilenschnittstelle verwendet, um ein Gerät zu simulieren und Aufträge zum Ausführen einer direkten Methode zu planen sowie die Gerätezwillingseigenschaften dieses simulierten Geräts zu aktualisieren.

Um IoT Hub und Geräteverwaltungsmuster weiter zu erkunden, aktualisieren Sie ein Image in Device Update for Azure IoT Hub unter Verwendung des Raspberry Pi 3 B+-Referenzimages.

Share via