Erste Schritte mit der Geräteverwaltung (Python)

Artikel
03/18/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 wird veranschaulicht, wie eine Back-End-App und eine Geräte-App zusammen verwendet werden können, um einen Remoteneustart des Geräts mithilfe von IoT Hub zu initiieren und zu überwachen.

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) von einer Back-End-App aus in der Cloud 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 eine Back-End-App in der Cloud verwenden, um Gerätezwillingsabfragen auszuführen und Berichte zum Status der Geräteverwaltungsaktionen zu erstellen.

In diesem Artikel wird gezeigt, wie Sie Folgendes erstellen:

dmpatterns_getstarted_device.py: eine simulierte Geräte-App mit einer direkten Methode, die das Gerät neu startet und die letzte Neustartzeit meldet. Direkte Methoden werden aus der Cloud aufgerufen.
dmpatterns_getstarted_service.js: eine Python-Konsolen-App, die die direkte Methode in der simulierten Geräte-App über Ihren IoT-Hub aufruft. Sie zeigt die Antwort und aktualisierte gemeldete Eigenschaften an.

Hinweis

Weitere Informationen zu den verfügbaren SDK-Tools zum Erstellen von Geräte- und Back-End-Apps finden Sie unter Azure IoT-SDKs.

Voraussetzungen

Ein aktives Azure-Konto. (Wenn Sie nicht über ein Konto verfügen, können Sie in nur wenigen Minuten ein kostenloses Konto erstellen.)
Einen IoT Hub. Erstellen Sie einen mit der CLI oder dem Azure-Portal.
Ein registriertes Gerät. Registrieren Sie eins im Azure-Portal.
Empfohlen wird Python, Version 3.7 oder höher. Stellen Sie je nach Einrichtung sicher, dass die 32-Bit- bzw. die 64-Bit-Installation verwendet wird. Fügen Sie Python Ihrer plattformspezifischen Umgebungsvariablen hinzu, wenn Sie während der Installation dazu aufgefordert werden.
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).

Registrieren eines neuen Geräts beim IoT-Hub

In diesem Abschnitt wird die Azure-Befehlszeilenschnittstelle verwendet, um eine Geräteidentität für diesen Artikel zu erstellen. Bei Geräte-IDs wird die Groß-/Kleinschreibung beachtet.

Öffnen Sie Azure Cloud Shell.
Führen Sie in Azure Cloud Shell den folgenden Befehl aus, um die Microsoft Azure IoT-Erweiterung für die Azure-Befehlszeilenschnittstelle zu installieren:
```
az extension add --name azure-iot
```
Erstellen Sie mithilfe der folgenden Befehle eine neue Geräteidentität mit dem Namen myDeviceId, und rufen Sie die Verbindungszeichenfolge für das Gerät ab:
```
az iot hub device-identity create --device-id myDeviceId --hub-name {Your IoT Hub name} --resource-group {Resource group of the Hub}
az iot hub device-identity connection-string show --device-id myDeviceId --hub-name {Your IoT Hub name} --resource-group {Resource group of the Hub} -o table
```
Wichtig

Diese Geräte-ID ist unter Umständen in den Protokollen sichtbar, die für den Kundensupport und die Problembehandlung erfasst werden. Stellen Sie also sicher, dass Sie beim Benennen keine sensiblen Informationen verwenden.

Notieren Sie sich die Verbindungszeichenfolge für das Gerät aus dem Ergebnis. Diese Geräteverbindungszeichenfolge wird von der Geräte-App verwendet, um die Verbindung mit Ihrem IoT Hub als Gerät herzustellen.

Erstellen einer Geräte-App mit einer direkten Methode

In diesem Abschnitt führen Sie folgende Schritte aus:

Erstellen einer Python-Konsolen-App, die auf eine von der Cloud aufgerufene direkte Methode antwortet
Simulieren eines Geräteneustarts
Verwenden der gemeldeten Eigenschaften, um Gerätezwillingsabfragen zu ermöglichen, die Geräte und den Zeitpunkt ihres letzten Neustarts ermitteln

Erstellen Sie in der oben verwendeten Azure Cloud Shell-Instanz oder in einer anderen Umgebung mit Python den Gerätecode.

Führen Sie an der Eingabeaufforderung den folgenden Befehl aus, um das Paket azure-iot-device zu installieren:
```
pip install azure-iot-device
```
Erstellen Sie mit einem Text-Editor in Ihrem Arbeitsverzeichnis eine Datei namens dmpatterns_getstarted_device.py.
Fügen Sie am Anfang der Datei importdmpatterns_getstarted_device.pydie folgenden-Anweisungen ein.
```
import time
import datetime
from azure.iot.device import IoTHubDeviceClient, MethodResponse
```
Fügen Sie die Variable CONNECTION_STRING hinzu. Ersetzen Sie den Platzhalterwert {deviceConnectionString} durch Ihre Geräteverbindungszeichenfolge. Diese Verbindungszeichenfolge haben Sie zuvor unter Registrieren eines neuen Geräts beim IoT-Hub kopiert.
```
CONNECTION_STRING = "{deviceConnectionString}"
```

Fügen Sie die folgende Funktion hinzu, um einen Client zu instanziieren, der für direkte Methoden auf dem Gerät konfiguriert wurde.

def create_client():
    # Instantiate the client
    client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

    # Define the handler for method requests
    def method_request_handler(method_request):
        if method_request.name == "rebootDevice":
            # Act on the method by rebooting the device
            print("Rebooting device")
            time.sleep(20)
            print("Device rebooted")

            # ...and patching the reported properties
            current_time = str(datetime.datetime.now())
            reported_props = {"rebootTime": current_time}
            client.patch_twin_reported_properties(reported_props)
            print( "Device twins updated with latest rebootTime")

            # Create a method response indicating the method request was resolved
            resp_status = 200
            resp_payload = {"Response": "This is the response from the device"}
            method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)

        else:
            # Create a method response indicating the method request was for an unknown method
            resp_status = 404
            resp_payload = {"Response": "Unknown method"}
            method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)

        # Send the method response
        client.send_method_response(method_response)

    try:
        # Attach the handler to the client
        client.on_method_request_received = method_request_handler
    except:
        # In the event of failure, clean up
        client.shutdown()

    return client

Starten Sie das Beispiel zur direkten Methode, und warten Sie.

def main():
    print ("Starting the IoT Hub Python sample...")
    client = create_client()

    print ("Waiting for commands, press Ctrl-C to exit")
    try:
        # Wait for program exit
        while True:
            time.sleep(1000)
    except KeyboardInterrupt:
        print("IoTHubDeviceClient sample stopped")
    finally:
        # Graceful exit
        print("Shutting down IoT Hub Client")
        client.shutdown()

if __name__ == '__main__':
    main()

Speichern und schließen Sie die Datei dmpatterns_getstarted_device.py.

Hinweis

Der Einfachheit halber wird in diesem Tutorial keine Wiederholungsrichtlinie implementiert. Im Produktionscode sollten Sie Wiederholungsrichtlinien implementieren (z.B. exponentielles Backoff), wie es im Artikel Behandeln vorübergehender Fehler vorgeschlagen wird.

Abrufen der IoT-Hub-Verbindungszeichenfolge

In diesem Artikel erstellen Sie einen Back-End-Dienst, der eine direkte Methode auf einem Gerät aufruft. Ihr Dienst muss über die Berechtigung Dienstverbindung verfügen, um über IoT Hub eine direkte Methode auf einem Gerät aufrufen zu können. Standardmäßig wird jeder IoT-Hub mit einer SAS-Richtlinie namens service erstellt, die diese Berechtigung erteilt.

Führen Sie zum Abrufen der IoT-Hub-Verbindungszeichenfolge für die Richtlinie service die folgenden Schritte aus:

Wählen Sie im Azure-Portal die Option Ressourcengruppen aus. Wählen Sie die Ressourcengruppe aus, in der sich der Hub befindet, und wählen Sie dann in der Liste der Ressourcen Ihren Hub aus.
Wählen Sie im linken Bereich Ihres IoT-Hubs Freigegebene Zugriffsrichtlinien aus.
Wählen Sie in der Liste der Richtlinien die Richtlinie service aus.
Kopieren Sie die primäre Verbindungszeichenfolge und speichern Sie den Wert.

Weitere Informationen zu SAS-Richtlinien und Berechtigungen für IoT-Hubs finden Sie unter Access Control und Berechtigungen.

Erstellen einer Dienst-App zum Auslösen eines Neustarts

In diesem Abschnitt erstellen Sie eine Python-Konsolen-App, die einen Remote-Neustart auf einem Gerät über eine direkte Methode auslöst. Die App verwendet Gerätezwillingsabfragen, um den Zeitpunkt des letzten Neustarts bei diesem Gerät zu ermitteln.

Erstellen Sie in Azure Cloud Shell-Instanz oder in einer anderen Umgebung mit Python den Konsolencode.

Führen Sie an der Eingabeaufforderung den folgenden Befehl aus, um das Paket azure-iot-hub zu installieren:
```
pip install azure-iot-hub
```
Erstellen Sie mit einem Text-Editor in Ihrem Arbeitsverzeichnis eine Datei namens dmpatterns_getstarted_service.py.

Fügen Sie am Anfang der Datei dmpatterns_getstarted_service.py die folgenden import-Anweisungen ein.

import sys, time

from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import CloudToDeviceMethod, CloudToDeviceMethodResult, Twin

Fügen Sie die folgenden Variablendeklarationen hinzu. Ersetzen Sie den Platzhalterwert {IoTHubConnectionString} durch die IoT-Hub-Verbindungszeichenfolge, die Sie zuvor unter Abrufen der IoT-Hub-Verbindungszeichenfolge kopiert haben. Ersetzen Sie den Platzhalterwert {deviceId} durch die Geräte-ID, die Sie unter Registrieren eines neuen Geräts beim IoT-Hub registriert haben.
```
CONNECTION_STRING = "{IoTHubConnectionString}"
DEVICE_ID = "{deviceId}"

METHOD_NAME = "rebootDevice"
METHOD_PAYLOAD = "{\"method_number\":\"42\"}"
TIMEOUT = 60
WAIT_COUNT = 10
```

Fügen Sie die folgende Funktion zum Aufrufen der Gerätemethode zum Neustart des Zielgeräts hinzu, fragen Sie dann die Gerätezwillinge ab, und rufen Sie den Zeitpunkt des letzten Neustarts ab.

def iothub_devicemethod_sample_run():
    try:
        # Create IoTHubRegistryManager
        registry_manager = IoTHubRegistryManager(CONNECTION_STRING)

        print ( "" )
        print ( "Invoking device to reboot..." )

        # Call the direct method.
        deviceMethod = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
        response = registry_manager.invoke_device_method(DEVICE_ID, deviceMethod)

        print ( "" )
        print ( "Successfully invoked the device to reboot." )

        print ( "" )
        print ( response.payload )

        while True:
            print ( "" )
            print ( "IoTHubClient waiting for commands, press Ctrl-C to exit" )

            status_counter = 0
            while status_counter <= WAIT_COUNT:
                twin_info = registry_manager.get_twin(DEVICE_ID)

                if twin_info.properties.reported.get("rebootTime") != None :
                    print ("Last reboot time: " + twin_info.properties.reported.get("rebootTime"))
                else:
                    print ("Waiting for device to report last reboot time...")

                time.sleep(5)
                status_counter += 1

    except Exception as ex:
        print ( "" )
        print ( "Unexpected error {0}".format(ex) )
        return
    except KeyboardInterrupt:
        print ( "" )
        print ( "IoTHubDeviceMethod sample stopped" )

if __name__ == '__main__':
    print ( "Starting the IoT Hub Service Client DeviceManagement Python sample..." )
    print ( "    Connection string = {0}".format(CONNECTION_STRING) )
    print ( "    Device ID         = {0}".format(DEVICE_ID) )

    iothub_devicemethod_sample_run()

Speichern und schließen Sie die Datei dmpatterns_getstarted_service.py.

Ausführen der Apps

Sie können nun den Gerätecode und den Dienstcode ausführen, der einen Neustart des Geräts initiiert.

Führen Sie an der Eingabeaufforderung, über die Sie das Gerät erstellt haben, den folgenden Befehl aus, um mit dem Lauschen auf die direkte Methode zum Neustarten zu beginnen.
```
python dmpatterns_getstarted_device.py
```
Führen Sie an der Eingabeaufforderung, über die Sie den Dienst erstellen, den folgenden Befehl aus, um den Remoteneustart und die Abfrage an den Gerätezwilling zum Suchen des letzten Neustartzeitpunkts auszulösen.
```
python dmpatterns_getstarted_service.py
```
Die Reaktion des Geräts auf die direkte Methode wird in der Konsole angezeigt.

Das folgende Beispiel zeigt die Reaktion des Geräts auf die direkte Methode für den Neustart:

Das folgende Beispiel zeigt, wie der Dienst die direkte Methode für den Neustart aufruft und den Status des Gerätezwillings abfragt:

Anpassen und Erweitern der Geräteverwaltungsaktionen

Ihre IoT-Lösungen können die festgelegten Geräteverwaltungsmuster erweitern oder benutzerdefinierte Muster ermöglichen. Dazu werden die Grundtypen für die Gerätezwillings- oder die C2D-Methode verwendet. Andere Beispiele für Geräteverwaltungsaktionen sind das Zurücksetzen auf die Werkseinstellungen, Firmware- und Softwareaktualisierungen, Energieverwaltung, Netzwerk- und Konnektivitätsverwaltung und Datenverschlüsselung.

Gerätewartungsfenster

In der Regel konfigurieren Sie die Ausführung von Aktionen für Geräte so, dass Unterbrechungen und Ausfallzeiten auf ein Minimum beschränkt sind. Bei Gerätewartungsfenstern handelt es sich um ein häufig verwendetes Muster zum Festlegen des Zeitpunkts, zu dem ein Gerät seine Konfiguration aktualisieren soll. Ihre Back-End-Lösungen können die gewünschten Eigenschaften des Gerätezwillings verwenden, um auf Ihrem Gerät eine Richtlinie zur Aktivierung eines Wartungsfensters festzulegen und zu aktivieren. Wenn ein Gerät die Wartungsfensterrichtlinie erhält, kann es mithilfe der gemeldeten Eigenschaft des Gerätezwillings den Richtlinienstatus melden. Die Back-End-App kann dann mithilfe von Gerätezwillingsabfragen die Konformität von Geräten und den einzelnen Richtlinien sicherstellen.

Nächste Schritte

In diesem Artikel haben Sie eine direkte Methode zum Auslösen eines Remoteneustarts auf einem Gerät verwendet. Sie haben die gemeldeten Eigenschaften zum Melden des letzten Neustartzeitpunkts des Geräts verwendet. Darüber hinaus haben Sie den Gerätezwilling abgefragt, um den letzten Neustartzeitpunkt des Geräts aus der Cloud zu ermitteln.

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

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

Freigeben über

Erste Schritte mit der Geräteverwaltung (Python)

Voraussetzungen

Registrieren eines neuen Geräts beim IoT-Hub

Erstellen einer Geräte-App mit einer direkten Methode

Abrufen der IoT-Hub-Verbindungszeichenfolge

Erstellen einer Dienst-App zum Auslösen eines Neustarts

Ausführen der Apps

Anpassen und Erweitern der Geräteverwaltungsaktionen

Gerätewartungsfenster

Nächste Schritte

Zusätzliche Ressourcen