Introduzione ai dispositivi gemelli (Node.js)

Articolo
03/17/2023

i dispositivi gemelli sono documenti JSON che archiviano informazioni sullo stato dei dispositivi, tra cui metadati, configurazioni e condizioni. L'hub IoT rende permanente un dispositivo gemello per ogni dispositivo che si connette.

Nota

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

Usare i dispositivi gemelli per:

Archiviare i metadati dei dispositivi dal back-end della soluzione.
Segnalare informazioni sullo stato corrente, come funzionalità disponibili e condizioni (ad esempio, il metodo di connettività usato) dall'app per dispositivi.
Sincronizzare lo stato dei flussi di lavoro a esecuzione prolungata (come gli aggiornamenti del firmware e della configurazione) tra un'app per dispositivi e un'app di back-end.
Eseguire query sui metadati, la configurazione o lo stato dei dispositivi.

I dispositivi gemelli sono progettati per la sincronizzazione e per l'esecuzione di query sulle configurazioni e le condizioni dei dispositivi. Per altre informazioni sui dispositivi gemelli, tra cui quando usare dispositivi gemelli, vedere Informazioni sui dispositivi gemelli.

Gli hub IoT archiviano i dispositivi gemelli, che contengono gli elementi seguenti:

Tag. Metadati dei dispositivi accessibili solo dal back-end della soluzione.
Proprietà desiderate. Oggetti JSON modificabili dal back-end della soluzione e osservabili dall'app per dispositivi.
Proprietà segnalate. Oggetti JSON modificabili dall'app per dispositivi e leggibili dal back-end della soluzione.

I tag e le proprietà non possono contenere matrici, ma possono contenere oggetti annidati.

Nella figura seguente viene illustrata l'organizzazione di un dispositivo gemello:

Screenshot di un diagramma del concetto di dispositivo gemello.

Il back-end della soluzione può anche eseguire query sui dispositivi gemelli in base a tutti i dati sopra indicati. Per altre informazioni sui dispositivi gemelli, vedere Informazioni sui dispositivi gemelli. Per altre informazioni sulle query, vedere Linguaggio di query di hub IoT.

Questo articolo illustra come:

Usare un'app per dispositivo simulato per segnalare il canale di connettività come proprietà segnalata nel dispositivo gemello.
Eseguire query sui dispositivi dall'app back-end con filtri sui tag e sulle proprietà creati in precedenza.

In questo articolo vengono create due app console Node.js:

AddTagsAndQuery.js: un'app back-end che aggiunge tag ed esegue query sui dispositivi gemelli.
TwinSimulatedDevice.js: un'app per dispositivi simulata che si connette all'hub IoT e ne segnala la condizione di connettività.

Nota

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

Prerequisiti

Per completare questo articolo, devi avere quanto segue:

Un hub IoT. Crearne uno con l'interfaccia della riga di comando o il portale di Azure.
Un dispositivo registrato. Registrarne uno nel portale di Azure.
Node.js 10.0.x o versione successiva.
Assicurarsi che la porta 8883 sia aperta nel firewall. L'esempio di dispositivo di questo articolo usa il protocollo MQTT, che comunica tramite la porta 8883. Questa porta potrebbe essere bloccata in alcuni ambienti di rete aziendali e didattici. Per altre informazioni e soluzioni alternative per questo problema, vedere Connettersi all'hub IoT (MQTT).

Ottenere la stringa di connessione dell'hub IoT

In questo articolo viene creato un servizio back-end che aggiunge le proprietà desiderate a un dispositivo gemello e quindi esegue una query nel registro delle identità per trovare tutti i dispositivi con le proprietà segnalate che sono stati aggiornati di conseguenza. Il servizio richiede l’autorizzazione di connessione al servizio per modificare le proprietà desiderate di un dispositivo gemello ed è necessaria l’autorizzazione di lettura del registro di sistema per eseguire query sul registro delle identità. Non esistono criteri di accesso condiviso predefiniti che contengono solo queste due autorizzazioni, quindi è necessario crearne uno.

Per creare criteri di accesso condiviso che concedono le autorizzazioni di connessione al servizio e lettura del registro di sistema e ottenere una stringa di connessione per questo criterio, attenersi alla seguente procedura:

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.
Nel riquadro sinistro dell'hub selezionare Criteri di accesso condiviso.
Nel menu in alto sopra l'elenco dei criteri selezionare Aggiungi criteri di accesso ai criteri condivisi.
Nel riquadro Aggiungi criteri di accesso condiviso a destra immettere un nome descrittivo per i criteri, ad esempio serviceAndRegistryRead. In Autorizzazioni selezionare Lettura e servizio del Registro di sistema Connessione e quindi selezionare Aggiungi.
Selezionare il nuovo criterio dall'elenco dei criteri.
Selezionare l'icona di copia per il stringa di connessione primario e salvare il valore.

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

Creare un'app per dispositivi che aggiorna le proprietà segnalate

In questa sezione viene creata un'app console Node.js che si connette all'hub come myDeviceId e quindi aggiorna le proprietà segnalate del dispositivo gemello per verificare che sia connessa tramite una rete cellulare.

Creare una nuova cartella vuota denominata reportconnectivity. Nella cartella reportconnectivity creare un nuovo file package.json immettendo il comando seguente al prompt dei comandi. Il parametro --yes accetta tutti i valori predefiniti.
```
npm init --yes
```
Eseguire questo comando al prompt dei comandi nella cartella reportconnectivity per installare i pacchetti azure-iot-device e azure-iot-device-mqtt:
```
npm install azure-iot-device azure-iot-device-mqtt --save
```
Usando un editor di testo, creare un nuovo file ReportConnectivity.js nella cartella reportconnectivity.

Aggiungere il codice seguente al file ReportConnectivity.js. Sostituire {device connection string} con il dispositivo stringa di connessione visualizzato quando è stato registrato un dispositivo nel hub IoT:

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

    var connectionString = '{device connection string}';
    var client = Client.fromConnectionString(connectionString, Protocol);

    client.open(function(err) {
    if (err) {
        console.error('could not open IotHub client');
    }  else {
        console.log('client opened');

        client.getTwin(function(err, twin) {
        if (err) {
            console.error('could not get twin');
        } else {
            var patch = {
                connectivity: {
                    type: 'cellular'
                }
            };

            twin.properties.reported.update(patch, function(err) {
                if (err) {
                    console.error('could not update twin');
                } else {
                    console.log('twin state reported');
                    process.exit();
                }
            });
        }
        });
    }
    });

L'oggetto Client espone tutti i metodi necessari per interagire con i dispositivi gemelli dal dispositivo. Il codice precedente, dopo avere inizializzato l'oggetto Client, recupera il dispositivo gemello per myDeviceId e aggiorna le proprietà segnalate con le informazioni sulla connettività.

Eseguire l'app per dispositivo
```
    node ReportConnectivity.js
```
Dovrebbe essere visualizzato il messaggio twin state reported.
Ora che il dispositivo ha segnalato le informazioni sulla connettività, verrà visualizzato in entrambe le query. Tornare alla cartella addtagsandqueryapp ed eseguire di nuovo le query:
```
    node AddTagsAndQuery.js
```
Questa volta myDeviceId verrà visualizzato nei risultati di entrambe le query.

Creare un'app di servizio che aggiorni le proprietà desiderate e le query dei dispositivi gemelli

In questa sezione si crea a un'app console Node.js che aggiunge i metadati della posizione al dispositivo gemello associato a myDeviceId. L'app esegue una query sull'hub IoT per i dispositivi che si trovano negli Stati Uniti e quindi esegue query sui dispositivi che segnalano una connessione di rete cellulare.

Creare una nuova cartella vuota denominata addtagsandqueryapp. Nella cartella addtagsandqueryapp creare un nuovo file package.json immettendo il comando seguente al prompt dei comandi. Il parametro --yes accetta tutti i valori predefiniti.
```
npm init --yes
```
Eseguire questo comando al prompt dei comandi nella cartella addtagsandqueryapp per installare il pacchetto azure-iothub:
```
npm install azure-iothub --save
```
Usando un editor di testo, creare un nuovo file AddTagsAndQuery.js nella cartella addtagsandqueryapp.

Aggiungere il codice seguente al file AddTagsAndQuery.js. Sostituire {iot hub connection string} con la stringa di connessione dell'hub IoT copiata in Ottenere la stringa di connessione dell'hub IoT.

     'use strict';
     var iothub = require('azure-iothub');
     var connectionString = '{iot hub connection string}';
     var registry = iothub.Registry.fromConnectionString(connectionString);

     registry.getTwin('myDeviceId', function(err, twin){
         if (err) {
             console.error(err.constructor.name + ': ' + err.message);
         } else {
             var patch = {
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                   }
                 }
             };

             twin.update(patch, function(err) {
               if (err) {
                 console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
               } else {
                 console.log(twin.deviceId + ' twin updated successfully');
                 queryTwins();
               }
             });
         }
     });

L'oggetto Registry espone tutti i metodi necessari per interagire con i dispositivi gemelli dal servizio. Il codice precedente inizializza prima l'oggetto Registry, quindi recupera il dispositivo gemello per myDeviceId e infine ne aggiorna i tag con le informazioni sulla posizione desiderate.

Dopo avere aggiornato i tag, chiama la funzione queryTwins.

Aggiungere il codice seguente alla fine di AddTagsAndQuery.js per implementare la funzione queryTwins:

     var queryTwins = function() {
         var query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
         query.nextAsTwin(function(err, results) {
             if (err) {
                 console.error('Failed to fetch the results: ' + err.message);
             } else {
                 console.log("Devices in Redmond43: " + results.map(function(twin) {return twin.deviceId}).join(','));
             }
         });

         query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
         query.nextAsTwin(function(err, results) {
             if (err) {
                 console.error('Failed to fetch the results: ' + err.message);
             } else {
                 console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin) {return twin.deviceId}).join(','));
             }
         });
     };

Il codice precedente esegue due query: la prima seleziona solo i dispositivi gemelli tra quelli situati nello stabilimento Redmond43 e la seconda affina la query per selezionare solo i dispositivi che sono anche connessi tramite la rete cellulare.

Quando il codice crea l’oggetto query , specifica il numero massimo di documenti restituiti nel secondo parametro. L'oggetto query contiene una proprietà booleana hasMoreResults che è possibile usare per richiamare i metodi nextAsTwin più volte per recuperare tutti i risultati. Un metodo chiamato next è disponibile per i risultati che non sono dispositivi gemelli, ad esempio i risultati delle query di aggregazione.

Eseguire l'applicazione con:
```
    node AddTagsAndQuery.js
```
Nei risultati si noterà un dispositivo per la query che cerca tutti i dispositivi situati in Redmond43 e nessuno per la query che limita i risultati ai dispositivi che usano una rete cellulare.

In questo articolo si apprenderà come:

Aggiunta di metadati del dispositivo come tag da un'app back-end
Informazioni sulla connettività del dispositivo segnalate nel dispositivo gemello
Query sulle informazioni sul dispositivo gemello usando un linguaggio di query simile a SQL hub IoT

Passaggi successivi

Per scoprire come:

Inviare dati di telemetria dai dispositivi, vedere Avvio rapido: Inviare dati di telemetria da un dispositivo Plug and Play IoT a hub IoT di Azure
Configurare i dispositivi usando le proprietà desiderate del dispositivo gemello, vedere Esercitazione: Configurare i dispositivi da un servizio back-end
Controllare i dispositivi in modo interattivo, ad esempio l'attivazione di una ventola da un'app controllata dall'utente, vedere Avvio rapido: Controllare un dispositivo connesso a un hub IoT