Erste Schritte mit Gerätezwillingen (Python)

Artikel
03/22/2023

Gerätezwillinge sind JSON-Dokumente, in denen Gerätestatusinformationen gespeichert werden, einschließlich Metadaten, Konfigurationen und Bedingungen. Von IoT Hub wird für jedes Gerät, das eine Verbindung herstellt, dauerhaft ein Gerätezwilling gespeichert.

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 Gerätezwillinge für Folgendes:

Speichern von Gerätemetadaten von Ihrem Lösungs-Back-End
Melden von aktuellen Zustandsinformationen wie verfügbare Funktionen und Bedingungen, z.B. die verwendete Verbindungsmethode, von Ihrer Geräte-App
Synchronisieren des Zustands von Workflows mit langer Ausführungsdauer, z.B. Firmware- und Konfigurationsupdates, zwischen einer Geräte-App und einer Back-End-App
Abfragen von Metadaten, Konfiguration oder Status des Geräts

Gerätezwillinge sind für die Synchronisierung und zum Abfragen von Gerätekonfigurationen und -bedingungen ausgelegt. Weitere Informationen zu Gerätezwillingen, einschließlich der Verwendung von Gerätezwillingen, finden Sie unter Verstehen und Verwenden von Gerätezwillingen in IoT Hub.

IoT-Hubs speichern Gerätezwillinge, die die folgenden Elemente enthalten:

Tags. Gerätemetadaten, auf die nur vom Lösungs-Back-End zugegriffen werden kann.
Gewünschte Eigenschaften JSON-Objekte, die vom Lösungs-Back-End geändert und von der Geräte-App überwacht werden können.
Gemeldete Eigenschaften JSON-Objekte, die von der Geräte-App geändert und vom Lösungs-Back-End gelesen werden können.

Tags und Eigenschaften können keine Arrays, aber geschachtelte Objekte enthalten.

Die folgende Abbildung zeigt die Organisation des Gerätezwillings:

Screenshot eines Konzeptdiagramms für Gerätezwillinge.

Außerdem können mit dem Lösungs-Back-End Gerätezwillinge basierend auf allen obigen Daten abgefragt werden. Weitere Informationen zu Gerätezwillingen finden Sie unter Grundlegendes zu Gerätezwillingen. Weitere Informationen zu Abfragen finden Sie unter IoT Hub-Abfragesprache.

In diesem Artikel lernen Sie Folgendes:

Verwenden Sie eine simulierte Geräte-App, um ihren Konnektivitätskanal als gemeldete Eigenschaft auf dem Gerätezwilling zu melden.
Fragen Sie Geräte von Ihrer Back-End-App ab, indem Sie Filter für die zuvor erstellten Tags und Eigenschaften verwenden.

In diesem Artikel erstellen Sie zwei Python-Konsolen-Apps:

AddTagsAndQuery.py, eine Python-Back-End-App, die Tags hinzufügt und Gerätezwillinge abfragt.
simulated-device ist eine Java-Geräte-App, die eine Verbindung mit Ihrem IoT Hub herstellt und seine Konnektivitätsbedingung mit einer gemeldeten Eigenschaft meldet.

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

Abrufen der IoT-Hub-Verbindungszeichenfolge

In diesem Artikel erstellen Sie einen Back-End-Dienst, der einem Gerätezwilling die gewünschten Eigenschaften hinzufügt und anschließend die Identitätsregistrierung abfragt, um alle Geräte mit gemeldeten Eigenschaften zu ermitteln, die entsprechend aktualisiert wurden. Ihr Dienst benötigt die Berechtigung Dienstverbindung, um die gewünschten Eigenschaften eines Gerätezwillings ändern zu können, sowie die Berechtigung Lesevorgänge in Registrierung, um die Identitätsregistrierung abfragen zu können. Da keine SAS-Standardrichtlinie mit nur diesen beiden Berechtigungen zur Verfügung steht, müssen Sie eine erstellen.

Gehen Sie wie folgt vor, um eine SAS-Richtlinie zu erstellen, die die Berechtigungen Dienstverbindung und Lesevorgänge in Registrierung gewährt, und eine Verbindungszeichenfolge für diese Richtlinie abzurufen:

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ü oberhalb der Richtlinienliste die Option Richtlinie für den gemeinsamen Zugriff hinzufügen aus.
Geben Sie unter Richtlinie für den gemeinsamen Zugriff hinzufügen einen aussagekräftigen Namen für Ihre Richtlinie ein, wie z.B. serviceAndRegistryRead. Wählen Sie unter Berechtigungen die Berechtigungen Registry Read und Service Connect aus und klicken Sie anschließend auf Hinzufügen.
Wählen Sie Ihre neue Richtlinie aus der Liste der Richtlinien aus.
Wählen Sie 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.

Erstellen einer Dienst-App, die gewünschte Eigenschaften aktualisiert und Zwillinge abfragt

In diesem Abschnitt erstellen Sie eine Python-Konsolen-App, mit der dem Gerätezwilling, der Ihrer {Geräte-ID} zugeordnet ist, Standortmetadaten hinzugefügt werden. Die App fragt IoT Hub nach Geräten ab, die sich in den USA befinden, und fragt dann Geräte ab, die eine Mobilfunknetzverbindung melden.

Öffnen Sie in Ihrem Arbeitsverzeichnis eine Eingabeaufforderung, und installieren Sie das Azure IoT Hub Service SDK für Python.
```
pip install azure-iot-hub
```
Erstellen Sie in einem Text-Editor eine neue Datei namens AddTagsAndQuery.py.

Fügen Sie den folgenden Code hinzu, um die erforderlichen Module aus dem Dienst-SDK zu importieren:

import sys
from time import sleep
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties, QuerySpecification, QueryResult

Fügen Sie den folgenden Code hinzu. Ersetzen Sie [IoTHub Connection String] durch die IoT-Hub-Verbindungszeichenfolge, die Sie unter Abrufen der IoT-Hub-Verbindungszeichenfolge kopiert haben. Ersetzen Sie [Device Id] durch die Geräte-ID (den Namen) aus Ihrem registrierten Gerät im IoT-Hub.
```
IOTHUB_CONNECTION_STRING = "[IoTHub Connection String]"
DEVICE_ID = "[Device Id]"
```

Fügen Sie den folgenden Code der Datei AddTagsAndQuery.py hinzu:

def iothub_service_sample_run():
    try:
        iothub_registry_manager = IoTHubRegistryManager(IOTHUB_CONNECTION_STRING)

        new_tags = {
                'location' : {
                    'region' : 'US',
                    'plant' : 'Redmond43'
                }
            }

        twin = iothub_registry_manager.get_twin(DEVICE_ID)
        twin_patch = Twin(tags=new_tags, properties= TwinProperties(desired={'power_level' : 1}))
        twin = iothub_registry_manager.update_twin(DEVICE_ID, twin_patch, twin.etag)

        # Add a delay to account for any latency before executing the query
        sleep(1)

        query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'")
        query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
        print("Devices in Redmond43 plant: {}".format(', '.join([twin.device_id for twin in query_result.items])))

        print()

        query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity = 'cellular'")
        query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
        print("Devices in Redmond43 plant using cellular network: {}".format(', '.join([twin.device_id for twin in query_result.items])))

    except Exception as ex:
        print("Unexpected error {0}".format(ex))
        return
    except KeyboardInterrupt:
        print("IoT Hub Device Twin service sample stopped")

Das IoTHubRegistryManager-Objekt macht alle Methoden verfügbar, die für die Interaktion mit Gerätezwillingen des Diensts erforderlich sind. Der Code initialisiert zuerst das IoTHubRegistryManager-Objekt, aktualisiert dann den Gerätezwilling für DEVICE_ID und führt schließlich zwei Abfragen aus. Mit der ersten werden nur die Gerätezwillinge von Geräten in der Anlage Redmond43 ausgewählt. Mit der zweiten wird die Abfrage so angepasst, dass nur die Geräte ausgewählt werden, die über ein Mobilfunknetz verbunden sind.

Fügen Sie am Ende der Datei AddTagsAndQuery.py den folgenden Code ein, um die Funktion iothub_service_sample_run zu implementieren:

if __name__ == '__main__':
    print("Starting the Python IoT Hub Device Twin service sample...")
    print()

    iothub_service_sample_run()

Führen Sie die Anwendung mit folgendem Befehl aus:
```
python AddTagsAndQuery.py
```
In den Ergebnissen für die Abfrage, mit der alle Geräte in der Anlage Redmond43 abgefragt werden, sollte ein Gerät angezeigt werden und keines für die Abfrage, mit der die Ergebnisse auf die über ein Mobilfunknetz verbundenen Geräte beschränkt werden. Im nächsten Abschnitt erstellen Sie eine Geräte-App, die ein Mobilfunknetzwerk verwendet. Dann führen Sie diese Abfrage erneut aus, um zu sehen, wie sie sich ändert.

Erstellen einer Geräte-App, die gemeldete Eigenschaften aktualisiert

In diesem Abschnitt erstellen Sie eine Python-Konsolen-App, die sich als Ihre {Geräte-ID} mit Ihrem Hub verbindet und dann die gemeldeten Eigenschaften ihres Gerätezwillings aktualisiert, um zu bestätigen, dass sie über ein Mobilfunknetz verbunden ist.

Installieren Sie über eine Eingabeaufforderung in Ihrem Arbeitsverzeichnis das Azure IoT Hub Device SDK für Python:
```
pip install azure-iot-device
```
Erstellen Sie in einem Text-Editor eine neue Datei namens ReportConnectivity.py.
Fügen Sie den folgenden Code hinzu, um die erforderlichen Module aus dem Geräte-SDK zu importieren:
```
import time
from azure.iot.device import IoTHubModuleClient
```
Fügen Sie den folgenden Code hinzu. Ersetzen Sie den Platzhalterwert [IoTHub Device Connection String] durch die Geräteverbindungszeichenfolge, die beim Registrieren eines neuen Geräts im IoT Hub angezeigt wurde:
```
CONNECTION_STRING = "[IoTHub Device Connection String]"
```

Fügen Sie der Datei ReportConnectivity.py folgenden Code hinzu, um einen Client zu instanziieren und die Gerätezwillingsfunktionalität zu implementieren:

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

    # Define behavior for receiving twin desired property patches
    def twin_patch_handler(twin_patch):
        print("Twin patch received:")
        print(twin_patch)

    try:
        # Set handlers on the client
        client.on_twin_desired_properties_patch_received = twin_patch_handler
    except:
        # Clean up in the event of failure
        client.shutdown()

    return client

Fügen Sie den folgenden Code am Ende der Datei ReportConnectivity.py hinzu, um die Anwendung auszuführen:

def main():
    print ( "Starting the Python IoT Hub Device Twin device sample..." )
    client = create_client()
    print ( "IoTHubModuleClient waiting for commands, press Ctrl-C to exit" )

    try:
        # Update reported properties with cellular information
        print ( "Sending data as reported property..." )
        reported_patch = {"connectivity": "cellular"}
        client.patch_twin_reported_properties(reported_patch)
        print ( "Reported properties updated" )

        # Wait for program exit
        while True:
            time.sleep(1000000)
    except KeyboardInterrupt:
        print ("IoT Hub Device Twin device sample stopped")
    finally:
        # Graceful exit
        print("Shutting down IoT Hub Client")
        client.shutdown()

if __name__ == '__main__':
    main()

Führen Sie die Geräte-App aus:
```
python ReportConnectivity.py
```
Es sollte die Bestätigung angezeigt werden, dass die gemeldeten Eigenschaften der Gerätezwillinge aktualisiert wurden.
Da das Gerät nun die Verbindungsinformationen gemeldet hat, sollten diese in beiden Abfragen angezeigt werden. Gehen Sie zurück, und führen Sie die Abfragen erneut aus:
```
python AddTagsAndQuery.py
```
Nun sollte Ihre {Geräte-ID} in beiden Abfrageergebnisse angezeigt werden.

In Ihrer Geräte-App wird die Bestätigung angezeigt, dass der von der Dienst-App gesendete Patch für die gewünschten Zwillingseigenschaften empfangen wurde.

In diesem Artikel führen Sie folgende Schritte aus:

Gerätemetadaten als Tags aus einer Back-End-App hinzugefügt
Gemeldete Gerätekonnektivitätsinformationen im Gerätezwilling
Die Gerätezwillingsinformationen mithilfe der IoT Hub-Abfragesprache abgefragt

Nächste Schritte

Eine entsprechende Anleitung

Senden von Telemetriedaten von Geräten finden Sie im Artikel Schnellstart: Senden von Telemetriedaten von einem IoT Plug & Play-Gerät an Azure IoT Hub.
Konfigurieren Sie Geräte mit den gewünschten Eigenschaften des Gerätezwillings, siehe Tutorial: Konfigurieren Sie Ihre Geräte über einen Back-End-Diens.
Steuern von Geräten interaktiv, z. B. das Aktivieren eines Lüfters von einer benutzergesteuerten App, finden Sie unter Schnellstart: Steuern eines Geräts, das mit einem IoT-Hub verbunden ist.