Erste Schritte mit der Geräteverwaltung (Node.js)

Artikel
03/21/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.js: 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 .NET-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.

Voraussetzungen

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. In Vorbereiten Ihrer Entwicklungsumgebung wird beschrieben, wie Node.js für diesen Artikel entweder auf Windows oder Linux installiert wird.
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).

Erstellen einer Geräte-App mit einer direkten Methode

In diesem Abschnitt führen Sie folgende Schritte aus:

Erstellen einer Node.js-Konsolen-App, die auf eine von der Cloud aufgerufene direkte Methode antwortet
Auslösen des Neustarts eines simulierten Geräts
Verwenden der gemeldeten Eigenschaften, um Gerätezwillingsabfragen zu ermöglichen, die Geräte und den Zeitpunkt ihres letzten Neustarts ermitteln

Erstellen Sie einen leeren Ordner mit dem Namen managed-device. Erstellen Sie im Ordner managed-device eine „package.json“-Datei, indem Sie an der Eingabeaufforderung den folgenden Befehl ausführen. Übernehmen Sie alle Standardeinstellungen:
```
npm init
```
Führen Sie an der Eingabeaufforderung im Ordner managed-device den folgenden Befehl aus, um das Geräte-SDK-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 im Ordner managed-device die Datei dmpatterns_getstarted_device.js.

Fügen Sie am Anfang der Datei dmpatterns_getstarted_device.js die folgenden require-Anweisungen ein:

'use strict';

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

Fügen Sie die Variable connectionString hinzu, und verwenden Sie sie zum Erstellen einer Client-Instanz. Ersetzen Sie den Platzhalterwert {yourdeviceconnectionstring} durch die Geräteverbindungszeichenfolge, die beim Registrieren eines neuen Geräts in IoT Hub angezeigt wurde:
```
var connectionString = '{yourdeviceconnectionstring}';
var client = Client.fromConnectionString(connectionString, Protocol);
```

Fügen Sie die folgende Funktion hinzu, um die direkte Methode auf dem Gerät zu implementieren

var onReboot = function(request, response) {

    // Respond the cloud app for the direct method
    response.send(200, 'Reboot started', function(err) {
        if (err) {
            console.error('An error occurred when sending a method response:\n' + err.toString());
        } else {
            console.log('Response to method \'' + request.methodName + '\' sent successfully.');
        }
    });

    // Report the reboot before the physical restart
    var date = new Date();
    var patch = {
        iothubDM : {
            reboot : {
                lastReboot : date.toISOString(),
            }
        }
    };

    // Get device Twin
    client.getTwin(function(err, twin) {
        if (err) {
            console.error('could not get twin');
        } else {
            console.log('twin acquired');
            twin.properties.reported.update(patch, function(err) {
                if (err) throw err;
                console.log('Device reboot twin state reported')
            });  
        }
    });

    // Add your device's reboot API for physical restart.
    console.log('Rebooting!');
};

Öffnen Sie die Verbindung mit dem IoT Hub, und starten Sie den Listener der direkten Methode:

client.open(function(err) {
    if (err) {
        console.error('Could not open IotHub client');
    }  else {
        console.log('Client opened.  Waiting for reboot method.');
        client.onDeviceMethod('reboot', onReboot);
    }
});

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

Hinweis

Der Einfachheit halber wird in diesem Artikel 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 Node.js-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 einen leeren Ordner mit dem Namen trigger-reboot-on-device. Erstellen Sie im Ordner trigger-reboot-on-device die Datei „package.json“, indem Sie an der Eingabeaufforderung den folgenden Befehl ausführen. Übernehmen Sie alle Standardeinstellungen:
```
npm init
```
Führen Sie an der Eingabeaufforderung im Ordner trigger-reboot-on-device den folgenden Befehl aus, um das Geräte-SDK-Paket azure-iothub und das Paket azure-iot-device-mqtt zu installieren:
```
npm install azure-iothub --save
```
Erstellen Sie mithilfe eines Text-Editors im Ordner trigger-reboot-on-device die Datei dmpatterns_getstarted_service.js.

Fügen Sie am Anfang der Datei dmpatterns_getstarted_service.js die folgenden require-Anweisungen ein:

'use strict';

var Registry = require('azure-iothub').Registry;
var Client = require('azure-iothub').Client;

Fügen Sie die folgenden Variablendeklarationen hinzu, und ersetzen Sie den Platzhalterwert {iothubconnectionstring} durch die IoT-Hub-Verbindungszeichenfolge, die Sie zuvor unter Abrufen der IoT-Hub-Verbindungszeichenfolge kopiert haben:
```
var connectionString = '{iothubconnectionstring}';
var registry = Registry.fromConnectionString(connectionString);
var client = Client.fromConnectionString(connectionString);
var deviceToReboot = 'myDeviceId';
```

Fügen Sie die folgende Funktion hinzu, um durch Aufrufen der Gerätemethode das Zielgerät neu zu starten:

var startRebootDevice = function(twin) {

    var methodName = "reboot";

    var methodParams = {
        methodName: methodName,
        payload: null,
        timeoutInSeconds: 30
    };

    client.invokeDeviceMethod(deviceToReboot, methodParams, function(err, result) {
        if (err) {
            console.error("Direct method error: "+err.message);
        } else {
            console.log("Successfully invoked the device to reboot.");  
        }
    });
};

Fügen Sie die folgende Funktion hinzu, um das Gerät abzufragen und den letzten Neustartzeitpunkt zu erhalten:

var queryTwinLastReboot = function() {

    registry.getTwin(deviceToReboot, function(err, twin){

        if (twin.properties.reported.iothubDM != null)
        {
            if (err) {
                console.error('Could not query twins: ' + err.constructor.name + ': ' + err.message);
            } else {
                var lastRebootTime = twin.properties.reported.iothubDM.reboot.lastReboot;
                console.log('Last reboot time: ' + JSON.stringify(lastRebootTime, null, 2));
            }
        } else 
            console.log('Waiting for device to report last reboot time.');
    });
};

Fügen Sie den folgenden Code hinzu, um die Funktionen aufrufen, die die direkte Methode zum Neustart auslösen und den letzten Neustartzeitpunkt abfragen:
```
startRebootDevice();
setInterval(queryTwinLastReboot, 2000);
```
Speichern und schließen Sie die Datei dmpatterns_getstarted_service.js.

Ausführen der Apps

Jetzt können Sie die Apps ausführen.

Führen Sie an der Eingabeaufforderung im Ordner managed-device den folgenden Befehl aus, um mit dem Lauschen auf die direkte Methode zum Neustarten zu beginnen.
```
node dmpatterns_getstarted_device.js
```
Führen Sie an der Eingabeaufforderung im Ordner trigger-reboot-on-device den folgenden Befehl aus, um den Remote-Neustart und die Abfrage an den Gerätezwilling zum Ermitteln des letzten Neustartzeitpunkts auszulösen.
```
node dmpatterns_getstarted_service.js
```
Die Reaktion des Geräts auf die direkte Methode zum Neustart und der Neustartstatus werden in der-Konsole angezeigt.

Das folgende Beispiel zeigt die Reaktion des Geräts auf die direkte Methode zum Neustart, die vom Dienst gesendet wird:

Das folgende Beispiel zeigt den Dienst, der den Neustart auslöst und den Gerätezwilling abruft, um den letzten Neustartzeitpunkt zu ermitteln:

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.