Erste Schritte mit der Geräteverwaltung (Azure CLI)

Artikel
03/19/2023

Back-End-Apps können Azure IoT Hub-Primitive wie Gerätezwillinge und direkte Methoden verwenden, um Aktionen zur Geräteverwaltung auf Geräten remote zu starten und zu überwachen. In diesem Artikel erfahren Sie, wie die Azure CLI und ein Gerät zusammen verwendet werden können, um eine direkte Methode für ein Gerät mithilfe von IoT Hub aufzurufen.

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.

Verwenden Sie eine direkte Methode, um Geräteverwaltungsaktionen (wie Neustarts, Zurücksetzen auf Werkseinstellungen und Firmwareaktualisierung) über eine Azure CLI-Sitzung zu initiieren. Das Gerät ist für Folgendes verantwortlich:

Verarbeiten der von IoT Hub gesendeten Methodenanforderung
Initiieren der entsprechenden gerätespezifischen Aktion auf dem Gerät.
Senden von Statusupdates über die gemeldeten Eigenschaften an IoT Hub

Sie können die Azure CLI verwenden, um Gerätezwillingsabfragen auszuführen und Berichte zum Status der Geräteverwaltungsaktionen zu erstellen. Weitere Informationen zur Verwendung von direkten Methoden finden Sie unter Leitfaden zur C2D-Kommunikation.

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.
Eine Sitzung, die eine direkte Methode auf dem simulierten Gerät aufruft, 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. Wenn Sie noch keinen Hub haben, können Sie die Schritte unter Erstellen eines IoT-Hubs ausführen.
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.
Die zweite Sitzung ruft mithilfe Ihres IoT-Hubs eine direkte Methode über das simulierte Gerät auf.

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 direkten Methoden, die Sie in der zweiten CLI-Sitzung aufrufen.

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 ein Gerät mithilfe der Geräteidentität simuliert, die 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.

Aufrufen einer direkten Methode

In diesem Abschnitt verwenden Sie die zweite 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 ruft einen Beispielmethodennamen auf dem simulierten Gerät auf. Die Methode liefert als Antwort einen Statuscode und eine Nutzlast.

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

{HubName}. Der Name Ihres IoT-Hubs.

{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.
```
az iot hub invoke-device-method --device-id {DeviceName} --hub-name {HubName} \
                                --method-name {MethodName}
```
Vergewissern Sie sich in der ersten CLI-Sitzung, dass die Ausgabe den Methodenaufruf anzeigt. Im folgenden Screenshot haben wir im CLI-Befehl az iot hub invoke-device-methodSampleDevice und SampleMethod für die Platzhalter {DeviceName} und {MethodName} verwendet.
Vergewissern Sie sich in der zweiten CLI-Sitzung, dass die Ausgabe den Statuscode und die Nutzlast anzeigt, die von der aufgerufenen Methode empfangen wurden.

Aufrufen einer direkten Methode mit einer Nutzlast

In diesem Abschnitt verwenden Sie die zweite CLI-Sitzung, um eine direkte Methode aufzurufen und eine Nutzlast an das simulierte Gerät zu übermitteln, 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 ruft einen Beispielmethodennamen auf dem simulierten Gerät auf und stellt eine Nutzlast für diese Methode bereit. Die Methode liefert als Antwort einen Statuscode und eine Nutzlast.

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

{HubName}. Der Name Ihres IoT-Hubs.

{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.
```
az iot hub invoke-device-method --device-id {DeviceName} --hub-name {HubName} \
                                --method-name {MethodName} \
                                --method-payload '{ "SamplePayload": "PayloadValue" }'
```
Vergewissern Sie sich in der ersten CLI-Sitzung, dass die Ausgabe den Methodenaufruf anzeigt. Im folgenden Screenshot haben wir im CLI-Befehl az iot hub invoke-device-methodSampleDevice und SampleMethod für die Platzhalter {DeviceName} und {MethodName} verwendet.
Vergewissern Sie sich in der zweiten CLI-Sitzung, dass die Ausgabe den Statuscode und die Nutzlast anzeigt, die von der aufgerufenen Methode empfangen wurden.

Nächste Schritte

Unter Planen und Übertragen von Aufträgen erfahren Sie, wie Sie mithilfe der Azure CLI Ihre IoT-Lösung erweitern und Methodenaufrufe für Geräte planen.

Informationen zu weiteren ersten Schritten mit IoT Hub und Geräteverwaltungsmustern wie z. B. einem imagebasierten End-to-End-Update finden Sie unter Tutorial: Device Update for Azure IoT Hub unter Verwendung des Raspberry Pi 3 B+-Referenzimages.

Freigeben über