Planen und Übertragen von Aufträgen (Node.js)

Artikel
10/01/2024

Verwenden Sie Azure IoT Hub zum Planen und Nachverfolgen von Aufträgen, die Millionen von Geräte aktualisieren. Verwenden Sie Aufträge zum:

Aktualisieren gewünschter Eigenschaften
Aktualisieren von Tags
Aufrufen direkter Methoden

Vom Konzept her umschließt ein Auftrag eine dieser Aktionen und verfolgt den Ausführungsfortschritt für eine Gruppe von Geräten nach, die anhand einer Gerätezwillingsabfrage definiert wird. Mit einem Auftrag kann eine Back-End-App beispielsweise eine Neustartmethode auf 10.000 Geräten aufrufen – angegeben durch eine Gerätezwillingsabfrage und geplant für einen späteren Zeitpunkt. Diese Anwendung kann dann den Fortschritt nachverfolgen, da jedes dieser Geräte die Neustartmethode empfängt und ausführt.

Weitere Informationen zu diesen Funktionen finden Sie in den folgenden Artikeln:

Gerätezwilling und Eigenschaften: Erste Schritte mit Gerätezwillingen (Vorschau) und Verstehen und Verwenden von Gerätezwillingen in IoT Hub
Direkte Methoden:IoT Hub-Entwicklerleitfaden – direkte Methoden

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.

In diesem Artikel wird gezeigt, wie Sie zwei Node.js-Apps erstellen:

Eine simulierte Node.js-Geräte-App, simDevice.js, die eine direkte Methode namens lockDoor implementiert, die von der Back-End-App aufgerufen werden kann.
Eine Node.js-Konsolen-App, scheduleJobService.js, die zwei Aufträge erstellt. Ein Auftrag ruft die direkte Methode lockDoor auf, und ein anderer Auftrag sendet die gewünschten Eigenschaftenupdates an mehrere Geräte.

Hinweis

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

Voraussetzungen

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.
Ein in Ihrem IoT-Hub registriertes Gerät. Wenn Sie nicht über ein Gerät in Ihrem IoT-Hub verfügen, führen Sie die Schritte unter Registrieren eines Geräts aus.
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 simulierten Geräte-App

In diesem Abschnitt erstellen Sie eine Node.js-Konsolen-App, die auf eine von der Cloud aufgerufene direkte Methode antwortet. Dadurch wird eine simulierte lockDoor-Methode ausgelöst.

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.

Erstellen Sie einen leeren Ordner mit dem Namen simDevice. Erstellen Sie im Ordner simDevice die Datei „package.json“, indem Sie an der Eingabeaufforderung den unten angegebenen Befehl ausführen. Übernehmen Sie alle Standardeinstellungen:
```
npm init
```
Führen Sie an der Eingabeaufforderung im Ordner simDevice 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 mit einem Text-Editor im Ordner simDevice die neue Datei simDevice.js.

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

'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 zuvor kopierte Verbindungszeichenfolge.
```
var connectionString = '{yourDeviceConnectionString}';
var client = Client.fromConnectionString(connectionString, Protocol);
```

Fügen Sie die folgende Funktion zur Behandlung der lockDoor-Methode hinzu.

var onLockDoor = function(request, response) {

    // Respond the cloud app for the direct method
    response.send(200, 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.');
        }
    });

    console.log('Locking Door!');
};

Fügen Sie den folgenden Code hinzu, um den Handler für die lockDoor-Methode zu registrieren.

client.open(function(err) {
     if (err) {
         console.error('Could not connect to IotHub client.');
     }  else {
         console.log('Client connected to IoT Hub. Register handler for lockDoor direct method.');
         client.onDeviceMethod('lockDoor', onLockDoor);
     }
});

Speichern und schließen Sie die Datei simDevice.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 einen Auftrag zum Aufrufen einer direkten Methode auf einem Gerät sowie einen Auftrag zum Aktualisieren des Gerätezwillings plant und den Fortschritt der beiden Aufträge überwacht. Für diese Vorgänge benötigt Ihr Dienst die Berechtigungen Lesevorgänge in Registrierung und Schreibvorgänge in Registrierung. Standardmäßig wird jeder IoT-Hub mit einer SAS-Richtlinie namens registryReadWrite erstellt, die diese Berechtigungen erteilt.

Führen Sie zum Abrufen der IoT-Hub-Verbindungszeichenfolge für die Richtlinie registryReadWrite 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 in der Liste der Richtlinien die Richtlinie registryRead Write 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.

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.

Planen von Aufträgen zum Aufrufen einer direkten Methode und Aktualisieren der Eigenschaften eines Gerätezwillings

In diesem Abschnitt erstellen Sie eine Node.js-Konsolen-App, mit der eine lockDoor-Remotefunktion auf einem Gerät mit einer direkten Methode initiiert wird, und aktualisieren die Eigenschaften des Gerätezwillings.

Erstellen Sie einen neuen leeren Ordner mit dem Namen scheduleJobService. Erstellen Sie im Ordner scheduleJobService die Datei „package.json“, indem Sie an der Eingabeaufforderung den unten angegebenen Befehl ausführen. Übernehmen Sie alle Standardeinstellungen:
```
npm init
```
Führen Sie an der Eingabeaufforderung im Ordner scheduleJobService 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 uuid --save
```
Erstellen Sie mit einem Text-Editor die neue Datei scheduleJobService.js im Ordner scheduleJobService.
Fügen Sie am Anfang der Datei scheduleJobService.js die folgenden ‚require‘-Anweisungen hinzu:
```
'use strict';

var uuid = require('uuid');
var JobClient = require('azure-iothub').JobClient;
```
Fügen Sie die folgenden Variablendeklarationen hinzu. Ersetzen Sie den Platzhalterwert {iothubconnectionstring} durch den Wert, den Sie in IoT Hub-Verbindungszeichenfolge abrufen zuvor kopiert haben. Wenn Sie ein anderes Gerät als myDeviceId registriert haben, müssen Sie es in der Abfragebedingung unbedingt ändern.
```
var connectionString = '{iothubconnectionstring}';
var queryCondition = "deviceId IN ['myDeviceId']";
var startTime = new Date();
var maxExecutionTimeInSeconds =  300;
var jobClient = JobClient.fromConnectionString(connectionString);
```

Fügen Sie die folgende Funktion hinzu, die zum Überwachen der Auftragsausführung verwendet werden soll:

function monitorJob (jobId, callback) {
    var jobMonitorInterval = setInterval(function() {
        jobClient.getJob(jobId, function(err, result) {
        if (err) {
            console.error('Could not get job status: ' + err.message);
        } else {
            console.log('Job: ' + jobId + ' - status: ' + result.status);
            if (result.status === 'completed' || result.status === 'failed' || result.status === 'cancelled') {
            clearInterval(jobMonitorInterval);
            callback(null, result);
            }
        }
        });
    }, 5000);
}

Fügen Sie den folgenden Code zum Planen des Auftrags hinzu, mit dem die Gerätemethode aufgerufen wird:

var methodParams = {
    methodName: 'lockDoor',
    payload: null,
    responseTimeoutInSeconds: 15 // Timeout after 15 seconds if device is unable to process method
};

var methodJobId = uuid.v4();
console.log('scheduling Device Method job with id: ' + methodJobId);
jobClient.scheduleDeviceMethod(methodJobId,
                            queryCondition,
                            methodParams,
                            startTime,
                            maxExecutionTimeInSeconds,
                            function(err) {
    if (err) {
        console.error('Could not schedule device method job: ' + err.message);
    } else {
        monitorJob(methodJobId, function(err, result) {
            if (err) {
                console.error('Could not monitor device method job: ' + err.message);
            } else {
                console.log(JSON.stringify(result, null, 2));
            }
        });
    }
});

Fügen Sie den folgenden Code zum Planen des Auftrags hinzu, mit dem der Gerätezwilling aktualisiert wird:

var twinPatch = {
   etag: '*',
   properties: {
       desired: {
           building: '43',
           floor: 3
       }
   }
};

var twinJobId = uuid.v4();

console.log('scheduling Twin Update job with id: ' + twinJobId);
jobClient.scheduleTwinUpdate(twinJobId,
                            queryCondition,
                            twinPatch,
                            startTime,
                            maxExecutionTimeInSeconds,
                            function(err) {
    if (err) {
        console.error('Could not schedule twin update job: ' + err.message);
    } else {
        monitorJob(twinJobId, function(err, result) {
            if (err) {
                console.error('Could not monitor twin update job: ' + err.message);
            } else {
                console.log(JSON.stringify(result, null, 2));
            }
        });
    }
});

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

Ausführen der Anwendungen

Sie können nun die Anwendungen ausführen.

Führen Sie an der Eingabeaufforderung im Ordner simDevice den folgenden Befehl aus, um mit dem Lauschen auf die direkte Methode zum Neustarten zu beginnen.
```
node simDevice.js
```
Führen Sie an der Eingabeaufforderung im Ordner scheduleJobService den folgenden Befehl aus, um die Aufträge zum Absperren der Tür und zum Aktualisieren des Zwillings auszulösen.
```
node scheduleJobService.js
```
Die Reaktion des Geräts auf die direkte Methode und den Auftragsstatus wird in der-Konsole angezeigt.

Das folgende Beispiel zeigt die Reaktion des Geräts auf die direkte Methode:

Das folgende Beispiel zeigt die Dienstplanungsaufträge für die direkte Methode und die Aktualisierung des Gerätezwillings sowie die Aufträge, die bis zum Abschluss ausgeführt werden:

Nächste Schritte

In diesem Artikel haben Sie Aufträge geplant, um eine direkte Methode auszuführen und die Eigenschaften des Gerätezwillings zu aktualisieren.

Informationen zur weiteren Erkundung von IoT Hub und Geräteverwaltungsmustern, aktualisieren Sie ein Image unter Device Update for Azure IoT Hub unter Verwendung des Raspberry Pi 3 B+-Referenzimages.

Freigeben über

Planen und Übertragen von Aufträgen (Node.js)

Voraussetzungen

Erstellen einer simulierten Geräte-App

Abrufen der IoT-Hub-Verbindungszeichenfolge

Planen von Aufträgen zum Aufrufen einer direkten Methode und Aktualisieren der Eigenschaften eines Gerätezwillings

Ausführen der Anwendungen

Nächste Schritte

Feedback

Zusätzliche Ressourcen