Kom igång med enhetstvillingar (Node.js)

Artikel
01/29/2024

Enhetstvillingar är JSON-dokument som lagrar information om enhetstillstånd, som metadata, konfigurationer och villkor. IoT Hub bevarar en enhetstvilling för varje enhet som ansluter till den.

Kommentar

De funktioner som beskrivs i den här artikeln är endast tillgängliga på standardnivån för IoT Hub. Mer information om de grundläggande och standard-/kostnadsfria IoT Hub-nivåerna finns i Välj rätt IoT Hub-nivå för din lösning.

Använd enhetstvillingar för att:

Lagra enhetsmetadata från lösningens serverdel.
Rapportera aktuell tillståndsinformation, till exempel tillgängliga funktioner och villkor, till exempel den anslutningsmetod som används, från enhetsappen.
Synkronisera tillståndet för långvariga arbetsflöden, till exempel inbyggd programvara och konfigurationsuppdateringar, mellan en enhetsapp och en serverdelsapp.
Fråga efter enhetens metadata, konfiguration eller tillstånd.

Enhetstvillingar är utformade för synkronisering och för att köra frågor mot enhetskonfigurationer och villkor. Mer information om enhetstvillingar, inklusive när du ska använda enhetstvillingar, finns i Förstå enhetstvillingar.

IoT Hubs lagrar enhetstvillingar som innehåller följande element:

Taggar. Enhetsmetadata är endast tillgängliga för lösningens serverdel.
Önskade egenskaper. JSON-objekt som kan ändras av lösningens serverdel och kan observeras av enhetsappen.
Rapporterade egenskaper. JSON-objekt kan ändras av enhetsappen och kan läsas av lösningens serverdel.

Taggar och egenskaper får inte innehålla matriser, men kan innehålla kapslade objekt.

Följande bild visar enhetstvillingorganisationen:

Skärmbild av ett konceptdiagram för enhetstvillingar.

Dessutom kan lösningens serverdel köra frågor mot enhetstvillingar baserat på alla ovanstående data. Mer information om enhetstvillingar finns i Förstå enhetstvillingar. Mer information om frågor finns i IoT Hub-frågespråk.

Den här artikeln visar hur du gör följande:

Använd en simulerad enhetsapp för att rapportera dess anslutningskanal som en rapporterad egenskap på enhetstvillingen.
Fråga enheter från serverdelsappen med filter på taggarna och egenskaperna som skapades tidigare.

I den här artikeln skapar du två Node.js konsolappar:

AddTagsAndQuery.js: en serverdelsapp som lägger till taggar och frågar enhetstvillingar.
TwinSimulatedDevice.js: en simulerad enhetsapp som ansluter till din IoT-hubb och rapporterar dess anslutningsvillkor.

Kommentar

Mer information om de SDK-verktyg som är tillgängliga för att skapa både enhets- och serverdelsappar finns i Azure IoT SDK:er .

Förutsättningar

För att slutföra den här artikeln behöver du:

En IoT-hubb. Skapa en med CLI eller Azure-portalen.
En registrerad enhet. Registrera en i Azure-portalen.
Node.js version 10.0.x eller senare.
Kontrollera att port 8883 är öppen i brandväggen. Enhetsexemplet i den här artikeln använder MQTT-protokollet, som kommunicerar via port 8883. Den här porten kan blockeras i vissa företags- och utbildningsnätverksmiljöer. Mer information och sätt att kringgå det här problemet finns i Anslut ing to IoT Hub (MQTT).

Hämta IoT Hub-anslutningssträng

I den här artikeln skapar du en serverdelstjänst som lägger till önskade egenskaper till en enhetstvilling och sedan frågar identitetsregistret för att hitta alla enheter med rapporterade egenskaper som har uppdaterats i enlighet med detta. Tjänsten behöver behörigheten för tjänstanslutning för att ändra önskade egenskaper för en enhetstvilling, och den behöver registerläsningsbehörighet för att köra frågor mot identitetsregistret. Det finns ingen standardprincip för delad åtkomst som bara innehåller dessa två behörigheter, så du måste skapa en.

Följ dessa steg för att skapa en princip för delad åtkomst som beviljar behörigheter för tjänstanslutning och registerläsning och få en anslutningssträng för den här principen:

I Azure-portalen väljer du Resursgrupper. Välj den resursgrupp där hubben finns och välj sedan din hubb i listan över resurser.
I den vänstra rutan i hubben väljer du Principer för delad åtkomst.
Välj Lägg till princip för delad principåtkomst på den översta menyn ovanför listan med principer.
I fönstret Lägg till princip för delad åtkomst till höger anger du ett beskrivande namn för din princip, till exempel serviceAndRegistryRead. Under Behörigheter väljer du Registerläsning och tjänst Anslut och väljer sedan Lägg till.
Välj din nya princip i listan över principer.
Välj kopieringsikonen för den primära anslutningssträng och spara värdet.

Mer information om principer och behörigheter för delad åtkomst i IoT Hub finns i Åtkomstkontroll och behörigheter.

Skapa en enhetsapp som uppdaterar rapporterade egenskaper

I det här avsnittet skapar du en Node.js-konsolapp som ansluter till din hubb som myDeviceId och uppdaterar sedan enhetstvillingens rapporterade egenskaper för att bekräfta att den är ansluten med ett mobilnät.

Skapa en ny tom mapp med namnet reportconnectivity. I mappen reportconnectivity skapar du en ny package.json fil med hjälp av följande kommando i kommandotolken. Parametern --yes accepterar alla standardvärden.
```
npm init --yes
```
Kör följande kommando i kommandotolken i mappen reportconnectivity för att installera paketen azure-iot-device och azure-iot-device-mqtt :
```
npm install azure-iot-device azure-iot-device-mqtt --save
```
Skapa en ny rapport Anslut ivity.js fil i mappen reportconnectivity med hjälp av en textredigerare.

Lägg till följande kod i filen Report Anslut ivity.js. Ersätt {device connection string} med enheten anslutningssträng du såg när du registrerade en enhet i IoT Hub:

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

Klientobjektet exponerar alla metoder som du behöver för att interagera med enhetstvillingar från enheten. När den tidigare koden har initierat klientobjektet hämtar den enhetstvillingen för myDeviceId och uppdaterar den rapporterade egenskapen med anslutningsinformationen.

Kör enhetsappen
```
    node ReportConnectivity.js
```
Du bör se meddelandet twin state reported.
Nu när enheten har rapporterat sin anslutningsinformation bör den visas i båda frågorna. Gå tillbaka till mappen addtagsandqueryapp och kör frågorna igen:
```
    node AddTagsAndQuery.js
```
Den här gången bör myDeviceId visas i båda frågeresultaten.

Skapa en tjänstapp som uppdaterar önskade egenskaper och frågar tvillingar

I det här avsnittet skapar du en Node.js-konsolapp som lägger till platsmetadata till enhetstvillingen som är associerad med myDeviceId. Appen frågar IoT Hub efter enheter som finns i USA och frågar sedan enheter som rapporterar en mobilnätverksanslutning.

Skapa en ny tom mapp med namnet addtagsandqueryapp. I mappen addtagsandqueryapp skapar du en ny package.json fil med hjälp av följande kommando i kommandotolken. Parametern --yes accepterar alla standardvärden.
```
npm init --yes
```
Kör följande kommando i kommandotolken i mappen addtagsandqueryapp för att installera azure-iothub-paketet :
```
npm install azure-iothub --save
```
Skapa en ny AddTagsAndQuery.js fil i mappen addtagsandqueryapp med hjälp av en textredigerare.

Lägg till följande kod i filen AddTagsAndQuery.js . Ersätt {iot hub connection string} med IoT Hub-anslutningssträng du kopierade i Hämta IoT Hub-anslutningssträng.

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

Registry-objektet exponerar alla metoder som krävs för att interagera med enhetstvillingar från tjänsten. Den föregående koden initierar först registry-objektet , hämtar sedan enhetstvillingen för myDeviceId och uppdaterar slutligen taggarna med önskad platsinformation.

När taggarna har uppdaterats anropas funktionen queryTwins .

Lägg till följande kod i slutet av AddTagsAndQuery.js för att implementera funktionen 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(','));
             }
         });
     };

Den föregående koden kör två frågor: den första väljer endast enhetstvillingar för enheter som finns i Redmond43-anläggningen och den andra förfinar frågan för att endast välja de enheter som också är anslutna via mobilnätet.

När koden skapar frågeobjektet anger den det maximala antalet returnerade dokument i den andra parametern. Frågeobjektet innehåller en boolesk egenskap för hasMoreResults som du kan använda för att anropa nextAsTwin-metoderna flera gånger för att hämta alla resultat. En metod med namnet next är tillgänglig för resultat som inte är enhetstvillingar, till exempel resultatet av aggregeringsfrågor.

Kör programmet med:
```
    node AddTagsAndQuery.js
```
Du bör se en enhet i resultatet för frågan som frågar efter alla enheter som finns i Redmond43 och ingen för frågan som begränsar resultatet till enheter som använder ett mobilnät.

Den här artikeln innehåller följande avsnitt:

Enhetsmetadata har lagts till som taggar från en serverdelsapp
Rapporterad anslutningsinformation för enheter i enhetstvillingen
Efterfrågade information om enhetstvillingen med hjälp av SQL-liknande IoT Hub-frågespråk

Nästa steg

Om du vill ta reda på hur du:

Skicka telemetri från enheter finns i Snabbstart: Skicka telemetri från en IoT Plug and Play-enhet till Azure IoT Hub
Konfigurera enheter med hjälp av enhetstvillingens önskade egenskaper finns i Självstudie: Konfigurera dina enheter från en serverdelstjänst
Kontrollera enheter interaktivt, till exempel aktivera en fläkt från en användarkontrollerad app, se Snabbstart: Kontrollera en enhet som är ansluten till en IoT-hubb