Wprowadzenie do tożsamości modułu IoT Hub i bliźniaczej reprezentacji modułu (.NET)

Artykuł
08/25/2023

Tożsamości modułów i bliźniacze reprezentacje modułów są podobne do tożsamości urządzenia i bliźniaczej reprezentacji urządzenia usługi Azure IoT Hub, ale zapewniają większy stopień szczegółowości. Podczas gdy Azure IoT Hub tożsamości urządzenia i bliźniaczej reprezentacji urządzenia umożliwiają aplikacji zaplecza skonfigurowanie urządzenia i zapewnienie widoczności warunków urządzenia, tożsamość modułu i bliźniaczą reprezentacja modułu zapewniają te możliwości dla poszczególnych składników urządzenia. Na urządzeniach obsługujących wiele składników, takich jak urządzenia z systemem operacyjnym lub urządzenia układowe, tożsamości modułów i bliźniacze reprezentacje modułów umożliwiają izolowane konfiguracje i warunki dla każdego składnika.

Uwaga

Funkcje opisane w tym artykule są dostępne tylko w warstwie Standardowa IoT Hub. Aby uzyskać więcej informacji o warstwach podstawowa i Standardowa/Bezpłatna IoT Hub, zobacz Wybieranie odpowiedniej warstwy IoT Hub dla rozwiązania.

Na końcu tego artykułu masz dwie aplikacje konsolowe platformy .NET:

CreateIdentities: tworzy tożsamość urządzenia, tożsamość modułu i skojarzony klucz zabezpieczeń w celu połączenia urządzeń i klientów modułu.
UpdateModuleTwinReportedProperties: wysyła zaktualizowaną reprezentację modułu, zgłaszane właściwości do centrum IoT.

Uwaga

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

Wymagania wstępne

Programu Visual Studio.
Centrum IoT. Utwórz go przy użyciu interfejsu wiersza polecenia lub Azure Portal.

Uwierzytelnianie modułu

Do uwierzytelniania tożsamości modułów można użyć kluczy symetrycznych lub certyfikatów X.509. W przypadku uwierzytelniania certyfikatu X.509 certyfikat modułu musi mieć jego nazwę pospolitą (CN) w formacie , na przykład CN=<deviceid>/<moduleid>. Na przykład:

openssl req -new -key d1m1.key.pem -out d1m1.csr -subj "/CN=device01\/module01"

Pobieranie parametrów połączenia centrum IoT

W tym artykule utworzysz usługę zaplecza, która dodaje urządzenie w rejestrze tożsamości, a następnie dodaje moduł do tego urządzenia. Usługa wymaga uprawnień do zapisu rejestru . Domyślnie każde centrum IoT jest tworzone przy użyciu zasad dostępu współdzielonego o nazwie registryReadWrite , które przyznaje to uprawnienie.

Aby uzyskać parametry połączenia IoT Hub dla zasad registryReadWrite, wykonaj następujące kroki:

W 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.
Z listy zasad wybierz zasady registryReadWrite .
Skopiuj podstawowe parametry połączenia i zapisz wartość.

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

Tworzenie tożsamości modułu

W tej sekcji utworzysz aplikację konsolową platformy .NET, która tworzy tożsamość urządzenia i tożsamość modułu w rejestrze tożsamości w centrum. Urządzenie lub moduł nie może nawiązać połączenia z centrum, chyba że ma wpis w rejestrze tożsamości. Więcej informacji znajduje się w sekcji Identity registry (Rejestr tożsamości) artykułu IoT Hub developer guide (Usługa IoT Hub — przewodnik dewelopera).

Uruchomienie tej aplikacji konsolowej powoduje wygenerowanie unikatowego identyfikatora i klucza zarówno dla urządzenia, jak i modułu. Urządzenie i moduł używają tych wartości do identyfikowania się podczas wysyłania komunikatów z urządzenia do chmury do IoT Hub. W identyfikatorach jest uwzględniana wielkość liter.

Otwórz program Visual Studio i wybierz pozycję Utwórz nowy projekt.
W obszarze Tworzenie nowego projektu wybierz pozycję Aplikacja konsolowa (.NET Framework).
Wybierz przycisk Dalej , aby otworzyć pozycję Konfiguruj nowy projekt. Nadaj projektowi nazwę CreateIdentities, a następnie wybierz pozycję Dalej.
Zachowaj domyślną opcję .NET Framework i wybierz pozycję Utwórz, aby utworzyć projekt.
W programie Visual Studio otwórz pozycję Narzędzia> Menedżer >pakietów NuGetZarządzaj pakietami NuGet dla rozwiązania. Wybierz kartę Przeglądaj.
Wyszukaj ciąg Microsoft.Azure.Devices. Wybierz go, a następnie wybierz pozycję Zainstaluj.

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

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Common.Exceptions;

Dodaj następujące pola do klasy Program: Zastąp wartość symbolu zastępczego parametrami połączenia usługi IoT Hub dla centrum IoT utworzonego w poprzedniej sekcji.
```
const string connectionString = "<replace_with_iothub_connection_string>";
const string deviceID = "myFirstDevice";
const string moduleID = "myFirstModule";
```

Dodaj następujący kod do klasy Main .

static void Main(string[] args)
{
    AddDeviceAsync().Wait();
    AddModuleAsync().Wait();
}

Dodaj następujące metody do klasy Program:
```
private static async Task AddDeviceAsync()
{
   RegistryManager registryManager = 
     RegistryManager.CreateFromConnectionString(connectionString);
   Device device;

   try
   {
       device = await registryManager.AddDeviceAsync(new Device(deviceID));
   }
   catch (DeviceAlreadyExistsException)
    {
        device = await registryManager.GetDeviceAsync(deviceID);
    }

    Console.WriteLine("Generated device key: {0}", 
      device.Authentication.SymmetricKey.PrimaryKey);
}

private static async Task AddModuleAsync()
{
    RegistryManager registryManager = 
      RegistryManager.CreateFromConnectionString(connectionString);
    Module module;

    try
    {
        module = 
          await registryManager.AddModuleAsync(new Module(deviceID, moduleID));
    }
    catch (ModuleAlreadyExistsException)
    {
        module = await registryManager.GetModuleAsync(deviceID, moduleID);
    }

    Console.WriteLine("Generated module key: {0}", module.Authentication.SymmetricKey.PrimaryKey);
}
```
Metoda AddDeviceAsync tworzy tożsamość urządzenia o identyfikatorze myFirstDevice. Jeśli ten identyfikator urządzenia już istnieje w rejestrze tożsamości, kod po prostu pobiera istniejące informacje o urządzeniu. Aplikacja następnie wyświetla klucz podstawowy dla tej tożsamości. Ten klucz jest używany w aplikacji urządzenia symulowanego do nawiązywania połączenia z centrum.

Metoda AddModuleAsync tworzy tożsamość modułu o identyfikatorze myFirstModule w obszarze urządzenia myFirstDevice. Jeśli ten identyfikator modułu już istnieje w rejestrze tożsamości, kod po prostu pobiera informacje o istniejącym module. Aplikacja następnie wyświetla klucz podstawowy dla tej tożsamości. Ten klucz jest używany w symulowanej aplikacji modułu, aby nawiązać połączenie z centrum.

Ważne

Identyfikator urządzenia może być widoczny w dziennikach zbieranych na potrzeby obsługi klienta i rozwiązywania problemów, dlatego upewnij się, żeby unikać poufnych informacji podczas nadawania mu nazwy.
Uruchom tę aplikację i zanotuj klucz urządzenia i klucz modułu.

Uwaga

Rejestr tożsamości IoT Hub przechowuje tylko tożsamości urządzeń i modułów, aby umożliwić bezpieczny dostęp do centrum. W rejestrze tożsamości są przechowywane identyfikatory urządzeń i klucze służące jako poświadczenia zabezpieczeń. W rejestrze tożsamości są także przechowywane flagi włączenia/wyłączenia dla każdego urządzenia, za pomocą których można wyłączyć dostęp do danego urządzenia. Jeśli aplikacja musi przechowywać inne metadane specyficzne dla urządzenia, powinna używać magazynu specyficznego dla aplikacji. Nie istnieje flaga włączenia/wyłączenia tożsamości modułów. Więcej informacji znajduje się w temacie IoT Hub Developer Guide (Usługa IoT Hub — przewodnik dewelopera).

Aktualizowanie bliźniaczej reprezentacji modułu przy użyciu zestawu SDK urządzenia platformy .NET

Teraz przekażemy chmurę z symulowanego urządzenia. Po utworzeniu tożsamości modułu w centrum IoT Hub jest niejawnie tworzona bliźniacza reprezentacja modułu. W tej sekcji tworzysz na urządzeniu symulowanym aplikację konsolową .NET, która aktualizuje zgłoszone właściwości bliźniaczej reprezentacji modułu.

Aby pobrać parametry połączenia modułu, przejdź do centrum IoT, a następnie wybierz pozycję Urządzenia. Znajdź i wybierz pozycję myFirstDevice , aby go otworzyć, a następnie wybierz pozycję myFirstModule , aby go otworzyć. W obszarze Szczegóły tożsamości modułu skopiuj parametry połączenia (klucz podstawowy) i zapisz je dla aplikacji konsolowej.

W programie Visual Studio dodaj nowy projekt do rozwiązania, wybierając pozycję Plik>nowy>projekt. W obszarze Utwórz nowy projekt wybierz pozycję Aplikacja konsolowa (.NET Framework), a następnie wybierz przycisk Dalej.
W obszarze Konfigurowanie nowego projektu nadaj projektowi nazwę UpdateModuleTwinReportedProperties, a następnie wybierz pozycję Dalej.
Zachowaj domyślną opcję .NET Framework i wybierz pozycję Utwórz, aby utworzyć projekt.
W programie Visual Studio otwórz pozycję Narzędzia> Menedżer >pakietów NuGetZarządzaj pakietami NuGet dla rozwiązania. Wybierz kartę Przeglądaj.
Wyszukaj i wybierz pozycję Microsoft.Azure.Devices.Client, a następnie wybierz pozycję Zainstaluj.

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

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using System.Threading.Tasks;
using Newtonsoft.Json;

Dodaj następujące pola do klasy Program: Zamień wartość symbolu zastępczego na parametry połączenia modułu.

private const string ModuleConnectionString = "<Your module connection string>";
private static ModuleClient Client = null;
static void ConnectionStatusChangeHandler(ConnectionStatus status, 
  ConnectionStatusChangeReason reason)
{
    Console.WriteLine("Connection Status Changed to {0}; the reason is {1}", 
      status, reason);
}

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

private static async Task OnDesiredPropertyChanged(TwinCollection desiredProperties, 
  object userContext)
    {
        Console.WriteLine("desired property change:");
        Console.WriteLine(JsonConvert.SerializeObject(desiredProperties));
        Console.WriteLine("Sending current time as reported property");
        TwinCollection reportedProperties = new TwinCollection
        {
            ["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.Now
        };

        await Client.UpdateReportedPropertiesAsync(reportedProperties).ConfigureAwait(false);
    }

Dodaj następujące wiersze do metody Main :

static void Main(string[] args)
{
    Microsoft.Azure.Devices.Client.TransportType transport = 
      Microsoft.Azure.Devices.Client.TransportType.Amqp;

    try
    {
        Client = 
          ModuleClient.CreateFromConnectionString(ModuleConnectionString, transport);
        Client.SetConnectionStatusChangesHandler(ConnectionStatusChangeHandler);
        Client.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChanged, null).Wait();

        Console.WriteLine("Retrieving twin");
        var twinTask = Client.GetTwinAsync();
        twinTask.Wait();
        var twin = twinTask.Result;
        Console.WriteLine(JsonConvert.SerializeObject(twin.Properties)); 

        Console.WriteLine("Sending app start time as reported property");
        TwinCollection reportedProperties = new TwinCollection();
        reportedProperties["DateTimeLastAppLaunch"] = DateTime.Now;

        Client.UpdateReportedPropertiesAsync(reportedProperties);
    }
    catch (AggregateException ex)
    {
        Console.WriteLine("Error in sample: {0}", ex);
    }

    Console.WriteLine("Waiting for Events.  Press enter to exit...");
    Console.ReadLine();
    Client.CloseAsync().Wait();
}

Teraz wiesz, jak pobrać bliźniaczą reprezentację modułu i zaktualizować zgłaszane właściwości za pomocą protokołu AMQP.

Opcjonalnie możesz dodać te instrukcje do metody Main, aby wysłać zdarzenie do IoT Hub z modułu. Umieść te wiersze pod blokiem try catch .

Byte[] bytes = new Byte[2];
bytes[0] = 0;
bytes[1] = 1;
var sendEventsTask = Client.SendEventAsync(new Message(bytes));
sendEventsTask.Wait();
Console.WriteLine("Event sent to IoT Hub.");

Uruchamianie aplikacji

Teraz możesz uruchamiać aplikacje.

W programie Visual Studio w Eksplorator rozwiązań kliknij rozwiązanie prawym przyciskiem myszy, a następnie wybierz polecenie Ustaw projekty startowe.
W obszarze Wspólne właściwości wybierz pozycję Projekt startowy.
Wybierz pozycję Wiele projektów startowych, a następnie wybierz pozycję Uruchom jako akcję dla aplikacji, a następnie kliknij przycisk OK , aby zaakceptować zmiany.
Naciśnij klawisz F5 , aby uruchomić aplikacje.

Następne kroki

Aby kontynuować wprowadzenie do usługi IoT Hub i zapoznać się z innymi scenariuszami IoT, zobacz:

Wprowadzenie do zarządzania urządzeniami
Getting started with IoT Edge (Wprowadzenie do usługi IoT Edge)

Share via

Wprowadzenie do tożsamości modułu IoT Hub i bliźniaczej reprezentacji modułu (.NET)

Wymagania wstępne

Uwierzytelnianie modułu

Pobieranie parametrów połączenia centrum IoT

Tworzenie tożsamości modułu

Aktualizowanie bliźniaczej reprezentacji modułu przy użyciu zestawu SDK urządzenia platformy .NET

Uruchamianie aplikacji

Następne kroki

Dodatkowe zasoby