Erste Schritte mit Gerätezwillingen (Node.js)

Artikel
03/20/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 Node.js-Konsolen-Apps:

AddTagsAndQuery.js: eine Back-End-App, die Tags hinzufügt und Gerätezwillinge abfragt.
TwinSimulatedDevice.js: eine simulierte Geräte-App, die eine Verbindung mit Ihrem IoT-Hub herstellt und seine Konnektivitätsbedingung meldet.

Hinweis

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

Voraussetzungen

Damit Sie die Anweisungen in diesem Artikel ausführen können, benötigen Sie Folgendes:

Einen IoT Hub. Erstellen Sie einen mit der CLI oder dem Azure-Portal.
Ein registriertes Gerät. Registrieren Sie eins im Azure-Portal.
Node.js, Version 10.0.x oder höher.
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 Geräte-App, die gemeldete Eigenschaften aktualisiert

In diesem Abschnitt erstellen Sie eine Node.js-Konsolen-App, die sich als Ihre myDeviceId mit Ihrem Hub verbindet und dann die gemeldeten Eigenschaften von dessen Gerätezwilling aktualisiert, um zu bestätigen, dass sie über ein Mobilfunknetz verbunden ist.

Erstellen Sie einen neuen leeren Ordner mit dem Namen reportconnectivity. Erstellen Sie im Ordner reportconnectivity die neue Datei „package.json“, indem Sie an der Eingabeaufforderung den unten angegebenen Befehl ausführen. Der Parameter --yes akzeptiert alle Standardwerte.
```
npm init --yes
```
Führen Sie an der Eingabeaufforderung im Ordner reportconnectivity den folgenden Befehl aus, um das Paket azure-iot-device und das Paket azure-iot-device-mqtt zu installieren:
```
npm install azure-iot-device azure-iot-device-mqtt --save
```
Erstellen Sie mithilfe eines Text-Editors die neue Datei ReportConnectivity.js im Ordner reportconnectivity.

Fügen Sie der Datei ReportConnectivity.js den folgenden Code hinzu. Ersetzen Sie {device connection string} durch die Geräteverbindungszeichenfolge, die Ihnen beim Registrieren eines Geräts im IoT-Hub angezeigt wurde:

    'use strict';
    var Client = require('azure-iot-device').Client;
    var Protocol = require('azure-iot-device-mqtt').Mqtt;

    var connectionString = '{device connection string}';
    var client = Client.fromConnectionString(connectionString, Protocol);

    client.open(function(err) {
    if (err) {
        console.error('could not open IotHub client');
    }  else {
        console.log('client opened');

        client.getTwin(function(err, twin) {
        if (err) {
            console.error('could not get twin');
        } else {
            var patch = {
                connectivity: {
                    type: 'cellular'
                }
            };

            twin.properties.reported.update(patch, function(err) {
                if (err) {
                    console.error('could not update twin');
                } else {
                    console.log('twin state reported');
                    process.exit();
                }
            });
        }
        });
    }
    });

Das Client-Objekt macht alle Methoden verfügbar, die für die Interaktion mit Gerätezwillingen des Geräts erforderlich sind. Mit diesem Code wird nach dem Initialisieren des Client-Objekts der Gerätezwilling für myDeviceId abgerufen und die zugehörige gemeldete Eigenschaft mit den Verbindungsinformationen aktualisiert.

Führen Sie die Geräte-App aus.
```
    node ReportConnectivity.js
```
Die Meldung twin state reported sollte angezeigt werden.
Da das Gerät nun die Verbindungsinformationen gemeldet hat, sollten diese in beiden Abfragen angezeigt werden. Wechseln Sie zurück in den Ordner addtagsandqueryapp, und führen Sie die Abfragen erneut aus:
```
    node AddTagsAndQuery.js
```
Nun sollte myDeviceId in beiden Abfrageergebnisse angezeigt werden.

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

In diesem Abschnitt erstellen Sie eine Node.js-Konsolen-App, mit der dem Gerätezwilling, der myDeviceId 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.

Erstellen Sie einen neuen leeren Ordner mit dem Namen addtagsandqueryapp. Erstellen Sie im Ordner addtagsandqueryapp die neue Datei „package.json“, indem Sie an der Eingabeaufforderung den unten angegebenen Befehl ausführen. Der Parameter --yes akzeptiert alle Standardwerte.
```
npm init --yes
```
Führen Sie an der Eingabeaufforderung im Ordner addtagsandqueryapp den folgenden Befehl aus, um das Paket azure-iothub zu installieren:
```
npm install azure-iothub --save
```
Erstellen Sie mithilfe eines Text-Editors die neue Datei AddTagsAndQuery.js im Ordner addtagsandqueryapp.

Fügen Sie der Datei AddTagsAndQuery.js den folgenden Code hinzu. Ersetzen Sie {iot hub connection string} durch die IoT-Hub-Verbindungszeichenfolge, die Sie unter Abrufen der IoT-Hub-Verbindungszeichenfolge kopiert haben.

     'use strict';
     var iothub = require('azure-iothub');
     var connectionString = '{iot hub connection string}';
     var registry = iothub.Registry.fromConnectionString(connectionString);

     registry.getTwin('myDeviceId', function(err, twin){
         if (err) {
             console.error(err.constructor.name + ': ' + err.message);
         } else {
             var patch = {
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                   }
                 }
             };

             twin.update(patch, function(err) {
               if (err) {
                 console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
               } else {
                 console.log(twin.deviceId + ' twin updated successfully');
                 queryTwins();
               }
             });
         }
     });

Das Registry-Objekt macht alle Methoden verfügbar, die für die Interaktion mit Gerätezwillingen des Diensts erforderlich sind. Mit dem vorherigen Code wird zunächst das Registry-Objekt initialisiert und dann der Gerätezwilling für myDeviceId abgerufen, und schließlich werden die zugehörigen Tags mit den gewünschten Standortinformationen aktualisiert.

Nach dem Aktualisieren der Tags wird die Funktion queryTwins aufgerufen.

Fügen Sie am Ende von AddTagsAndQuery.js den folgenden Code ein, um die Funktion queryTwins zu implementieren:

     var queryTwins = function() {
         var query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
         query.nextAsTwin(function(err, results) {
             if (err) {
                 console.error('Failed to fetch the results: ' + err.message);
             } else {
                 console.log("Devices in Redmond43: " + results.map(function(twin) {return twin.deviceId}).join(','));
             }
         });

         query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
         query.nextAsTwin(function(err, results) {
             if (err) {
                 console.error('Failed to fetch the results: ' + err.message);
             } else {
                 console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin) {return twin.deviceId}).join(','));
             }
         });
     };

Mithilfe dieses Codes werden zwei Abfragen ausgeführt: 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.

Wenn der Code das query-Objekt erstellt, wird die maximale Anzahl der zurückgegebenen Dokumente im zweiten Parameter angegeben. Das query-Objekt enthält die boolesche Eigenschaft hasMoreResults, mit der Sie die nextAsTwin-Methoden mehrmals aufrufen können, um alle Ergebnisse abzurufen. Die next-Methode ist für Ergebnisse verfügbar, die keine Gerätezwillinge sind, z.B. die Ergebnisse von Aggregationsabfragen.

Führen Sie die Anwendung mit folgendem Befehl aus:
```
    node AddTagsAndQuery.js
```
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.

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
Sie haben zudem erfahren, wie die Gerätezwillingsinformationen mithilfe der SQL-ähnlichen IoT Hub-Abfragesprache abgefragt werden können

Nächste Schritte

Eine entsprechende Anleitung

Zum Senden von Telemetriedaten von Geräten finden Sie im Schnellstart: Senden von Telemetriedaten von einem IoT Plug & Play-Gerät an Azure IoT Hub.
Zum Konfigurieren von Geräten mithilfe der gewünschten Eigenschaften des Gerätezwillings finden Sie im Tutorial: Konfigurieren Ihrer Geräte aus einem Back-End-Dienst.
Zum interaktiven Steuern von Geräten, z. B. zum Aktivieren eines Lüfters aus einer benutzergesteuerten App, finden Sie im Schnellstart: Steuern eines Geräts, das mit einem IoT-Hub verbunden ist.