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

Artykuł
10/01/2024

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 tożsamość urządzenia i bliźniacze reprezentacje urządzenia w usłudze Azure IoT Hub umożliwiają aplikacji zaplecza skonfigurowanie urządzenia i zapewnienie widoczności warunków urządzenia, tożsamość modułu i bliźniacze reprezentacje 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 oprogramowania układowego, 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 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.

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 klientów urządzenia i 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 kompilowania aplikacji urządzeń i zaplecza.

Wymagania wstępne

Visual Studio.
Centrum IoT w ramach subskrypcji platformy Azure. Jeśli nie masz jeszcze centrum, możesz wykonać kroki opisane w temacie Tworzenie centrum IoT Hub.

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 parametry 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 usługi IoT Hub dla zasad registryReadWrite, 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.
Z listy zasad wybierz zasady registryReadWrite .
Skopiuj parametry połączenia podstawową 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.

Ważne

Ten artykuł zawiera kroki nawiązywania połączenia z usługą przy użyciu sygnatury dostępu współdzielonego. Ta metoda uwierzytelniania jest wygodna do testowania i oceny, ale uwierzytelnianie w usłudze przy użyciu identyfikatora Entra firmy Microsoft lub tożsamości zarządzanych jest bardziej bezpieczne. Aby dowiedzieć się więcej, zobacz Security best practices Cloud security (Najlepsze rozwiązania > dotyczące zabezpieczeń w chmurze).

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. Aby uzyskać więcej informacji, zobacz sekcję Identity Registry (Rejestr tożsamości) w przewodniku dewelopera usługi IoT Hub.

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 usługi 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.
Pozostaw domyślną opcję .NET Framework i wybierz pozycję Utwórz , aby utworzyć projekt.
W programie Visual Studio otwórz pozycję Narzędzia>NuGet Menedżer pakietów> Zarządzanie pakietami NuGet dla rozwiązania. Wybierz kartę Przeglądaj.
Wyszukaj ciąg Microsoft.Azure.Devices. Wybierz ją, a następnie wybierz pozycję Zainstaluj.

Dodaj następujące instrukcje using 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 aplikacji symulowanego modułu w celu nawiązania połączenia 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 usługi 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 się do chmury z urządzenia symulowanego. 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.

Ważne

Ten artykuł zawiera kroki łączenia urządzenia przy użyciu sygnatury dostępu współdzielonego, nazywanej również uwierzytelnianiem klucza symetrycznego. Ta metoda uwierzytelniania jest wygodna do testowania i oceny, ale uwierzytelnianie urządzenia przy użyciu certyfikatów X.509 jest bardziej bezpieczne. Aby dowiedzieć się więcej, zobacz Zabezpieczenia najlepszych rozwiązań > zabezpieczeń Zabezpieczenia zabezpieczeń Zabezpieczenia zabezpieczeń.

W programie Visual Studio dodaj nowy projekt do rozwiązania, wybierając pozycję Plik>nowy>projekt. W obszarze Tworzenie nowego projektu wybierz pozycję Aplikacja konsolowa (.NET Framework) i wybierz przycisk Dalej.
W obszarze Konfigurowanie nowego projektu nadaj projektowi nazwę UpdateModuleTwinReportedProperties, a następnie wybierz pozycję Dalej.
Pozostaw domyślną opcję .NET Framework i wybierz pozycję Utwórz , aby utworzyć projekt.
W programie Visual Studio otwórz pozycję Narzędzia>NuGet Menedżer pakietów> Zarządzanie 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 instrukcje using 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źniacze reprezentacje 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 usługi IoT Hub z modułu. Umieść te wiersze poniżej try catch bloku.

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 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)

Udostępnij za pośrednictwem

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

Wymagania wstępne

Uwierzytelnianie modułu

Pobieranie parametry 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

Opinia

Dodatkowe zasoby