Wprowadzenie do bliźniaczych reprezentacji urządzeń (Node.js)

Artykuł
01/29/2024

Bliźniacze reprezentacje urządzeń to dokumenty JSON, które przechowują informacje o stanie urządzenia, takie jak metadane, konfiguracje i warunki. Usługa IoT Hub utrzymuje bliźniacze reprezentację urządzenia dla każdego urządzenia, które łączy się z nim.

Uwaga

Funkcje opisane w tym artykule są dostępne tylko w warstwie Standardowa usługi IoT Hub. Aby uzyskać więcej informacji na temat warstw podstawowej i standardowej/bezpłatnej usługi IoT Hub, zobacz Wybieranie odpowiedniej warstwy usługi IoT Hub dla rozwiązania.

Użyj bliźniaczych reprezentacji urządzeń, aby:

Przechowywanie metadanych urządzenia z zaplecza rozwiązania.
Zgłoś bieżące informacje o stanie, takie jak dostępne możliwości i warunki, na przykład użyta metoda łączności z poziomu aplikacji urządzenia.
Synchronizuj stan długotrwałych przepływów pracy, takich jak aktualizacje oprogramowania układowego i konfiguracji, między aplikacją urządzenia a aplikacją zaplecza.
Wykonywanie zapytań dotyczących metadanych, konfiguracji lub stanu urządzenia.

Bliźniacze reprezentacje urządzeń są przeznaczone do synchronizacji i wykonywania zapytań dotyczących konfiguracji i warunków urządzeń. Aby uzyskać więcej informacji o bliźniaczych reprezentacjach urządzeń, w tym o tym, kiedy używać bliźniaczych reprezentacji urządzeń, zobacz Omówienie bliźniaczych reprezentacji urządzeń.

Centra IoT przechowują bliźniacze reprezentacje urządzeń, które zawierają następujące elementy:

Tagi. Metadane urządzenia dostępne tylko przez zaplecze rozwiązania.
Żądane właściwości. Obiekty JSON modyfikowalne przez zaplecze rozwiązania i można je zaobserwować przez aplikację urządzenia.
Zgłoszone właściwości. Obiekty JSON modyfikowalne przez aplikację urządzenia i czytelne dla zaplecza rozwiązania.

Tagi i właściwości nie mogą zawierać tablic, ale mogą zawierać zagnieżdżone obiekty.

Poniższa ilustracja przedstawia organizację bliźniaczej reprezentacji urządzenia:

Zrzut ekranu przedstawiający diagram koncepcji bliźniaczej reprezentacji urządzenia.

Ponadto zaplecze rozwiązania może wykonywać zapytania dotyczące bliźniaczych reprezentacji urządzeń na podstawie wszystkich powyższych danych. Aby uzyskać więcej informacji na temat bliźniaczych reprezentacji urządzeń, zobacz Omówienie bliźniaczych reprezentacji urządzeń. Aby uzyskać więcej informacji na temat wykonywania zapytań, zobacz Język zapytań usługi IoT Hub.

W tym artykule pokazano, w jaki sposób wykonać następujące czynności:

Użyj aplikacji urządzenia symulowanego, aby zgłosić swój kanał łączności jako zgłoszoną właściwość na bliźniaczej reprezentacji urządzenia.
Wykonywanie zapytań dotyczących urządzeń z aplikacji zaplecza przy użyciu filtrów w utworzonych wcześniej tagach i właściwościach.

W tym artykule utworzysz dwie aplikacje konsolowe Node.js:

AddTagsAndQuery.js: aplikacja zaplecza, która dodaje tagi i wysyła zapytania do bliźniaczych reprezentacji urządzeń.
TwinSimulatedDevice.js: symulowana aplikacja urządzenia, która łączy się z centrum IoT Hub i zgłasza jej stan łączności.

Uwaga

Zobacz Zestawy SDK usługi Azure IoT, aby uzyskać więcej informacji na temat narzędzi zestawu SDK dostępnych do kompilowania aplikacji urządzeń i zaplecza.

Wymagania wstępne

Aby ukończyć pracę z tym artykułem, potrzebne są następujące zasoby:

Centrum IoT. Utwórz go za pomocą interfejsu wiersza polecenia lub witryny Azure Portal.
Zarejestrowane urządzenie. Zarejestruj je w witrynie Azure Portal.
Node.js w wersji 10.0.x lub nowszej.
Upewnij się, że port 8883 jest otwarty w zaporze. Przykład urządzenia w tym artykule używa protokołu MQTT, który komunikuje się za pośrednictwem portu 8883. Ten port może zostać zablokowany w niektórych środowiskach sieci firmowych i edukacyjnych. Aby uzyskać więcej informacji i sposobów obejścia tego problemu, zobacz Połączenie do usługi IoT Hub (MQTT).

Pobieranie parametry połączenia centrum IoT

W tym artykule utworzysz usługę zaplecza, która dodaje żądane właściwości do bliźniaczej reprezentacji urządzenia, a następnie wysyła zapytanie do rejestru tożsamości w celu znalezienia wszystkich urządzeń z zgłoszonymi właściwościami, które zostały odpowiednio zaktualizowane. Usługa wymaga uprawnienia połączenia usługi, aby zmodyfikować żądane właściwości bliźniaczej reprezentacji urządzenia i potrzebuje uprawnień do odczytu rejestru w celu wykonywania zapytań dotyczących rejestru tożsamości. Nie ma domyślnych zasad dostępu współdzielonego, które zawierają tylko te dwa uprawnienia, więc musisz je utworzyć.

Aby utworzyć zasady dostępu współdzielonego, które udzielają uprawnień do nawiązywania połączenia z usługą i odczytu rejestru i uzyskiwania parametry połączenia dla tych zasad, wykonaj następujące kroki:

W witrynie Azure Portal wybierz pozycję Grupy zasobów. Wybierz grupę zasobów, w której znajduje się centrum, a następnie wybierz centrum z listy zasobów.
W okienku po lewej stronie centrum wybierz pozycję Zasady dostępu współdzielonego.
W górnym menu powyżej listy zasad wybierz pozycję Dodaj zasady dostępu współdzielonego.
W okienku Dodawanie zasad dostępu współdzielonego po prawej stronie wprowadź opisową nazwę zasad , taką jak serviceAndRegistryRead. W obszarze Uprawnienia wybierz pozycję Odczyt rejestru i usługa Połączenie, a następnie wybierz pozycję Dodaj.
Wybierz nowe zasady z listy zasad.
Wybierz ikonę kopiowania dla parametry połączenia podstawowej i zapisz wartość.

Aby uzyskać więcej informacji na temat zasad dostępu współdzielonego i uprawnień usługi IoT Hub, zobacz Kontrola dostępu i uprawnienia.

Tworzenie aplikacji urządzenia, która aktualizuje zgłoszone właściwości

W tej sekcji utworzysz aplikację konsolową Node.js, która łączy się z centrum jako myDeviceId, a następnie aktualizuje zgłoszone właściwości bliźniaczej reprezentacji urządzenia, aby potwierdzić, że jest połączona przy użyciu sieci komórkowej.

Utwórz nowy pusty folder o nazwie reportconnectivity. W folderze reportconnectivity utwórz nowy plik package.json przy użyciu następującego polecenia w wierszu polecenia. Parametr --yes akceptuje wszystkie wartości domyślne.
```
npm init --yes
```
W wierszu polecenia w folderze reportconnectivity uruchom następujące polecenie, aby zainstalować pakiety azure-iot-device i azure-iot-device-mqtt :
```
npm install azure-iot-device azure-iot-device-mqtt --save
```
Za pomocą edytora tekstów utwórz nowy plik Report Połączenie ivity.js w folderze reportconnectivity.

Dodaj następujący kod do pliku Report Połączenie ivity.js. Zastąp {device connection string} element urządzeniem parametry połączenia, który został wyświetlony podczas rejestrowania urządzenia w usłudze 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();
                }
            });
        }
        });
    }
    });

Obiekt Client uwidacznia wszystkie metody wymagane do interakcji z bliźniaczymi reprezentacjami urządzeń z urządzenia. Poprzedni kod, po zainicjowaniu obiektu Client , pobiera bliźniacza reprezentację urządzenia dla identyfikatora myDeviceId i aktualizuje swoją zgłoszoną właściwość przy użyciu informacji o łączności.

Uruchamianie aplikacji urządzenia
```
    node ReportConnectivity.js
```
Powinien zostać wyświetlony komunikat twin state reported.
Teraz, gdy urządzenie zgłosiło informacje o łączności, powinno zostać wyświetlone w obu zapytaniach. Wróć do folderu addtagsandqueryapp i ponownie uruchom zapytania:
```
    node AddTagsAndQuery.js
```
Tym razem identyfikator myDeviceId powinien być wyświetlany w obu wynikach zapytania.

Tworzenie aplikacji usługi, która aktualizuje żądane właściwości i wysyła zapytania do bliźniaczych reprezentacji

W tej sekcji utworzysz aplikację konsolową Node.js, która dodaje metadane lokalizacji do bliźniaczej reprezentacji urządzenia skojarzonej z parametrem myDeviceId. Aplikacja wysyła zapytanie do centrum IoT dla urządzeń znajdujących się w Stanach Zjednoczonych, a następnie wysyła zapytania do urządzeń, które zgłaszają połączenie sieciowe.

Utwórz nowy pusty folder o nazwie addtagsandqueryapp. W folderze addtagsandqueryapp utwórz nowy plik package.json przy użyciu następującego polecenia w wierszu polecenia. Parametr --yes akceptuje wszystkie wartości domyślne.
```
npm init --yes
```
W wierszu polecenia w folderze addtagsandqueryapp uruchom następujące polecenie, aby zainstalować pakiet azure-iothub :
```
npm install azure-iothub --save
```
Za pomocą edytora tekstów utwórz nowy plik AddTagsAndQuery.js w folderze addtagsandqueryapp .

Dodaj następujący kod do pliku AddTagsAndQuery.js . Zastąp element {iot hub connection string} parametry połączenia usługi IoT Hub skopiowanym w sekcji Pobieranie parametry połączenia centrum IoT Hub.

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

Obiekt Registry uwidacznia wszystkie metody wymagane do interakcji z bliźniaczymi reprezentacjami urządzeń z usługi. Poprzedni kod najpierw inicjuje obiekt Registry , a następnie pobiera bliźniacza reprezentację urządzenia dla identyfikatora myDeviceId, a na koniec aktualizuje jego tagi przy użyciu żądanych informacji o lokalizacji.

Po zaktualizowaniu tagów wywołuje funkcję queryTwins .

Dodaj następujący kod na końcu AddTagsAndQuery.js , aby zaimplementować funkcję 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(','));
             }
         });
     };

Poprzedni kod wykonuje dwa zapytania: pierwszy wybiera tylko bliźniacze reprezentacje urządzeń znajdujące się w zakładzie Redmond43 , a drugi uściśli zapytanie, aby wybrać tylko urządzenia, które są również połączone za pośrednictwem sieci komórkowej.

Gdy kod tworzy obiekt zapytania , określa maksymalną liczbę zwracanych dokumentów w drugim parametrze. Obiekt zapytania zawiera właściwość logiczną hasMoreResults , której można użyć do wywołania metod nextAsTwin wiele razy w celu pobrania wszystkich wyników. Metoda o nazwie next jest dostępna dla wyników, które nie są bliźniaczymi reprezentacjami urządzeń, na przykład wynikami zapytań agregacji.

Uruchom aplikację za pomocą:
```
    node AddTagsAndQuery.js
```
Powinno zostać wyświetlone jedno urządzenie w wynikach zapytania z prośbą o wszystkie urządzenia znajdujące się w Redmond43 i żadne zapytanie, które ogranicza wyniki do urządzeń korzystających z sieci komórkowej.

W tym artykule opisano następujące zagadnienia:

Dodano metadane urządzenia jako tagi z aplikacji zaplecza
Zgłoszone informacje o łączności urządzenia w bliźniaczej reprezentacji urządzenia
Odpytywanie informacji o bliźniaczej reprezentacji urządzenia przy użyciu języka zapytań przypominającego usługę IoT Hub

Następne kroki

Aby dowiedzieć się, jak:

Wysyłanie danych telemetrycznych z urządzeń, zobacz Szybki start: wysyłanie danych telemetrycznych z urządzenia IoT Plug and Play do usługi Azure IoT Hub
Konfigurowanie urządzeń przy użyciu żądanych właściwości bliźniaczej reprezentacji urządzenia, zobacz Samouczek: konfigurowanie urządzeń z poziomu usługi zaplecza
Interaktywne sterowanie urządzeniami, takimi jak włączanie wentylatora z aplikacji kontrolowanej przez użytkownika, zobacz Szybki start: kontrolowanie urządzenia podłączonego do centrum IoT Hub