Erste Schritte mit der Modulidentität und dem Modulzwilling von IoT Hub (Node.js)

Artikel
10/03/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 und geben Aufschluss über den Gerätezustand. Modulidentitäten und Modulzwillinge bieten diese Funktionalität 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 zwei Node.js-Apps:

CreateIdentities: Hiermit werden eine Geräteidentität, eine Modulidentität und ein zugeordneter Sicherheitsschlüssel zum Verbinden Ihrer Geräte- und Modulclients erstellt.
UpdateModuleTwinReportedProperties: Hiermit werden aktualisierte, vom Modulzwilling gemeldete Eigenschaften an Ihren IoT Hub gesendet.

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 IoT Hub in Ihrem Azure-Abonnement. Wenn Sie noch keinen Hub haben, können Sie die Schritte unter Erstellen eines IoT-Hubs ausführen.
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.

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. Ihr Dienst erfordert die Berechtigung Schreibvorgänge in Registrierung. Standardmäßig wird jeder IoT-Hub mit einer SAS-Richtlinie namens registryReadWrite erstellt, die diese Berechtigung 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.

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

In diesem Abschnitt erstellen Sie eine Node.js-App, mit der eine Geräte- und eine Modulidentität in der Identitätsregistrierung Ihres IoT Hub erstellt wird. 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.

Erstellen Sie ein Verzeichnis zum Speichern Ihres Codes.
Führen Sie in diesem Verzeichnis zuerst npm init -y aus, um eine leere Datei „package.json“ mit Standardwerten zu erstellen. Dies ist die Projektdatei für Ihren Code.
Führen Sie npm install -S azure-iothub@modules-preview aus, um das Dienst-SDK im Unterverzeichnis node_modules zu installieren.

Hinweis

Beim Namen des Unterverzeichnisses „node_modules“ steht das Wort „module“ für Node-Bibliotheken. Hier hat der Begriff nichts mit IoT Hub-Modulen zu tun.

Erstellen Sie die folgende JS-Datei in Ihrem Verzeichnis. Geben Sie ihr den Namen add.js. Kopieren Sie Ihre Hub-Verbindungszeichenfolge und den Hub-Namen, und fügen Sie sie ein.

var Registry = require('azure-iothub').Registry;
var uuid = require('uuid');
// Copy/paste your connection string and hub name here
var serviceConnectionString = '<hub connection string from portal>';
var hubName = '<hub name>.azure-devices.net';
// Create an instance of the IoTHub registry
var registry = Registry.fromConnectionString(serviceConnectionString);
// Insert your device ID and moduleId here.
var deviceId = 'myFirstDevice';
var moduleId = 'myFirstModule';
// Create your device as a SAS authentication device
var primaryKey = new Buffer(uuid.v4()).toString('base64');
var secondaryKey = new Buffer(uuid.v4()).toString('base64');
var deviceDescription = {
  deviceId: deviceId,
  status: 'enabled',
  authentication: {
    type: 'sas',
    symmetricKey: {
      primaryKey: primaryKey,
      secondaryKey: secondaryKey
    }
  }
};

// First, create a device identity
registry.create(deviceDescription, function(err) {
  if (err) {
    console.log('Error creating device identity: ' + err);
    process.exit(1);
  }
  console.log('device connection string = "HostName=' + hubName + ';DeviceId=' + deviceId + ';SharedAccessKey=' + primaryKey + '"');

  // Then add a module to that device
  registry.addModule({ deviceId: deviceId, moduleId: moduleId }, function(err) {
    if (err) {
      console.log('Error creating module identity: ' + err);
      process.exit(1);
    }

    // Finally, retrieve the module details from the hub so we can construct the connection string
    registry.getModule(deviceId, moduleId, function(err, foundModule) {
      if (err) {
        console.log('Error getting module back from hub: ' + err);
        process.exit(1);
      }
      console.log('module connection string = "HostName=' + hubName + ';DeviceId=' + foundModule.deviceId + ';ModuleId='+foundModule.moduleId+';SharedAccessKey=' + foundModule.authentication.symmetricKey.primaryKey + '"');
      process.exit(0);
    });
  });
});

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 diese Modul-ID in der Identitätsregistrierung bereits vorhanden ist, werden mit dem Code lediglich die vorhandenen Modulinformationen abgerufen.) Anschließend zeigt die App den Primärschlüssel für diese Identität an. Sie verwenden diesen Schlüssel in der simulierten Modul-App, um eine Verbindung mit Ihrem IoT Hub herzustellen.

Führen Sie sie mit „node add.js“ aus. Dadurch erhalten Sie eine Verbindungszeichenfolge für Ihre Geräteidentität und eine weitere für Ihre Modulidentität.

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 im Handbuch für IoT-Entwickler.

Aktualisieren des Modulzwillings mithilfe des Node.js-Geräte-SDK

In diesem Abschnitt erstellen Sie eine Node.js-App auf Ihrem simulierten Gerät, die die vom Modulzwilling gemeldeten Eigenschaften aktualisiert.

Rufen Sie die Modulverbindungszeichenfolge ab. Melden Sie sich beim Azure-Portal an. Navigieren Sie zu Ihrem IoT-Hub, und wählen Sie IoT-Geräte aus. Suchen Sie nach „myFirstDevice“, und öffnen Sie den Eintrag. Sie sehen, dass „myFirstModule“ erfolgreich erstellt wurde. Kopieren Sie die Modulverbindungszeichenfolge. Sie wird im nächsten Schritt benötigt.
Erstellen Sie ähnlich wie im vorherigen Abschnitt ein Verzeichnis für Ihren Gerätecode, und verwenden Sie npm, um es zu initialisieren und das Geräte-SDK zu installieren (npm install -S azure-iot-device-amqp@modules-preview).

Hinweis

Der NPM-Installationsbefehl kann längere Zeit in Anspruch nehmen. Sie müssen etwas Geduld haben, weil sehr viel Code aus dem Paketrepository übertragen wird.

Hinweis

Wenn eine Fehlermeldung mit dem Inhalt, dass bei NPM ein Fehler bei der Analyse des JSON-Codes aufgetreten ist, angezeigt wird, können Sie diese ignorieren. Wenn eine Fehlermeldung mit dem Inhalt, dass bei NPM ein Fehler bei der Analyse des JSON-Codes aufgetreten ist, angezeigt wird, können Sie diese ignorieren.

Erstellen Sie eine Datei namens „twin.js“. Kopieren Sie die Modulidentitätszeichenfolge, und fügen Sie sie ein.

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-amqp').Amqp;
// Copy/paste your module connection string here.
var connectionString = '<insert module connection string here>';
// Create a client using the Amqp protocol.
var client = Client.fromConnectionString(connectionString, Protocol);
client.on('error', function (err) {
  console.error(err.message);
});
// connect to the hub
client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
  console.log('client opened');
// Create device Twin
  client.getTwin(function(err, twin) {
    if (err) {
      console.error('error getting twin: ' + err);
      process.exit(1);
    }
    // Output the current properties
    console.log('twin contents:');
    console.log(twin.properties);
    // Add a handler for desired property changes
    twin.on('properties.desired', function(delta) {
        console.log('new desired properties received:');
        console.log(JSON.stringify(delta));
    });
    // create a patch to send to the hub
    var patch = {
      updateTime: new Date().toString(),
      firmwareVersion:'1.2.1',
      weather:{
        temperature: 72,
        humidity: 17
      }
    };
    // send the patch
    twin.properties.reported.update(patch, function(err) {
      if (err) throw err;
      console.log('twin state reported');
    });
  });
});

Führen Sie die dann mit dem Befehl node twin.js aus.

F:\temp\module_twin>node twin.js

Anschließend wird Folgendes angezeigt:

client opened
twin contents:
{ reported: { update: [Function: update], '$version': 1 },
  desired: { '$version': 1 } }
new desired properties received:
{"$version":1}
twin state reported

Nächste Schritte

Informationen zu den weiteren ersten Schritten mit IoT Hub und zum Kennenlernen anderer IoT-Szenarien finden Sie in den folgenden Artikeln:

Freigeben über

Erste Schritte mit der Modulidentität und dem Modulzwilling von IoT Hub (Node.js)

Voraussetzungen

Modulauthentifizierung

Abrufen der IoT-Hub-Verbindungszeichenfolge

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

Aktualisieren des Modulzwillings mithilfe des Node.js-Geräte-SDK

Nächste Schritte

Feedback

Zusätzliche Ressourcen