Erste Schritte mit der Modulidentität und dem Modulzwilling von IoT Hub (Python)

Artikel
10/01/2024

Modulidentitäten und Modulzwillinge ähneln den Geräteidentitäten und Gerätezwillingen von Azure IoT Hub, ermöglichen jedoch eine feinere Granularität. Azure IoT Hub-Geräteidentitäten und -Gerätezwillinge ermöglichen der Back-End-Anwendung die Konfiguration eines Geräts. Außerdem geben sie Aufschluss über den Gerätezustand. Modulidentitäten und Modulzwillinge bieten diese Funktionalität hingegen für einzelne Komponenten eines Geräts. Auf geeigneten Geräten mit mehreren Komponenten (beispielsweise auf Betriebssystem- oder Firmwaregeräten) ermöglichen sie isolierte Konfiguration und Zustände für jede Komponente.

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.

Am Ende dieses Artikels haben Sie drei Python-Apps:

CreateModule: Hiermit werden eine Geräteidentität, eine Modulidentität und zugeordnete Sicherheitsschlüssel zum Verbinden Ihrer Geräte- und Modulclients erstellt.
UpdateModuleTwinReportedProperties: Hiermit werden aktualisierte gewünschte Eigenschaften für den Modulzwilling an Ihren IoT Hub gesendet.
ReceiveModuleTwinDesiredPropertiesPatch:Hiermit wird der Patch mit den gewünschten Eigenschaften für den Modulzwilling auf Ihrem Gerät empfangen.

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.)
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.
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.

Modulauthentifizierung

Sie können symmetrische Schlüssel oder X.509-Zertifikate verwenden, um Modulidentitäten zu authentifizieren. Für die X.509-Zertifikatauthentifizierung muss das Zertifikat des Moduls seinen allgemeinen Namen (Common Name, CN) wie CN=<deviceid>/<moduleid> formatiert haben. Zum Beispiel:

openssl req -new -key d1m1.key.pem -out d1m1.csr -subj "/CN=device01\/module01"

Abrufen der IoT-Hub-Verbindungszeichenfolge

In diesem Artikel erstellen Sie einen Back-End-Dienst, der ein Gerät in der Identitätsregistrierung hinzufügt und dann diesem Gerät ein Modul. Dieser Dienst erfordert die Berechtigung Schreibvorgänge in Registrierung (die auch Lesevorgänge in Registrierung umfasst). Außerdem erstellen Sie einen Dienst, der dem Modulzwilling für das neu erstellte Modul gewünschte Eigenschaften hinzufügt. Dieser Dienst erfordert die Berechtigung Dienstverbindung. Obwohl es standardmäßige SAS-Richtlinien gibt, mit denen diese Berechtigungen einzeln erteilt werden, erstellen Sie in diesem Abschnitt eine benutzerdefinierte SAS-Richtlinie, die beide Berechtigungen enthält.

Wenn Sie eine SAS-Richtlinie, die die Berechtigungen Dienstverbindung und Schreibvorgänge in Registrierung gewährt, und eine Verbindungszeichenfolge für diese Richtlinie abrufen möchten, führen Sie 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 Hubs SAS-Richtlinien aus.
Wählen Sie im Menü über der Richtlinienliste die Option SAS-Richtlinie hinzufügen aus.
Geben Sie unter Richtlinie für den gemeinsamen Zugriff hinzufügen einen aussagekräftigen Namen für Ihre Richtlinie ein (z. B. serviceAndRegistryReadWrite). Wählen Sie unter Berechtigungen die Berechtigungen Schreibvorgänge in Registrierung und Dienstverbindung und dann Hinzufügen aus. (Wenn Sie Schreibvorgänge in Registrierung auswählen, wird die Berechtigung Lesevorgänge in Registrierung automatisch einbezogen.)
Wählen Sie Ihre neue Richtlinie aus der Liste der Richtlinien aus.
Wählen Sie unter Schlüssel für gemeinsamen Zugriff das Kopiersymbol für Primäre Verbindungszeichenfolge aus, und speichern Sie den Wert.

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

Wichtig

Dieser Artikel enthält Schritte zum Herstellen einer Verbindung mit einem Dienst mithilfe einer Shared Access Signature. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung bei einem Dienst mit Microsoft Entra ID oder verwalteten Identitäten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Cloudsicherheit.

Erstellen einer Geräteidentität und einer Modulidentität in IoT Hub

In diesem Abschnitt erstellen Sie eine Python-Dienst-App, mit der eine Geräte- und eine Modulidentität in der Identitätsregistrierung Ihrer IoT Hub-Identität erstellt werden. Ein Gerät oder Modul kann nur eine Verbindung mit IoT Hub herstellen, wenn in der Identitätsregistrierung ein Eintrag für dieses Gerät vorhanden ist. Weitere Informationen finden Sie unter Grundlegendes zur Identitätsregistrierung in Ihrer IoT Hub-Instanz. Wenn Sie diese Konsolen-App ausführen, generiert sie eine eindeutige ID und einen eindeutigen Schlüssel für das Gerät und das Modul. Bei der ID und dem Schlüssel muss die Groß-/Kleinschreibung beachtet werden. Ihr Gerät und Ihr Modul verwenden diese Werte, um sich beim Senden von D2C-Nachrichten an IoT Hub zu identifizieren.

Wichtig

Dieser Artikel enthält Schritte zum Verbinden eines Geräts mithilfe einer Shared Access Signature, was auch als symmetrische Schlüsselauthentifizierung bezeichnet wird. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung eines Geräts mit X.509-Zertifikaten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Verbindungssicherheit.

Führen Sie an der Eingabeaufforderung den folgenden Befehl aus, um das Paket azure-iot-hub zu installieren:
```
pip install azure-iot-hub
```
Führen Sie an der Eingabeaufforderung den folgenden Befehl aus, um das Paket msrest zu installieren. Sie benötigen dieses Paket, um HTTPOperationError-Ausnahmen abzufangen.
```
pip install msrest
```
Erstellen Sie mit einem Text-Editor in Ihrem Arbeitsverzeichnis eine Datei mit dem Namen CreateModule.py.

Fügen Sie der Python-Datei den folgenden Code hinzu. Ersetzen Sie YourIoTHubConnectionString durch die Verbindungszeichenfolge, die Sie unter Abrufen der IoT-Hub-Verbindungszeichenfolge kopiert haben.

import sys
from msrest.exceptions import HttpOperationError
from azure.iot.hub import IoTHubRegistryManager

CONNECTION_STRING = "YourIotHubConnectionString"
DEVICE_ID = "myFirstDevice"
MODULE_ID = "myFirstModule"

try:
    # RegistryManager
    iothub_registry_manager = IoTHubRegistryManager(CONNECTION_STRING)

    try:
        # CreateDevice - let IoT Hub assign keys
        primary_key = ""
        secondary_key = ""
        device_state = "enabled"
        new_device = iothub_registry_manager.create_device_with_sas(
            DEVICE_ID, primary_key, secondary_key, device_state
        )
    except HttpOperationError as ex:
        if ex.response.status_code == 409:
            # 409 indicates a conflict. This happens because the device already exists.
            new_device = iothub_registry_manager.get_device(DEVICE_ID)
        else:
            raise

    print("device <" + DEVICE_ID +
          "> has primary key = " + new_device.authentication.symmetric_key.primary_key)

    try:
        # CreateModule - let IoT Hub assign keys
        primary_key = ""
        secondary_key = ""
        managed_by = ""
        new_module = iothub_registry_manager.create_module_with_sas(
            DEVICE_ID, MODULE_ID, managed_by, primary_key, secondary_key
        )
    except HttpOperationError as ex:
        if ex.response.status_code == 409:
            # 409 indicates a conflict. This happens because the module already exists.
            new_module = iothub_registry_manager.get_module(DEVICE_ID, MODULE_ID)
        else:
            raise

    print("device/module <" + DEVICE_ID + "/" + MODULE_ID +
          "> has primary key = " + new_module.authentication.symmetric_key.primary_key)

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

Führen Sie an der Eingabeaufforderung den folgenden Befehl aus:
```
python CreateModule.py
```

Diese App erstellt eine Geräteidentität mit der ID myFirstDevice und ein Identitätsmodul mit der ID myFirstModule unter dem Gerät myFirstDevice. (Falls die Geräte- oder Modul-ID in der Identitätsregistrierung bereits vorhanden ist, werden mit dem Code lediglich die vorhandenen Geräte- bzw. Modulinformationen abgerufen.) Die App zeigt die ID und den Primärschlüssel für jede Identität an.

Hinweis

Die Identitätsregistrierung in IoT Hub speichert nur Geräte- und Modulidentitäten, um einen sicheren Zugriff auf IoT Hub zu ermöglichen. In der Identitätsregistrierung werden Geräte-IDs und -schlüssel für die Verwendung als Sicherheitsanmeldeinformationen gespeichert. Darüber hinaus wird in der Identitätsregistrierung ein Flag für den Aktivierungszustand des jeweiligen Geräts gespeichert, mit dem Sie den Zugriff für das betreffende Gerät deaktivieren können. Wenn Ihre Anwendung das Speichern weiterer gerätespezifischer Metadaten erfordert, sollte dafür ein anwendungsspezifischer Speicher verwendet werden. Es gibt keinen Flag „Aktiviert/deaktiviert“ für Modulidentitäten. Weitere Informationen finden Sie unter Grundlegendes zur Identitätsregistrierung in Ihrer IoT Hub-Instanz.

Aktualisieren des Modulzwillings mithilfe des Python-Dienst-SDK

In diesem Abschnitt erstellen Sie eine Python-Dienst-App, die die gewünschten Eigenschaften für den Modulzwilling aktualisiert.

Führen Sie an der Eingabeaufforderung den folgenden Befehl aus, um das Paket azure-iot-hub zu installieren. Sie können diesen Schritt überspringen, wenn Sie im vorherigen Abschnitt das Paket azure-iot-hub installiert haben.
```
pip install azure-iot-hub
```
Erstellen Sie mit einem Text-Editor in Ihrem Arbeitsverzeichnis eine Datei mit dem Namen UpdateModuleTwinDesiredProperties.py.

import sys
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties

CONNECTION_STRING = "YourIoTHubConnectionString"
DEVICE_ID = "myFirstDevice"
MODULE_ID = "myFirstModule"

try:
    # RegistryManager
    iothub_registry_manager = IoTHubRegistryManager(CONNECTION_STRING)

    module_twin = iothub_registry_manager.get_module_twin(DEVICE_ID, MODULE_ID)
    print ( "" )
    print ( "Module twin properties before update    :" )
    print ( "{0}".format(module_twin.properties) )

    # Update twin
    twin_patch = Twin()
    twin_patch.properties = TwinProperties(desired={"telemetryInterval": 122})
    updated_module_twin = iothub_registry_manager.update_module_twin(
        DEVICE_ID, MODULE_ID, twin_patch, module_twin.etag
    )
    print ( "" )
    print ( "Module twin properties after update     :" )
    print ( "{0}".format(updated_module_twin.properties) )

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

Abrufen von Updates auf Geräteseite

In diesem Abschnitt erstellen Sie eine Python-App, mit der die aktualisierten gewünschten Eigenschaften für den Modulzwilling auf Ihr Gerät abgerufen werden.

Rufen Sie die Modulverbindungszeichenfolge ab. Navigieren Sie im Azure-Portal zu Ihrem IoT-Hub, und wählen Sie im linken Bereich Geräte aus. Wählen Sie in der Liste der Geräte myFirstDevice aus, und öffnen Sie es. Wählen Sie unter Modulidentitäten den Namen myFirstModule aus. Wählen Sie das Symbol zum Kopieren für Verbindungszeichenfolge (Primärschlüssel) aus. Sie benötigen diese Verbindungszeichenfolge in einem der nächsten Schritte.
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 mit dem Namen ReceiveModuleTwinDesiredPropertiesPatch.py.

Fügen Sie der Python-Datei den folgenden Code hinzu. Ersetzen Sie YourModuleConnectionString durch die Modulverbindungszeichenfolge, die Sie in Schritt 1 kopiert haben.

import time
from azure.iot.device import IoTHubModuleClient

CONNECTION_STRING = "YourModuleConnectionString"


def twin_patch_handler(twin_patch):
    print("")
    print("Twin desired properties patch received:")
    print(twin_patch)


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

    print ("Waiting for commands, press Ctrl-C to exit")
    try:
        # Attach the handler to the client
        client.on_twin_desired_properties_patch_received = twin_patch_handler

        while True:
            time.sleep(1000)
    except KeyboardInterrupt:
        print("IoTHubModuleClient sample stopped")
    finally:
        # Graceful exit
        print("Shutting down IoT Hub Client")
        client.shutdown()

if __name__ == '__main__':
    main()

Ausführen der Apps

In diesem Abschnitt führen Sie die Geräte-App ReceiveModuleTwinDesiredPropertiesPatch und dann die Dienst-App UpdateModuleTwinDesiredProperties aus, um die gewünschten Eigenschaften des Moduls zu aktualisieren.

Öffnen Sie eine Eingabeaufforderung, und führen Sie die Geräte-App aus:
```
python ReceiveModuleTwinDesiredPropertiesPatch.py
```
Öffnen Sie eine andere Eingabeaufforderung, und führen Sie die Dienst-App aus:
```
python UpdateModuleTwinDesiredProperties.py
```
Beachten Sie, dass in der Ausgabe der Dienst-App die gewünschte TelemetryInterval-Eigenschaft im aktualisierten Modulzwilling angezeigt wird:

In der Ausgabe der Geräte-App wird im empfangenen Patch für gewünschte Eigenschaften die gleiche Eigenschaft angezeigt: