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

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 platformy .NET:

AddTagsAndQuery: aplikacja zaplecza, która dodaje tagi i wysyła zapytania do bliźniaczych reprezentacji urządzeń.
Raport Połączenie ivity: symulowana aplikacja urządzenia, która łączy się z centrum IoT 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

Visual Studio.
Centrum IoT. Utwórz go za pomocą interfejsu wiersza polecenia lub witryny Azure Portal.
Zarejestrowane urządzenie. Zarejestruj je w witrynie Azure Portal.
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ą platformy .NET, która łączy się z centrum jako myDeviceId, a następnie aktualizuje zgłoszone właściwości, aby potwierdzić, że jest połączona przy użyciu sieci komórkowej.

Otwórz program Visual Studio i wybierz pozycję Utwórz nowy projekt.
Wybierz pozycję Aplikacja konsolowa (.NET Framework), a następnie wybierz pozycję Dalej.
W obszarze Konfigurowanie nowego projektu nadaj projektowi nazwę Raport Połączenie ivity, a następnie wybierz pozycję Dalej.
W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt Raport Połączenie ivity, a następnie wybierz pozycję Zarządzaj pakietami NuGet.
Zachowaj domyślny program .NET Framework, a następnie wybierz pozycję Utwórz , aby utworzyć projekt.
Wybierz pozycję Przeglądaj i wyszukaj i wybierz pozycję Microsoft.Azure.Devices.Client. Wybierz Zainstaluj.

Ten krok pobiera, instaluje i dodaje odwołanie do pakietu NuGet zestawu SDK urządzeń usługi Azure IoT oraz jego zależności.

Dodaj następujące instrukcje using w górnej części pliku Program.cs:

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using Newtonsoft.Json;

Dodaj następujące pola do klasy Program: 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:
```
static string DeviceConnectionString = "HostName=<yourIotHubName>.azure-devices.net;DeviceId=<yourIotDeviceName>;SharedAccessKey=<yourIotDeviceAccessKey>";
static DeviceClient Client = null;
```

Dodaj następującą metodę do klasy Program:

public static async void InitClient()
{
    try
    {
        Console.WriteLine("Connecting to hub");
        Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
          TransportType.Mqtt);
        Console.WriteLine("Retrieving twin");
        await Client.GetTwinAsync();
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

Obiekt Client uwidacznia wszystkie metody wymagane do interakcji z bliźniaczymi reprezentacjami urządzeń z urządzenia. Kod przedstawiony powyżej inicjuje obiekt Client , a następnie pobiera bliźniacza reprezentację urządzenia dla identyfikatora myDeviceId.

Dodaj następującą metodę do klasy Program:

public static async void ReportConnectivity()
{
    try
    {
        Console.WriteLine("Sending connectivity data as reported property");

        TwinCollection reportedProperties, connectivity;
        reportedProperties = new TwinCollection();
        connectivity = new TwinCollection();
        connectivity["type"] = "cellular";
        reportedProperties["connectivity"] = connectivity;
        await Client.UpdateReportedPropertiesAsync(reportedProperties);
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

Powyższy kod aktualizuje zgłoszoną właściwość myDeviceId przy użyciu informacji o łączności.

Na koniec dodaj następujące wiersze do metody Główne:

try
{
    InitClient();
    ReportConnectivity();
}
catch (Exception ex)
{
    Console.WriteLine();
    Console.WriteLine("Error in sample: {0}", ex.Message);
}
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

W Eksplorator rozwiązań kliknij rozwiązanie prawym przyciskiem myszy i wybierz polecenie Ustaw projekty startowe.
W obszarze Typowy projekt startowy właściwości>wybierz pozycję Wiele projektów startowych. W obszarze Raport Połączenie ivity wybierz pozycję Rozpocznij jako akcję. Aby zapisać zmiany, wybierz pozycję OK.
Uruchom tę aplikację, klikając prawym przyciskiem myszy projekt Raport Połączenie ivity i wybierając pozycję Debuguj, a następnie uruchom nowe wystąpienie. Powinna zostać wyświetlona aplikacja uzyskująca informacje o bliźniaczej reprezentacji, a następnie wysyłająca łączność jako zgłoszoną właściwość.

Gdy urządzenie zgłosiło informacje o łączności, powinno zostać wyświetlone w obu zapytaniach.
Kliknij prawym przyciskiem myszy projekt AddTagsAndQuery i wybierz polecenie Debuguj> nowe wystąpienie, aby ponownie uruchomić zapytania. Tym razem identyfikator myDeviceId powinien pojawić się 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ą platformy .NET przy użyciu języka C#, która dodaje metadane lokalizacji do bliźniaczej reprezentacji urządzenia skojarzonej z identyfikatorem 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.

W programie Visual Studio wybierz pozycję Plik > nowy > projekt. W obszarze Tworzenie nowego projektu wybierz pozycję Aplikacja konsolowa (.NET Framework), a następnie wybierz pozycję Dalej.
W obszarze Konfigurowanie nowego projektu nadaj projektowi nazwę AddTagsAndQuery, a następnie wybierz pozycję Dalej.
Zaakceptuj domyślną wersję programu .NET Framework, a następnie wybierz pozycję Utwórz , aby utworzyć projekt.
W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt AddTagsAndQuery, a następnie wybierz polecenie Zarządzaj pakietami NuGet.
Wybierz pozycję Przeglądaj i wyszukaj i wybierz pozycję Microsoft.Azure.Devices. Wybierz Zainstaluj.

Ten krok pobiera, instaluje i dodaje odwołanie do pakietu NuGet zestawu SDK usługi Azure IoT oraz jego zależności.
Dodaj następujące instrukcje using w górnej części pliku Program.cs:
```
using Microsoft.Azure.Devices;
```
Dodaj następujące pola do klasy Program: Zastąp wartość {iot hub connection string} parametry połączenia usługi IoT Hub skopiowaną w sekcji Pobieranie parametry połączenia centrum IoT Hub.
```
static RegistryManager registryManager;
static string connectionString = "{iot hub connection string}";
```
Dodaj następującą metodę do klasy Program:
```
public static async Task AddTagsAndQuery()
{
    var twin = await registryManager.GetTwinAsync("myDeviceId");
    var patch =
        @"{
            tags: {
                location: {
                    region: 'US',
                    plant: 'Redmond43'
                }
            }
        }";
    await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);

    var query = registryManager.CreateQuery(
      "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
    var twinsInRedmond43 = await query.GetNextAsTwinAsync();
    Console.WriteLine("Devices in Redmond43: {0}", 
      string.Join(", ", twinsInRedmond43.Select(t => t.DeviceId)));

    query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
    var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
    Console.WriteLine("Devices in Redmond43 using cellular network: {0}", 
      string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));
}
```
Klasa RegistryManager uwidacznia wszystkie metody wymagane do interakcji z bliźniaczymi reprezentacjami urządzeń z usługi. Poprzedni kod najpierw inicjuje obiekt registryManager , a następnie pobiera bliźniacza reprezentację urządzenia dla identyfikatora myDeviceId, a na koniec aktualizuje tagi przy użyciu żądanych informacji o lokalizacji.

Po zaktualizowaniu wykonuje ona 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.

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

Na koniec dodaj następujące wiersze do metody Główne:

registryManager = RegistryManager.CreateFromConnectionString(connectionString);
AddTagsAndQuery().Wait();
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

Uruchom tę aplikację, klikając prawym przyciskiem myszy projekt AddTagsAndQuery i wybierając pozycję Debuguj, a następnie pozycję Uruchom nowe wystąpienie. 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.

Share via