Aan de slag met apparaatdubbels (Node.js)

Artikel
01/29/2024

Apparaatdubbels zijn JSON-documenten waarin statusinformatie van een apparaat zijn opgeslagen, zoals metagegevens, configuraties en voorwaarden. IoT Hub houdt een apparaatdubbel vast voor elk apparaat dat er verbinding mee maakt.

Notitie

De functies die in dit artikel worden beschreven, zijn alleen beschikbaar in de standaardlaag van de IoT Hub. Zie De juiste IoT Hub-laag voor uw oplossing kiezen voor meer informatie over de Basic- en Standard-/gratis IoT Hub-lagen.

Apparaatdubbels gebruiken om:

Sla metagegevens van apparaten op vanuit de back-end van uw oplossing.
Rapporteer actuele statusinformatie, zoals beschikbare mogelijkheden en voorwaarden, bijvoorbeeld de gebruikte connectiviteitsmethode vanuit uw apparaat-app.
Synchroniseer de status van langlopende werkstromen, zoals firmware- en configuratie-updates, tussen een apparaat-app en een back-end-app.
Voer een query uit op de metagegevens, configuratie of status van uw apparaat.

Apparaatdubbels zijn ontworpen voor synchronisatie en voor het opvragen van apparaatconfiguraties en -voorwaarden. Zie Apparaatdubbels begrijpen voor meer informatie over apparaatdubbels, inclusief wanneer u apparaatdubbels gebruikt.

IoT Hubs slaan apparaatdubbels op, die de volgende elementen bevatten:

Tags. Metagegevens van apparaten die alleen toegankelijk zijn voor de back-end van de oplossing.
Gewenste eigenschappen. JSON-objecten kunnen worden gewijzigd door de back-end van de oplossing en waarneembaar door de apparaat-app.
Gerapporteerde eigenschappen. JSON-objecten kunnen worden gewijzigd door de apparaat-app en kunnen worden gelezen door de back-end van de oplossing.

Tags en eigenschappen kunnen geen matrices bevatten, maar kunnen geneste objecten bevatten.

In de volgende afbeelding ziet u de organisatie van apparaatdubbels:

Schermopname van een conceptdiagram van een apparaatdubbel.

Daarnaast kan de back-end van de oplossing een query uitvoeren op apparaatdubbels op basis van alle bovenstaande gegevens. Zie Apparaatdubbels begrijpen voor meer informatie over apparaatdubbels. Zie de Querytaal van IoT Hub voor meer informatie over het uitvoeren van query's.

Dit artikel laat het volgende zien:

Gebruik een gesimuleerde apparaat-app om het connectiviteitskanaal te rapporteren als een gerapporteerde eigenschap op de apparaatdubbel.
Query's uitvoeren op apparaten vanuit uw back-end-app met behulp van filters op de tags en eigenschappen die u eerder hebt gemaakt.

In dit artikel maakt u twee Node.js console-apps:

AddTagsAndQuery.js: een back-end-app die tags toevoegt en query's uitvoert op apparaatdubbels.
TwinSimulatedDevice.js: een gesimuleerde apparaat-app die verbinding maakt met uw IoT-hub en de connectiviteitsvoorwaarde rapporteert.

Notitie

Zie Azure IoT SDK's voor meer informatie over de SDK-hulpprogramma's die beschikbaar zijn voor het bouwen van zowel apparaat- als back-end-apps.

Vereisten

U hebt het volgende nodig om dit artikel te voltooien:

Een IoT-hub. Maak er een met de CLI of Azure Portal.
Een geregistreerd apparaat. Registreer er een in Azure Portal.
Node.js versie 10.0.x of hoger.
Zorg ervoor dat de poort 8883 is geopend in uw firewall. Het apparaatvoorbeeld in dit artikel maakt gebruik van het MQTT-protocol, dat via poort 8883 communiceert. Deze poort is in sommige netwerkomgevingen van bedrijven en onderwijsinstellingen mogelijk geblokkeerd. Zie Verbinding maken met IoT Hub (MQTT) voor meer informatie en manieren om dit probleem te omzeilen.

De IoT Hub-verbindingsreeks ophalen

In dit artikel maakt u een back-endservice die gewenste eigenschappen toevoegt aan een apparaatdubbel en vervolgens het identiteitsregister opvraagt om alle apparaten met gerapporteerde eigenschappen te vinden dienovereenkomstig zijn bijgewerkt. Uw service heeft de serviceverbindingsmachtiging nodig om de gewenste eigenschappen van een apparaatdubbel te wijzigen en heeft de leesmachtiging voor het register nodig om een query uit te voeren op het identiteitsregister. Er is geen standaardbeleid voor gedeelde toegang dat alleen deze twee machtigingen bevat, dus u moet er een maken.

Voer de volgende stappen uit om een gedeeld toegangsbeleid te maken dat serviceverbindings- en registertoegangsmachtigingen verleent en een verbindingsreeks voor dit beleid op te halen:

Selecteer resourcegroepen in de Azure-portal. Selecteer de resourcegroep waar uw hub zich bevindt en selecteer vervolgens uw hub in de lijst met resources.
Selecteer in het linkerdeelvenster van uw hub beleid voor gedeelde toegang.
Selecteer in het bovenste menu boven de lijst met beleidsregels de optie Beleid voor gedeelde beleidsregels toevoegen.
Voer in het deelvenster Gedeeld toegangsbeleid aan de rechterkant een beschrijvende naam in voor uw beleid, zoals serviceAndRegistryRead. Selecteer onder Machtigingen de optie Lezen en Verbinding maken register en Service en selecteer vervolgens Toevoegen.
Selecteer uw nieuwe beleid in de lijst met beleidsregels.
Selecteer het kopieerpictogram voor de primaire verbindingsreeks en sla de waarde op.

Zie Toegangsbeheer en machtigingen voor meer informatie over beleid en machtigingen voor gedeelde toegang van IoT Hub.

Een apparaat-app maken waarmee gerapporteerde eigenschappen worden bijgewerkt

In deze sectie maakt u een Node.js console-app die verbinding maakt met uw hub als myDeviceId en werkt u vervolgens de gerapporteerde eigenschappen van de apparaatdubbel bij om te bevestigen dat deze is verbonden met een mobiel netwerk.

Maak een nieuwe lege map met de naam reportconnectivity. Maak in de map reportconnectivity een nieuw package.json-bestand met behulp van de volgende opdracht bij de opdrachtprompt. De --yes parameter accepteert alle standaardwaarden.
```
npm init --yes
```
Voer bij de opdrachtprompt in de map reportconnectivity de volgende opdracht uit om de azure-iot-device en azure-iot-device-mqtt-pakketten te installeren:
```
npm install azure-iot-device azure-iot-device-mqtt --save
```
Maak met behulp van een teksteditor een nieuw rapport Verbinding maken ivity.js-bestand in de map reportconnectivity.

Voeg de volgende code toe aan het bestand Report Verbinding maken ivity.js. Vervang {device connection string} door het apparaat verbindingsreeks u hebt gezien toen u een apparaat hebt geregistreerd in de 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();
                }
            });
        }
        });
    }
    });

Het clientobject bevat alle methoden die u nodig hebt om te communiceren met apparaatdubbels vanaf het apparaat. De vorige code, nadat het clientobject is geïnitialiseerd, haalt de apparaatdubbel voor myDeviceId op en werkt de gerapporteerde eigenschap bij met de connectiviteitsgegevens.

De apparaat-app uitvoeren
```
    node ReportConnectivity.js
```
Als het goed is, ziet u nu het bericht twin state reported.
Nu het apparaat de connectiviteitsgegevens heeft gerapporteerd, moet het in beide query's worden weergegeven. Ga terug naar de map addtagsandqueryapp en voer de query's opnieuw uit:
```
    node AddTagsAndQuery.js
```
Deze keer moet myDeviceId worden weergegeven in beide queryresultaten.

Een service-app maken waarmee de gewenste eigenschappen worden bijgewerkt en query's worden uitgevoerd op dubbels

In deze sectie maakt u een Node.js console-app waarmee locatiemetagegevens worden toegevoegd aan de apparaatdubbel die is gekoppeld aan myDeviceId. De app vraagt IoT Hub op voor apparaten die zich in de VS bevinden en vraagt vervolgens apparaten op die een mobiele netwerkverbinding rapporteren.

Maak een nieuwe lege map met de naam addtagsandqueryapp. Maak in de map addtagsandqueryapp een nieuw package.json bestand met behulp van de volgende opdracht bij de opdrachtprompt. De --yes parameter accepteert alle standaardwaarden.
```
npm init --yes
```
Voer bij de opdrachtprompt in de map addtagsandqueryapp de volgende opdracht uit om het azure-iothub-pakket te installeren:
```
npm install azure-iothub --save
```
Maak met behulp van een teksteditor een nieuw AddTagsAndQuery.js-bestand in de map addtagsandqueryapp .

Voeg de volgende code toe aan het bestand AddTagsAndQuery.js . Vervang {iot hub connection string} door de IoT Hub-verbindingsreeks die u hebt gekopieerd in De IoT-hub ophalen verbindingsreeks.

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

Het registerobject bevat alle methoden die nodig zijn om te communiceren met apparaatdubbels van de service. De vorige code initialiseert eerst het registerobject , haalt vervolgens de apparaatdubbel voor myDeviceId op en werkt ten slotte de tags bij met de gewenste locatiegegevens.

Na het bijwerken van de tags wordt de functie queryTwins aangeroepen.

Voeg de volgende code toe aan het einde van AddTagsAndQuery.js om de functie queryTwins te implementeren:

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

Met de vorige code worden twee query's uitgevoerd: de eerste selecteert alleen de apparaatdubbels van apparaten die zich in de Redmond43-fabriek bevinden en de tweede verfijnt de query om alleen de apparaten te selecteren die ook zijn verbonden via een mobiel netwerk.

Wanneer de code het queryobject maakt, wordt het maximum aantal geretourneerde documenten in de tweede parameter opgegeven. Het queryobject bevat een booleaanse eigenschap hasMoreResults die u kunt gebruiken om de volgendeAsTwin-methoden meerdere keren aan te roepen om alle resultaten op te halen. Een methode die hierna wordt aangeroepen, is beschikbaar voor resultaten die geen apparaatdubbels zijn, bijvoorbeeld de resultaten van aggregatiequery's.

Voer de toepassing uit met:
```
    node AddTagsAndQuery.js
```
U ziet één apparaat in de resultaten voor de query waarin wordt gevraagd naar alle apparaten die zich in Redmond43 bevinden en geen voor de query die de resultaten beperkt tot apparaten die gebruikmaken van een mobiel netwerk.

In dit artikel leert u het volgende:

Metagegevens van apparaten toegevoegd als tags uit een back-end-app
Gerapporteerde apparaatverbindingsgegevens in de apparaatdubbel
Query's uitgevoerd op de gegevens van de apparaatdubbel, met sql-achtige IoT Hub-querytaal

Volgende stappen

Zie voor meer informatie over:

Telemetrie verzenden vanaf apparaten, zie quickstart: Telemetrie verzenden van een IoT-Plug en Play-apparaat naar Azure IoT Hub
Configureer apparaten met behulp van de gewenste eigenschappen van een apparaatdubbel. Zie Zelfstudie: Uw apparaten configureren vanuit een back-endservice
Apparaten interactief beheren, zoals het inschakelen van een ventilator vanuit een door de gebruiker beheerde app, zie Quickstart: Een apparaat beheren dat is verbonden met een IoT-hub