Bien démarrer avec l’identité de module et le jumeau de module IoT Hub (Node.js)

Article
03/19/2023

Les identités de module et les jumeaux de module sont similaires aux identités d’appareil et aux jumeaux d’appareil Azure IoT Hub, mais offrent un plus grand niveau de détail. Contrairement à l’identité d’appareil et au jumeau d’appareil Azure IoT Hub qui permettent à l’application back-end de configurer un appareil et d’obtenir une visibilité sur les conditions de l’appareil, une identité de module et un jumeau de module fournissent ces capacités pour les composants individuels d’un appareil. Sur les appareils compatibles qui intègrent plusieurs composants, par exemple des appareils avec système d’exploitation ou des appareils avec un microprogramme, ils permettent d’isoler la configuration et les conditions de chacun de ces composants.

Notes

Les fonctionnalités décrites dans cet article sont uniquement disponibles au niveau Standard d’IoT Hub. Pour plus d’informations sur les niveaux de base et standard/gratuit d’IoT Hub, consultez Choisir le niveau IoT Hub correspondant à votre solution.

À la fin de cet article, vous disposerez de deux applications Node.js :

CreateIdentities : crée une identité d’appareil, une identité de module et les clés de sécurité associées pour connecter votre appareil et vos clients de module.
UpdateModuleTwinReportedProperties : envoie à votre hub IoT les propriétés à jour de votre jumeau de module.

Notes

Pour plus d’informations sur les outils SDK disponibles pour créer des applications back-end et d’appareil, consultez Kits SDK Azure IoT.

Prérequis

Un IoT Hub. Créez-en un avec l’interface CLI ou le portail Azure.
Node.j version 10.0.x ou ultérieure. Préparer votre environnement de développement décrit l’installation de Node.js sur Windows ou sur Linux.

Authentification Module

Vous pouvez utiliser des clés symétriques ou des certificats X.509 pour authentifier les identités de module. Pour l’authentification par certificat X.509, le certificat du module doit avoir son nom commun (Common Name/CN) formaté comme CN=<deviceid>/<moduleid>. Par exemple :

openssl req -new -key d1m1.key.pem -out d1m1.csr -subj "/CN=device01\/module01"

Obtenir la chaîne de connexion du hub IoT

Dans cet article, vous allez créer un service back-end qui ajoute un appareil dans le registre des identités, puis ajoute un module à cet appareil. Votre service a besoin de l’autorisation Écriture du registre. Par défaut, chaque hub IoT est créé avec une stratégie d’accès partagé nommée registryReadWrite qui accorde cette autorisation.

Pour obtenir la chaîne de connexion IoT Hub pour la stratégie registryReadWrite, procédez comme suit :

Dans le portail Azure, sélectionnez Groupes de ressources. Sélectionnez le groupe de ressources dans lequel se trouve votre hub, puis sélectionnez votre hub dans la liste des ressources.
Dans le volet de gauche de votre hub, sélectionnez Stratégies d’accès partagé.
Dans la liste des stratégies, sélectionnez la stratégie registryReadWrite.
Copiez la Chaîne de connexion principale, puis enregistrez la valeur.

Pour plus d’informations sur les autorisations et les stratégies d’accès partagé IoT Hub, consultez Contrôle d’accès et autorisations.

Créer une identité d’appareil et une identité de module dans IoT Hub

Dans cette section, vous allez créer une application Node.js qui crée une identité d’appareil et une identité de module dans le registre d’identités de votre hub IoT. Un appareil ou un module ne peut se connecter à un hub IoT que s’il a une entrée dans le registre des identités. Pour plus d’informations, consultez Comprendre le registre des identités dans votre IoT Hub. En exécutant cette application console, une clé et un ID uniques sont générés pour chaque appareil et module. L’ID et la clé respectent la casse. Votre appareil et le module utilisent ces valeurs pour s’identifier lorsqu’ils envoient des messages d’appareil-à-cloud à IoT Hub.

Créez un répertoire pour stocker votre code.
À l’intérieur de ce répertoire, exécutez d’abord npm init -y pour créer un fichier package.json vide comportant les valeurs par défaut. Il s’agit du fichier projet pour votre code.
Exécutez npm install -S azure-iothub@modules-preview pour installer le Kit de développement logiciel (SDK) du service à l’intérieur du sous-répertoire node_modules.

Notes

Dans le nom de sous-répertoire node_modules, le mot « module » désigne « une bibliothèque de nœuds ». En l’occurrence, le terme n’a rien à voir avec les modules IoT Hub.

Créez le fichier .js suivant dans votre répertoire. Appelez-le add.js. Copiez et collez la chaîne de connexion de hub et le nom du hub.

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);
    });
  });
});

Cette application crée une identité d’appareil avec l’ID myFirstDevice et une identité de module avec l’ID myFirstModule sous l’appareil myFirstDevice. (si cet ID de module existe déjà dans le registre d’identité, le code récupère simplement les informations existantes du module.) L’application affiche ensuite la clé primaire pour cette identité. Vous utilisez cette clé dans l’application de module simulé pour vous connecter à votre IoT Hub.

Exécutez-la à l’aide de la commande node add.js. Vous obtiendrez alors une chaîne de connexion pour votre identité d’appareil et une autre pour votre identité de module.

Notes

Le registre des identités IoT Hub stocke uniquement les identités des appareils et des modules pour permettre un accès sécurisé à IoT Hub. Le registre des identités stocke les ID et les clés d’appareil à utiliser en tant qu’informations d’identification de sécurité. Il stocke également un indicateur activé/désactivé pour chaque appareil pouvant être utilisé pour désactiver l’accès de cet appareil. Si votre application a besoin de stocker d’autres métadonnées spécifiques aux appareils, elle doit utiliser un magasin spécifique aux applications. Il n’y a aucun indicateur d’activation/désactivation pour les identités de module. Pour plus d’informations, consultez Comprendre le registre des identités dans votre IoT Hub dans le guide du développeur IoT Hub.

Mettre à jour le jumeau de module à l’aide du SDK d’appareil Node.js

Dans cette section, vous allez créer sur votre appareil simulé une application Node.js qui met à jour les propriétés rapportées du jumeau de module.

Obtenez la chaîne de connexion de votre module. Connectez-vous au portail Azure. Accédez à votre hub IoT, puis sélectionnez Appareils IoT. Recherchez et ouvrez myFirstDevice pour vérifier que myFirstModule a bien été créé. Copiez la chaîne de connexion du module. Vous en aurez besoin à l’étape suivante.
Comme vous l’avez fait à la précédente section, créez un répertoire pour votre code d’appareil et utilisez NPM pour l’initialiser et installer le kit de développement logiciel (SDK) de l’appareil (npm install -S azure-iot-device-amqp@modules-preview).

Notes

La commande npm install peut vous sembler lente. Soyez patient ; elle récupère beaucoup de code du référentiel de packages.

Notes

Si vous voyez l’erreur « npm ERR! registry error parsing json » (Erreur npm : erreur de registre liée à une analyse json), vous pouvez l’ignorer sans risque. Si vous voyez l’erreur « npm ERR! registry error parsing json » (Erreur npm : erreur de registre liée à une analyse json), vous pouvez l’ignorer sans risque.

Créez un fichier appelé twin.js. Copiez et collez la chaîne d’identité de module.

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');
    });
  });
});

Maintenant, exécutez ceci à l’aide de la commande node twin.js.

F:\temp\module_twin>node twin.js

Vous verrez alors :

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

Étapes suivantes

Pour continuer la prise en main de IoT Hub et explorer les autres scénarios IoT, consultez les articles suivants :

Partager via

Bien démarrer avec l’identité de module et le jumeau de module IoT Hub (Node.js)

Prérequis

Authentification Module

Obtenir la chaîne de connexion du hub IoT

Créer une identité d’appareil et une identité de module dans IoT Hub

Mettre à jour le jumeau de module à l’aide du SDK d’appareil Node.js

Étapes suivantes

Commentaires

Commentaires

Ressources supplémentaires