Condividi tramite

Introduzione all'identità del modulo dell'hub IoT e al modulo gemello (Node.js)

  • Articolo

Le identità del modulo e i moduli gemelli sono simili alle identità del dispositivo e ai dispositivi gemelli dell'hub IoT di Azure, ma offrono una granularità superiore. Mentre l'identità del dispositivo e il dispositivo gemello dell'hub IoT di Azure consentono all'applicazione back-end di configurare un dispositivo e forniscono visibilità sulle condizioni del dispositivo, l'identità del modulo e il modulo gemello forniscono queste funzionalità per i singoli componenti di un dispositivo. Nei dispositivi con più componenti, ad esempio i dispositivi del sistema operativo o i dispositivi firmware, è possibile isolare la configurazione e le condizioni di ogni componente.

Nota

Le funzionalità descritte in questo articolo sono disponibili solo nel livello Standard dell'hub IoT. Per altre informazioni sui livelli Basic e Standard/Gratuito dell'hub IoT, vedere Scegliere il livello appropriato dell'hub IoT per la soluzione.

Al termine di questo articolo si avranno due app Node.js:

  • CreateIdentities: crea un'identità del dispositivo, un'identità del modulo e le chiavi di sicurezza associata per connettere i client dispositivo e modulo.

  • UpdateModuleTwinReportedProperties: invia le proprietà segnalate aggiornate del modulo gemello all'hub IoT.

Nota

Vedere Azure IoT SDK per altre informazioni sugli strumenti SDK disponibili per creare app sia per dispositivi che back-end.

Prerequisiti

  • Un hub IoT nella sottoscrizione di Azure. Se non si ha ancora un hub, è possibile seguire la procedura descritta in Creare un hub IoT.

  • Node.js 10.0.x o versione successiva. Preparare l'ambiente di sviluppo descrive come installare Node.js per questo articolo in Windows o Linux.

Autenticazione modulo

È possibile usare chiavi simmetriche o certificati X.509 per autenticare le identità del modulo. Per l'autenticazione del certificato X.509, il certificato del modulo deve avere il nome comune (CN) formattato come CN=<deviceid>/<moduleid>. Ad esempio:

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

Ottenere la stringa di connessione dell'hub IoT

In questo articolo viene creato un servizio back-end che aggiunge un dispositivo nel registro delle identità e quindi aggiunge un modulo a tale dispositivo. Il servizio richiede l'autorizzazione Scrittura registro. Per impostazione predefinita, ogni hub IoT viene creato con un criterio di accesso condiviso denominato registryReadWrite che concede tale autorizzazione.

Per ottenere la stringa di connessione dell'hub IoT per i criteri registryReadWrite, seguire questa procedura:

  1. Nel portale di Azure fare clic su Gruppi di risorse. Selezionare il gruppo di risorse in cui si trova l'hub e quindi selezionare l'hub dall'elenco di risorse.

  2. Nel riquadro sinistro dell'hub selezionare Criteri di accesso condiviso.

  3. Dall'elenco dei criteri selezionare il criterio registryReadWrite.

  4. Copiare la Stringa di connessione primaria e salvare il valore.

    Screenshot che mostra come recuperare la stringa di connessione

Per altre informazioni sui criteri di accesso condiviso e sulle autorizzazioni dell'hub IoT, vedere Controllo dell'accesso e autorizzazioni.

Creare un'identità del dispositivo e un'identità del modulo nell'hub IoT

In questa sezione si scriverà un'app Node.js che crea un'identità del dispositivo e un'identità del modulo nel registro delle identità dell'hub IoT. Un dispositivo o un modulo non può connettersi all'hub IoT se non ha una voce nel registro delle identità. Per altre informazioni, vedere Informazioni sul registro delle identità nell'hub IoT. Quando si esegue questa app console vengono generati un ID e una chiave univoci sia per il dispositivo che per il modulo. L'ID e la chiave fanno distinzione tra maiuscole e minuscole. Il dispositivo e il modulo usano questi valori per identificarsi quando inviano messaggi da dispositivo a cloud all'hub IoT.

  1. Creare una directory per il codice.

  2. All'interno di tale directory, eseguire prima di tutto npm init -y per creare un file package.json vuoto con i valori predefiniti. Questo è il file di progetto per il codice.

  3. Eseguire npm install -S azure-iothub@modules-preview per installare l'SDK del servizio all'interno della sottodirectory node_modules.

    Nota

    Nel nome di sottodirectory node_modules, il riferimento a modulo viene usato con il significato di "libreria del nodo". In questo contesto il termine non ha nulla a che fare con i moduli dell'hub IoT.

  4. Creare il file con estensione js seguente nella directory. Chiamarlo add.js. Copiare e incollare la stringa di connessione dell'hub e il nome dell'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);
    });
  });
});

Questa app crea un'identità del dispositivo con ID myFirstDevice e un'identità del modulo con ID myFirstModule per il dispositivo myFirstDevice. Se questo ID modulo è già presente nel registro delle identità, il codice recupera semplicemente le informazioni esistenti sul modulo. L'app visualizzerà quindi la chiave primaria per l'identità. Questa chiave verrà usata dall'app per modulo simulato per connettersi all'hub IoT.

Eseguire questa operazione usando node add.js. Si otterrà una stringa di connessione per l'identità del dispositivo e un'altra per l'identità del modulo.

Nota

Il registro delle identità dell'hub IoT archivia solo le identità del dispositivo e del modulo per abilitare l'accesso sicuro all'hub. Il registro delle identità archivia gli ID dispositivo e le chiavi da usare come credenziali di sicurezza. Il registro delle identità archivia anche un flag di abilitazione/disabilitazione per ogni dispositivo che consente di disabilitare l'accesso per un dispositivo. Se l'applicazione deve archiviare altri metadati specifici del dispositivo, dovrà usare un archivio specifico dell'applicazione. Non esiste alcun flag abilitato/disabilitato per le identità del modulo. Per altre informazioni, vedere Informazioni sul registro delle identità nell'hub IoT nella guida per sviluppatori dell'hub IoT.

Aggiornare il modulo gemello usando l'SDK per dispositivi Node.js

In questa sezione, nel dispositivo simulato viene creata un'app Node.js che aggiorna le proprietà restituite del modulo gemello.

  1. Ottenere la stringa di connessione del modulo. Accedere al portale di Azure. Passare all'hub IoT e selezionare dispositivi IoT. Trovare myFirstDevice e aprirlo. Si vedrà che myFirstModule è stato creato correttamente. Copiare la stringa di connessione del modulo. Sarà necessaria nel prossimo passaggio.

    Dettagli del modulo nel portale di Azure

  2. In modo simile a quanto fatto nel passaggio precedente, creare una directory per il codice del dispositivo e usare NPM per inizializzarlo e installare l'SDK del dispositivo (npm install -S azure-iot-device-amqp@modules-preview).

    Nota

    L'esecuzione del comando npm install potrebbe sembrare lenta. Attendere pazientemente perché è richiesto il pull di molto codice dal repository dei pacchetti.

    Nota

    Se viene visualizzato un messaggio di errore per NPM che segnala un errore del Registro di sistema durante l'analisi JSON, è possibile ignorarlo. Se viene visualizzato un messaggio di errore per NPM che segnala un errore del Registro di sistema durante l'analisi JSON, è possibile ignorarlo.

  3. Creare un file denominato twin.js. Copiare e incollare la stringa di identità del modulo.

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

  4. A questo punto, eseguire il comando node twin.js.

    F:\temp\module_twin>node twin.js

    Si vedrà quindi:

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

Passaggi successivi

Per altre informazioni sulle attività iniziali con l'hub IoT e per esplorare altri scenari IoT, vedere: