Udostępnij za pośrednictwem

Wprowadzenie do tożsamości modułów usługi IoT Hub i bliźniaczych reprezentacji tożsamości modułu

  • Artykuł

Tożsamości modułów i bliźniacze reprezentacje tożsamości modułu są podobne do tożsamości urządzeń usługi Azure IoT Hub i bliźniaczych reprezentacji urządzeń, ale zapewniają bardziej szczegółowość. Chociaż tożsamości urządzeń i bliźniacze reprezentacje urządzeń usługi Azure IoT Hub umożliwiają aplikacji zaplecza skonfigurowanie urządzenia i zapewnienie widoczności warunków urządzenia, tożsamość modułu i 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 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. Aby uzyskać więcej informacji, zobacz Omówienie bliźniaczych reprezentacji modułów usługi Azure IoT Hub.

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.

W tym artykule przedstawiono sposób tworzenia dwóch typów aplikacji:

  • Aplikacje urządzeń, które wyświetlają i aktualizują zgłaszane właściwości bliźniaczej reprezentacji tożsamości modułu i obsługują żądania aktualizacji żądanych właściwości.
  • Aplikacje usługi, które mogą odczytywać i ustawiać żądane właściwości tożsamości modułu.

Uwaga

Ten artykuł ma na celu uzupełnienie przykładów zestawów SDK usługi Azure IoT, do których odwołuje się ten artykuł. Za pomocą narzędzi zestawu SDK można tworzyć zarówno aplikacje urządzeń, jak i zaplecza.

Wymagania wstępne

  • Centrum IoT Hub.

  • Urządzenie centrum IoT Hub

  • Tożsamość modułu urządzenia usługi IoT Hub

  • Jeśli aplikacja używa protokołu MQTT, upewnij się, że port 8883 jest otwarty w zaporze. Protokół MQTT 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 Nawiązywanie połączenia z usługą IoT Hub (MQTT).

  • Wymaga programu Visual Studio

Omówienie

W tym artykule opisano sposób używania zestawu AZURE IoT SDK dla platformy .NET do tworzenia kodu aplikacji usługi urządzenia i zaplecza dla bliźniaczych reprezentacji tożsamości modułu.

Tworzenie aplikacji urządzenia

W tej sekcji opisano sposób używania kodu aplikacji urządzenia do wykonywania następujących czynności:

  • Pobieranie bliźniaczej reprezentacji tożsamości modułu i badanie zgłoszonych właściwości
  • Aktualizowanie właściwości bliźniaczej reprezentacji tożsamości zgłaszanego modułu
  • Tworzenie procedury obsługi wywołania zwrotnego żądanej właściwości modułu

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ń.

Wymagany pakiet NuGet urządzenia

Aplikacje klienckie urządzeń napisane w języku C# wymagają pakietu NuGet Microsoft.Azure.Devices.Client .

Dodaj te using instrukcje, aby używać biblioteki urządzeń.

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

Nawiązywanie połączenia z urządzeniem

Klasa ModuleClient uwidacznia wszystkie metody wymagane do interakcji z bliźniaczymi reprezentacjami tożsamości modułu z urządzenia.

Połącz się z urządzeniem przy użyciu metody CreateFromConnectionString z tożsamością modułu parametry połączenia.

Wywoływanie CreateFromConnectionString bez parametru transportu łączy się przy użyciu domyślnego transportu PROTOKOŁU AMQP.

W tym przykładzie nawiąż połączenie z urządzeniem przy użyciu domyślnego transportu protokołu AMQP.

static string ModuleConnectionString = "{Device module identity connection string}";
private static ModuleClient _moduleClient = null;

_moduleClient = ModuleClient.CreateFromConnectionString(ModuleConnectionString, null);

Uwaga

Język C#/.NET nie obsługuje połączenia aplikacji urządzenia z bliźniaczą reprezentacją tożsamości modułu usługi IoT Hub przy użyciu certyfikatu.

Pobieranie bliźniaczej reprezentacji tożsamości modułu i badanie właściwości

Wywołaj metodę GetTwinAsync , aby pobrać bieżące właściwości bliźniaczej reprezentacji modułu do obiektu bliźniaczej reprezentacji .

Ten przykład pobiera i wyświetla właściwości bliźniaczej reprezentacji tożsamości modułu w formacie JSON.

Console.WriteLine("Retrieving twin...");
Twin twin = await _moduleClient.GetTwinAsync();
Console.WriteLine("\tModule identity twin value received:");
Console.WriteLine(JsonConvert.SerializeObject(twin.Properties));

Aktualizowanie zgłoszonych właściwości bliźniaczej reprezentacji tożsamości modułu

Aby zaktualizować zgłoszoną właściwość bliźniaczej reprezentacji:

  1. Tworzenie obiektu TwinCollection dla zgłaszanej aktualizacji właściwości
  2. Aktualizowanie co najmniej jednej zgłoszonej właściwości w TwinCollection obiekcie
  3. Użyj metody UpdateReportedPropertiesAsync , aby wypchnąć zmiany zgłaszanej właściwości do usługi IoT Hub

Na przykład:

try
{
  Console.WriteLine("Sending sample start time as reported property");
  TwinCollection reportedProperties = new TwinCollection();
  reportedProperties["DateTimeLastAppLaunch"] = DateTime.UtcNow;
  await _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}
catch (Exception ex)
{
   Console.WriteLine();
   Console.WriteLine("Error in sample: {0}", ex.Message);
}

Tworzenie procedury obsługi wywołania zwrotnego żądanej aktualizacji właściwości

Przekaż nazwę metody procedury obsługi wywołania zwrotnego do polecenia SetDesiredPropertyUpdateCallbackAsync , aby utworzyć żądaną procedurę obsługi wywołania zwrotnego aktualizacji właściwości, która jest wykonywana po zmianie żądanej właściwości w bliźniaczej reprezentacji tożsamości modułu.

Na przykład to wywołanie konfiguruje system, aby powiadomić metodę o nazwie OnDesiredPropertyChangedAsync za każdym razem, gdy zmieniono żądaną właściwość modułu.

await _moduleClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

Właściwości bliźniaczej reprezentacji tożsamości modułu są przekazywane do metody wywołania zwrotnego jako twinCollection i można je zbadać jako KeyValuePair struktury.

Ten przykład odbiera żądane aktualizacje właściwości jako TwinCollectionelement , a następnie przechodzi w pętli i drukuje KeyValuePair aktualizacje kolekcji. Po pętli w KeyValuePair kolekcji kod wywołuje UpdateReportedPropertiesAsync polecenie w celu zaktualizowania zgłaszanej DateTimeLastDesiredPropertyChangeReceived właściwości, aby zachować aktualność czasu ostatniej aktualizacji.

private async Task OnDesiredPropertyChangedAsync(TwinCollection desiredProperties, object userContext)
{
   var reportedProperties = new TwinCollection();

   Console.WriteLine("\tDesired properties requested:");
   Console.WriteLine($"\t{desiredProperties.ToJson()}");

   // For the purpose of this sample, we'll blindly accept all twin property write requests.
   foreach (KeyValuePair<string, object> desiredProperty in desiredProperties)
   {
         Console.WriteLine($"Setting {desiredProperty.Key} to {desiredProperty.Value}.");
         reportedProperties[desiredProperty.Key] = desiredProperty.Value;
   }

   Console.WriteLine("\tAlso setting current time as reported property");
   reportedProperties["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.UtcNow;

   await _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}

Przykładowy moduł ZESTAWU SDK

Zestaw SDK usługi Azure IoT dla platformy .NET udostępnia działające przykłady aplikacji urządzeń, które obsługują zadania bliźniaczej reprezentacji tożsamości modułu. Aby uzyskać więcej informacji, zobacz:

Tworzenie aplikacji zaplecza

W tej sekcji opisano sposób odczytywania i aktualizowania pól tożsamości modułu.

Klasa RegistryManager uwidacznia wszystkie metody wymagane do utworzenia aplikacji zaplecza w celu interakcji z bliźniaczymi reprezentacjami tożsamości modułu z usługi.

Wymagany pakiet NuGet usługi

Aplikacje usługi zaplecza wymagają pakietu NuGet Microsoft.Azure.Devices .

Dodaj te using instrukcje, aby używać biblioteki usług.

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;

Łączenie z usługą IoT Hub

Usługę zaplecza można połączyć z usługą IoT Hub przy użyciu następujących metod:

  • Zasady dostępu współdzielonego
  • Microsoft Entra

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

Nawiązywanie połączenia przy użyciu zasad dostępu współdzielonego

Połącz aplikację zaplecza z centrum IoT hub przy użyciu polecenia CreateFromConnectionString.

Metoda UpdateModuleAsync używana w tej sekcji wymaga uprawnienia zasad dostępu współdzielonego programu Service Connect w celu dodania żądanych właściwości do modułu. Jako parametr CreateFromConnectionStringparametru podaj zasady dostępu współdzielonego parametry połączenia, które obejmują uprawnienia programu Service Connect. Aby uzyskać więcej informacji na temat zasad dostępu współdzielonego, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu sygnatur dostępu współdzielonego.

Na przykład:

static RegistryManager registryManager;
static string connectionString = "{IoT hub shared access policy connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

Nawiązywanie połączenia przy użyciu usługi Microsoft Entra

Aplikacja zaplecza korzystająca z usługi Microsoft Entra musi pomyślnie uwierzytelnić się i uzyskać poświadczenia tokenu zabezpieczającego przed nawiązaniem połączenia z usługą IoT Hub. Ten token jest przekazywany do metody połączenia usługi IoT Hub. Aby uzyskać ogólne informacje na temat konfigurowania i używania usługi Microsoft Entra dla usługi IoT Hub, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu identyfikatora Microsoft Entra.

Konfigurowanie aplikacji Microsoft Entra

Musisz skonfigurować aplikację Firmy Microsoft Entra skonfigurowaną dla preferowanych poświadczeń uwierzytelniania. Aplikacja zawiera parametry, takie jak klucz tajny klienta, który jest używany przez aplikację zaplecza do uwierzytelniania. Dostępne konfiguracje uwierzytelniania aplikacji to:

  • Klucz tajny klienta
  • Certyfikat
  • Poświadczenia tożsamości federacyjnej

Aplikacje Firmy Microsoft Entra mogą wymagać określonych uprawnień roli w zależności od wykonywanych operacji. Na przykład współautor bliźniaczej reprezentacji usługi IoT Hub jest wymagany do włączenia dostępu do odczytu i zapisu na urządzeniu usługi IoT Hub i bliźniaczych reprezentacjach modułów. Aby uzyskać więcej informacji, zobacz Zarządzanie dostępem do usługi IoT Hub przy użyciu przypisania roli RBAC platformy Azure.

Aby uzyskać więcej informacji na temat konfigurowania aplikacji Microsoft Entra, zobacz Szybki start: rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft.

Uwierzytelnianie przy użyciu wartości DefaultAzureCredential

Najprostszym sposobem użycia usługi Microsoft Entra do uwierzytelniania aplikacji zaplecza jest użycie wartości DefaultAzureCredential, ale zaleca się użycie innej metody w środowisku produkcyjnym, w tym określonej TokenCredential lub pared-down ChainedTokenCredential. Dla uproszczenia w tej sekcji opisano uwierzytelnianie przy użyciu i DefaultAzureCredential klucz tajny klienta. Aby uzyskać więcej informacji na temat zalet i wad korzystania z usługi , zobacz Wskazówki dotyczące użycia DefaultAzureCredentialdla elementu DefaultAzureCredential.

DefaultAzureCredential obsługuje różne mechanizmy uwierzytelniania i określa odpowiedni typ poświadczeń na podstawie środowiska, w których jest wykonywany. Próbuje użyć wielu typów poświadczeń w kolejności, dopóki nie znajdzie działającego poświadczenia.

Firma Microsoft Entra wymaga tych pakietów NuGet i odpowiednich using instrukcji:

  • Azure.Core
  • Azure.Identity
using Azure.Core;
using Azure.Identity;

W tym przykładzie klucz tajny klienta rejestracji aplikacji Firmy Microsoft, identyfikator klienta i identyfikator dzierżawy są dodawane do zmiennych środowiskowych. Te zmienne środowiskowe są używane przez DefaultAzureCredential program do uwierzytelniania aplikacji. Wynikiem pomyślnego uwierzytelnienia firmy Microsoft Entra jest poświadczenie tokenu zabezpieczającego przekazywane do metody połączenia usługi IoT Hub.

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

Wynikowy tokenCredential można następnie przekazać do metody łączenia z usługą IoT Hub dla dowolnego klienta zestawu SDK, który akceptuje poświadczenia firmy Microsoft Entra:

W tym przykładzie TokenCredential parametr jest przekazywany do , aby ServiceClient.Create utworzyć obiekt połączenia ServiceClient .

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

W tym przykładzie TokenCredential parametr jest przekazywany do RegistryManager.Create , aby utworzyć obiekt RegistryManager .

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);
Przykład kodu

Aby zapoznać się z roboczym przykładem uwierzytelniania usługi Entra firmy Microsoft, zobacz Przykład uwierzytelniania opartego na rolach.

Odczytywanie i aktualizowanie pól tożsamości modułu

Wywołaj metodę GetModuleAsync, aby pobrać bieżące pola bliźniaczej reprezentacji modułu do obiektu modułu.

Klasa Module obejmuje properties sekcje bliźniaczej reprezentacji tożsamości modułu. Użyj właściwości klasy Moduł, aby wyświetlić i zaktualizować pola bliźniaczej reprezentacji modułu. Właściwości obiektu można użyć Module do zaktualizowania wielu pól przed zapisaniem aktualizacji na urządzeniu przy użyciu polecenia UpdateModuleAsync.

Po zaktualizowaniu pola bliźniaczej reprezentacji tożsamości modułu wywołaj metodę UpdateModuleAsync , aby zapisać Module aktualizacje pól obiektów z powrotem na urządzeniu. Użyj funkcji try i catch logiki powiązanej z procedurą obsługi błędów, aby przechwycić błędy niepoprawnie sformatowanych poprawek z programu UpdateModuleAsync.

W tym przykładzie moduł jest pobierany do Module obiektu, aktualizuje module LastActivityTime właściwość, a następnie aktualizuje moduł w usłudze IoT Hub przy użyciu polecenia UpdateModuleAsync.

// Retrieve the module
var module = await registryManager.GetModuleAsync("myDeviceId","myModuleId");

// Update the module object
module.LastActivityTime = DateTime.Now;

// Apply the patch to update the device twin tags section
try
{
   await registryManager.UpdateModuleAsync(module);
}
catch (Exception e)
{
   console.WriteLine("Module update failed.", e.Message);
}

Inny interfejs API modułu

Przykład usługi SDK

Zestaw SDK usługi Azure IoT dla platformy .NET udostępnia działającą przykładową aplikację usługi, która obsługuje zadania bliźniaczej reprezentacji tożsamości modułu. Aby uzyskać więcej informacji, zobacz Registry Manager E2E Tests (Testy E2E menedżera rejestru).

  • Zalecane jest użycie języka Python w wersji 3.7 lub nowszej . Upewnij się, że używasz 32-bitowej lub 64-bitowej instalacji zgodnie z wymaganiami konfiguracji. Po wyświetleniu monitu podczas instalacji upewnij się, że język Python został dodany do zmiennej środowiskowej specyficznej dla platformy.

Omówienie

W tym artykule opisano sposób używania zestawu SDK usługi Azure IoT dla języka Python do tworzenia kodu aplikacji usługi urządzenia i zaplecza dla bliźniaczych reprezentacji tożsamości modułu.

Instalowanie pakietów

Aby tworzyć aplikacje urządzeń, należy zainstalować bibliotekę azure-iot-device .

pip install azure-iot-device

Aby tworzyć aplikacje usługi zaplecza, należy zainstalować bibliotekę azure-iot-hub .

pip install azure-iot-hub

Biblioteka msrest służy do przechwytywania wyjątków HTTPOperationError.

pip install msrest

Tworzenie aplikacji urządzenia

W tej sekcji opisano sposób używania kodu aplikacji urządzenia do wykonywania następujących czynności:

  • Pobieranie bliźniaczej reprezentacji tożsamości modułu i badanie zgłoszonych właściwości
  • Aktualizowanie zgłoszonych właściwości bliźniaczej reprezentacji tożsamości modułu
  • Tworzenie procedury obsługi wywołania zwrotnego żądanej właściwości bliźniaczej reprezentacji tożsamości modułu

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ń.

Instrukcje importu

Dodaj tę import instrukcję, aby użyć biblioteki urządzeń.

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

Nawiązywanie połączenia z urządzeniem

Klasa IoTHubModuleClient zawiera metody, których można użyć do pracy z bliźniaczymi reprezentacjami tożsamości modułu.

Aby połączyć aplikację z urządzeniem:

  1. Wywołaj create_from_connection_string, aby dodać parametry połączenia tożsamości modułu
  2. Wywołanie połączenia w celu połączenia klienta urządzenia z centrum Azure IoT Hub
# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

# substitute the device connection string in conn_str
# and add it to the IoTHubDeviceClient object
conn_str = "{Device module identity connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

# connect the application to the device
await device_client.connect()

Uwaga

Język Python nie obsługuje połączenia aplikacji urządzenia z bliźniaczą reprezentacją tożsamości modułu usługi IoT Hub przy użyciu certyfikatu.

Pobieranie bliźniaczej reprezentacji tożsamości modułu i badanie właściwości

Wywołaj get_twin w celu pobrania bliźniaczej reprezentacji tożsamości modułu z usługi Azure IoT Hub. Informacje o bliźniaczej reprezentacji są umieszczane w zmiennej, którą można zbadać.

W tym przykładzie pobrano bliźniacza reprezentację urządzenia i użyto print polecenia w celu wyświetlenia bliźniaczej reprezentacji urządzenia w formacie JSON.

# get the twin
twin = await device_client.get_twin()
print("Twin document:")
print("{}".format(twin))

Aktualizowanie zgłoszonych właściwości bliźniaczej reprezentacji tożsamości modułu

Możesz zastosować poprawkę, aby zaktualizować zgłaszane właściwości bliźniaczej reprezentacji tożsamości modułu w formacie JSON.

Aby zastosować poprawkę w celu zaktualizowania zgłoszonych właściwości:

  1. Przypisz poprawkę JSON zgłaszanej właściwości do zmiennej.
  2. Wywołaj patch_twin_reported_properties , aby zastosować poprawkę JSON do zgłoszonych właściwości.

Na przykład:

# create the reported properties patch
reported_properties = {"temperature": random.randint(320, 800) / 10}
print("Setting reported temperature to {}".format(reported_properties["temperature"]))
# update the reported properties and wait for the result
await device_client.patch_twin_reported_properties(reported_properties)

Tworzenie procedury obsługi wywołania zwrotnego żądanej właściwości bliźniaczej reprezentacji tożsamości modułu

Wywołaj on_twin_desired_properties_patch_received , aby utworzyć funkcję obsługi lub coroutine wywoływaną po odebraniu poprawki żądanej właściwości bliźniaczej reprezentacji modułu. Procedura obsługi przyjmuje jeden argument, który jest poprawką bliźniaczej reprezentacji w postaci obiektu słownika JSON.

W tym przykładzie skonfigurowano żądaną procedurę obsługi poprawek właściwości o nazwie twin_patch_handler.

Na przykład:

try:
    # Set handlers on the client
    device_client.on_twin_desired_properties_patch_received = twin_patch_handler
except:
    # Clean up in the event of failure
    client.shutdown()

Odbiera twin_patch_handler i drukuje aktualizacje żądanej właściwości w formacie JSON.

    # Define behavior for receiving twin desired property patches
    def twin_patch_handler(twin_patch):
        print("Twin patch received:")
        print(twin_patch)

Przykłady urządzeń z zestawem SDK

Zestaw SDK usługi Azure IoT dla języka Python udostępnia działającą próbkę aplikacji urządzeń, które obsługują zadania bliźniaczej reprezentacji tożsamości modułu:

  • get_twin — połącz się z urządzeniem i pobierz informacje o bliźniaczej reprezentacji.
  • update_twin_reported_properties — aktualizowanie zgłoszonych właściwości bliźniaczej reprezentacji bliźniaczej.
  • receive_twin_desired_properties — odbieranie i aktualizowanie żądanych właściwości.

Tworzenie aplikacji zaplecza

W tej sekcji opisano sposób tworzenia aplikacji zaplecza w celu pobierania i aktualizowania żądanych właściwości bliźniaczej reprezentacji tożsamości modułu.

Klasa IoTHubRegistryManager uwidacznia wszystkie metody wymagane do utworzenia aplikacji zaplecza w celu interakcji z bliźniaczymi reprezentacjami tożsamości modułu z usługi.

Instrukcje importowania usługi

Dodaj tę import instrukcję, aby użyć biblioteki usług.

import sys
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties, QuerySpecification, QueryResult

Nawiązywanie połączenia z centrum IoT

Usługę zaplecza można połączyć z usługą IoT Hub przy użyciu następujących metod:

  • Zasady dostępu współdzielonego
  • Microsoft Entra

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

Nawiązywanie połączenia przy użyciu zasad dostępu współdzielonego

Nawiąż połączenie z centrum IoT Przy użyciu from_connection_string.

Metoda update_module_twin używana w tej sekcji wymaga uprawnienia zasad dostępu współdzielonego programu Service Connect w celu dodania żądanych właściwości do modułu. Jako parametr from_connection_stringparametru podaj zasady dostępu współdzielonego parametry połączenia, które obejmują uprawnienia programu Service Connect. Aby uzyskać więcej informacji na temat zasad dostępu współdzielonego, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu sygnatur dostępu współdzielonego.

Na przykład:

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub shared access policy connection string}"
iothub_registry_manager = IoTHubRegistryManager.from_connection_string(IOTHUB_CONNECTION_STRING)

Nawiązywanie połączenia przy użyciu usługi Microsoft Entra

Aplikacja zaplecza korzystająca z usługi Microsoft Entra musi pomyślnie uwierzytelnić się i uzyskać poświadczenia tokenu zabezpieczającego przed nawiązaniem połączenia z usługą IoT Hub. Ten token jest przekazywany do metody połączenia usługi IoT Hub. Aby uzyskać ogólne informacje na temat konfigurowania i używania usługi Microsoft Entra dla usługi IoT Hub, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu identyfikatora Microsoft Entra.

Aby zapoznać się z omówieniem uwierzytelniania zestawu PYTHON SDK, zobacz Uwierzytelnianie aplikacji języka Python w usługach platformy Azure przy użyciu zestawu Azure SDK dla języka Python

Konfigurowanie aplikacji Microsoft Entra

Musisz skonfigurować aplikację Firmy Microsoft Entra skonfigurowaną dla preferowanych poświadczeń uwierzytelniania. Aplikacja zawiera parametry, takie jak klucz tajny klienta, który jest używany przez aplikację zaplecza do uwierzytelniania. Dostępne konfiguracje uwierzytelniania aplikacji to:

  • Klucz tajny klienta
  • Certyfikat
  • Poświadczenia tożsamości federacyjnej

Aplikacje Firmy Microsoft Entra mogą wymagać określonych uprawnień roli w zależności od wykonywanych operacji. Na przykład współautor bliźniaczej reprezentacji usługi IoT Hub jest wymagany do włączenia dostępu do odczytu i zapisu na urządzeniu usługi IoT Hub i bliźniaczych reprezentacjach modułów. Aby uzyskać więcej informacji, zobacz Zarządzanie dostępem do usługi IoT Hub przy użyciu przypisania roli RBAC platformy Azure.

Aby uzyskać więcej informacji na temat konfigurowania aplikacji Microsoft Entra, zobacz Szybki start: rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft.

Uwierzytelnianie przy użyciu wartości DefaultAzureCredential

Najprostszym sposobem użycia usługi Microsoft Entra do uwierzytelniania aplikacji zaplecza jest użycie wartości DefaultAzureCredential, ale zaleca się użycie innej metody w środowisku produkcyjnym, w tym określonej TokenCredential lub pared-down ChainedTokenCredential. Dla uproszczenia w tej sekcji opisano uwierzytelnianie przy użyciu i DefaultAzureCredential klucz tajny klienta. Aby uzyskać więcej informacji na temat zalet i wad korzystania z programu DefaultAzureCredential, zobacz Łańcuchy poświadczeń w bibliotece klienta tożsamości platformy Azure dla języka Python.

Ustawienie domyślneAzureCredential obsługuje różne mechanizmy uwierzytelniania i określa odpowiedni typ poświadczeń na podstawie środowiska, w których jest wykonywany. Próbuje użyć wielu typów poświadczeń w kolejności, dopóki nie znajdzie działającego poświadczenia.

Firma Microsoft Entra wymaga tego pakietu importu i odpowiedniej import instrukcji:

pip install azure-identity

from azure.identity import DefaultAzureCredential

W tym przykładzie klucz tajny klienta rejestracji aplikacji Firmy Microsoft, identyfikator klienta i identyfikator dzierżawy zostały dodane do zmiennych środowiskowych. Te zmienne środowiskowe są używane przez DefaultAzureCredential program do uwierzytelniania aplikacji. Wynikiem pomyślnego uwierzytelnienia firmy Microsoft Entra jest poświadczenie tokenu zabezpieczającego przekazywane do metody połączenia usługi IoT Hub.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

Wynikowy token AccessToken można następnie przekazać w celu from_token_credential nawiązania połączenia z usługą IoT Hub dla dowolnego klienta zestawu SDK, który akceptuje poświadczenia firmy Microsoft Entra:

from_token_credential wymaga dwóch parametrów:

  • Adres URL usługi platformy Azure — adres URL usługi platformy Azure powinien być w formacie {Your Entra domain URL}.azure-devices.net bez prefiksu https:// . Na przykład MyAzureDomain.azure-devices.net.
  • Token poświadczeń platformy Azure

W tym przykładzie poświadczenia platformy Azure są uzyskiwane przy użyciu polecenia DefaultAzureCredential. Adres URL i poświadczenia usługi platformy Azure są następnie dostarczane w celu IoTHubRegistryManager.from_token_credential utworzenia połączenia z usługą IoT Hub.

import sys
import os

from azure.identity import DefaultAzureCredential
from azure.iot.hub import IoTHubRegistryManager

# Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

# Set environment variables
os.environ['AZURE_CLIENT_SECRET'] = clientSecretValue
os.environ['AZURE_CLIENT_ID'] = clientID
os.environ['AZURE_TENANT_ID'] = tenantID

# Acquire a credential object
credential = DefaultAzureCredential()

# Use Entra to authorize IoT Hub service
print("Connecting to IoTHubRegistryManager...")
iothub_registry_manager = IoTHubRegistryManager.from_token_credential(
url="MyAzureDomain.azure-devices.net",
token_credential=credential)
Przykłady kodu

Aby zapoznać się z roboczymi przykładami uwierzytelniania usługi Entra firmy Microsoft, zobacz Biblioteka Microsoft Authentication Library (MSAL) dla języka Python.

Pobieranie i aktualizowanie żądanych właściwości bliźniaczej reprezentacji tożsamości modułu

Żądane właściwości można zaktualizować z poziomu aplikacji zaplecza przy użyciu update_module_twin.

Aby pobrać i zaktualizować żądane właściwości bliźniaczej reprezentacji tożsamości modułu:

  1. Wywołaj get_module_twin , aby pobrać bieżącą wersję bliźniaczej reprezentacji tożsamości modułu.
  2. Użyj klasy bliźniaczej, aby dodać żądane właściwości w formacie JSON.
  3. Wywołaj metodę update_module_twin , aby zastosować poprawkę do bliźniaczej reprezentacji urządzenia. Można również użyć replace_module_twin , aby zastąpić żądane właściwości i tagi bliźniaczej reprezentacji tożsamości modułu.

W tym przykładzie żądana właściwość zostanie zaktualizowana telemetryInterval do 122elementu .

try:
    module_twin = iothub_registry_manager.get_module_twin(DEVICE_ID, MODULE_ID)
    print ( "" )
    print ( "Module identity twin properties before update:" )
    print ( "{0}".format(module_twin.properties) )

    # Update twin
    twin_patch = Twin()
    twin_patch.properties = TwinProperties(desired={"telemetryInterval": 122})
    updated_module_twin = iothub_registry_manager.update_module_twin(
        DEVICE_ID, MODULE_ID, twin_patch, module_twin.etag
    )
    print ( "" )
    print ( "Module identity twin properties after update     :" )
    print ( "{0}".format(updated_module_twin.properties) )

except Exception as ex:
    print ( "Unexpected error {0}".format(ex) )
except KeyboardInterrupt:
    print ( "IoTHubRegistryManager sample stopped" )

Przykład usługi SDK

Zestaw SDK usługi Azure IoT dla języka Python udostępnia działający przykład aplikacji usługi, która obsługuje zadania bliźniaczej reprezentacji modułu tożsamości urządzenia. Aby uzyskać więcej informacji, zobacz Test IoTHub Registry Manager (Testowanie Menedżera rejestru usługi IoTHub).

  • Wymaga Node.js w wersji 10.0.x lub nowszej

Omówienie

W tym artykule opisano, jak używać zestawu SDK usługi Azure IoT dla Node.js do tworzenia kodu aplikacji usługi urządzenia i zaplecza dla bliźniaczych reprezentacji tożsamości modułu.

Tworzenie aplikacji urządzenia

W tej sekcji opisano sposób użycia pakietu azure-iot-device w zestawie SDK usługi Azure IoT dla Node.js w celu utworzenia aplikacji urządzenia w celu:

  • Pobieranie bliźniaczej reprezentacji tożsamości modułu i badanie zgłoszonych właściwości
  • Aktualizowanie właściwości zgłaszanej reprezentacji bliźniaczej tożsamości modułu
  • Otrzymuj powiadomienie o zmianach żądanej właściwości bliźniaczej reprezentacji tożsamości modułu

Pakiet azure-iot-device zawiera obiekty interfejsu z urządzeniami IoT. Klasa Bliźniacze obejmuje obiekty specyficzne dla bliźniaczej reprezentacji. W tej sekcji opisano Client kod klasy używany do odczytywania i zapisywania danych bliźniaczej reprezentacji modułu urządzenia.

Instalowanie pakietu ZESTAWU SDK

Uruchom to polecenie, aby zainstalować zestaw SDK urządzenia azure-iot-device na maszynie dewelopera:

npm install azure-iot-device --save

Łączenie urządzenia z usługą IoT Hub

Aplikacja urządzenia może uwierzytelniać się w usłudze IoT Hub przy użyciu następujących metod:

  • Klucz dostępu współdzielonego
  • Certyfikat X.509

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ń.

Uwierzytelnianie przy użyciu klucza dostępu współdzielonego

Wybieranie protokołu transportowego

Obiekt Client obsługuje następujące protokoły:

  • Amqp
  • Http — W przypadku korzystania z Httpusługi Client wystąpienie sprawdza komunikaty z usługi IoT Hub rzadko (co najmniej co 25 minut).
  • Mqtt
  • MqttWs
  • AmqpWs

Zainstaluj wymagane protokoły transportu na maszynie dewelopera.

Na przykład to polecenie instaluje Amqp protokół:

npm install azure-iot-device-amqp --save

Aby uzyskać więcej informacji na temat różnic między obsługą protokołów MQTT, AMQP i HTTPS, zobacz Wskazówki dotyczące komunikacji między chmurą i urządzeniem i Wybieranie protokołu komunikacyjnego urządzenia.

Tworzenie obiektu klienta

Client Utwórz obiekt przy użyciu zainstalowanego pakietu.

Na przykład:

const Client = require('azure-iot-device').Client;
Tworzenie obiektu protokołu

Utwórz Protocol obiekt przy użyciu zainstalowanego pakietu transportowego.

W tym przykładzie przypisywany jest protokół AMQP:

const Protocol = require('azure-iot-device-amqp').Amqp;
Dodawanie protokołu parametry połączenia urządzenia i transportu

Wywołaj metodę fromConnectionString, aby podać parametry połączenia urządzenia:

  • connStr — moduł tożsamości centrum IoT parametry połączenia.
  • transportCtor — protokół transportowy.

W tym przykładzie użyto Amqp protokołu transportu:

const deviceConnectionString = "{IoT hub identity module connection string}"
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);
Otwieranie połączenia z usługą IoT Hub

Użyj metody open, aby otworzyć połączenie między urządzeniem IoT i usługą IoT Hub.

Na przykład:

client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
})

Uwierzytelnianie przy użyciu certyfikatu X.509

Certyfikat X.509 jest dołączony do transportu połączeń device-to-IoT Hub.

Aby skonfigurować połączenie urządzenia z usługą IoT Hub przy użyciu certyfikatu X.509:

  1. Wywołaj metodę fromConnectionString, aby dodać parametry połączenia modułu urządzenia lub tożsamości oraz typ transportu do Client obiektu. Dodaj x509=true do parametry połączenia, aby wskazać, że certyfikat został dodany do elementu DeviceClientOptions. Na przykład:

    • Parametry połączenia urządzenia:

      HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true

    • Moduł tożsamości parametry połączenia:

      HostName=xxxxx.azure-devices.net;DeviceId=Device-1;ModuleId=Module-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true

  2. Skonfiguruj zmienną JSON ze szczegółami certyfikatu i przekaż ją do elementu DeviceClientOptions.

  3. Wywołaj metodę setOptions , aby dodać certyfikat I klucz X.509 (i opcjonalnie hasło) do transportu klienta.

  4. Wywołaj połączenie otwarte , aby otworzyć połączenie z urządzenia do usługi IoT Hub.

W tym przykładzie przedstawiono informacje o konfiguracji certyfikatu w zmiennej JSON. Konfiguracja clientOptions certyfikacji jest przekazywana do setOptions, a połączenie jest otwierane przy użyciu polecenia open.

const Client = require('azure-iot-device').Client;
const Protocol = require('azure-iot-device-mqtt').Mqtt;
// Connection string illustrated for demonstration only. Never hard-code the connection string in production. Instead use an environmental variable or other secure storage.
const connectionString = `HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true`
const client = Client.fromConnectionString(connectionString, Protocol);

var clientOptions = {
   cert: myX509Certificate,
   key: myX509Key,
   passphrase: passphrase,
   http: {
     receivePolicy: {
       interval: 10
     }
   }
 }

 client.setOptions(clientOptions);
 client.open(connectCallback);

Aby uzyskać więcej informacji na temat uwierzytelniania certyfikatów, zobacz:

Przykład kodu

Aby zapoznać się z roboczym przykładem uwierzytelniania certyfikatu X.509 urządzenia, zobacz Simple sample device X.509 (Proste przykładowe urządzenie X.509).

Pobieranie bliźniaczej reprezentacji tożsamości modułu i badanie zgłoszonych właściwości

Wywołaj metodę getTwin , aby pobrać informacje o reprezentacji bliźniaczej reprezentacji modułu do obiektu bliźniaczej reprezentacji .

Kod urządzenia może następnie uzyskać dostęp do właściwości bliźniaczej reprezentacji tożsamości modułu.

Na przykład:

// Retrieve the current module identity twin
client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

// Display the current properties
console.log('twin contents:');
console.log(twin.properties);

Aktualizowanie zgłoszonych właściwości bliźniaczej reprezentacji tożsamości modułu

Użyj aktualizacji , aby zaktualizować zgłaszane właściwości urządzenia. Dołącz poprawkę w formacie JSON jako pierwszy parametr i metodę wywołania zwrotnego stanu wykonywania funkcji jako drugi parametr metody .

W tym przykładzie w zmiennej patch jest przechowywana poprawka bliźniaczej reprezentacji tożsamości modułu w formacie JSON. Poprawka zawiera wartość aktualizacji bliźniaczej reprezentacji connectivity tożsamości modułu cellular. Procedura obsługi poprawek i błędów jest przekazywana update do metody . Jeśli wystąpi błąd, zostanie wyświetlony komunikat o błędzie konsoli.

// Create a patch to send to IoT Hub
var patch = {
  updateTime: new Date().toString(),
  firmwareVersion:'1.2.1',
  weather:{
    temperature: 72,
    humidity: 17
  }
};

// Apply the patch
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

Otrzymuj powiadomienie o zmianach żądanej właściwości bliźniaczej reprezentacji tożsamości modułu

Utwórz odbiornik zdarzeń aktualizacji żądanej właściwości bliźniaczej reprezentacji tożsamości modułu, który jest wykonywany po zmianie żądanej właściwości, przekazując nazwę metody obsługi wywołania zwrotnego na twin.on.

Odbiornik zdarzeń żądanej właściwości może mieć następujące formy:

  • Odbieranie wszystkich poprawek za pomocą pojedynczej procedury obsługi zdarzeń
  • Odbieranie zdarzenia, jeśli cokolwiek się zmienia w ramach grupowania właściwości
  • Odbieranie zdarzenia dla zmiany pojedynczej właściwości

Odbieranie wszystkich poprawek za pomocą pojedynczej procedury obsługi zdarzeń

Możesz utworzyć odbiornik, aby otrzymać dowolną zmianę żądanej właściwości.

Ten przykładowy kod generuje wszystkie właściwości odebrane z usługi.

twin.on('properties.desired', function (delta) {
    console.log('new desired properties received:');
    console.log(JSON.stringify(delta));
});

Odbieranie zdarzenia, jeśli cokolwiek się zmienia w ramach grupowania właściwości

Możesz utworzyć odbiornik, aby odebrać zdarzenie, jeśli coś w ramach zmiany grupowania właściwości.

Na przykład:

  1. Właściwości minTemperature i maxTemperature znajdują się w grupie właściwości o nazwie properties.desired.climate changes.

  2. Aplikacja usługi zaplecza stosuje tę poprawkę do aktualizacji minTemperature i maxTemperature żądanych właściwości:

    const twinPatch1 = {
properties: {
   desired: {
    climate: { minTemperature: 68, maxTemperature: 76, },
    },
  },
 };

  3. Ten kod konfiguruje odbiornik zdarzeń zmiany żądanej właściwości, który wyzwala wszelkie zmiany w properties.desired.climate grupie właściwości. Jeśli w tej grupie zostanie zmieniona żądana właściwość, zostaną wyświetlone komunikaty o minimalnych i maksymalnych zmianach temperatury w konsoli:

    twin.on('properties.desired.climate', function (delta) {
    if (delta.minTemperature || delta.maxTemperature) {
        console.log('updating desired temp:');
        console.log('min temp = ' + twin.properties.desired.climate.minTemperature);
        console.log('max temp = ' + twin.properties.desired.climate.maxTemperature);
    }
});

Odbieranie zdarzenia dla zmiany pojedynczej właściwości

Odbiornik można skonfigurować pod kątem zmiany pojedynczej właściwości. W tym przykładzie kod tego zdarzenia jest wykonywany tylko wtedy, gdy fanOn wartość logiczna jest częścią poprawki. Kod generuje nowy żądany fanOn stan za każdym razem, gdy usługa go zaktualizuje.

  1. Aplikacja zaplecza stosuje tę żądaną poprawkę właściwości:

     const twinPatch2 = {
  properties: {
    desired: {
      climate: {
        hvac: {
          systemControl: { fanOn: true, },
        },
      },
    },
  },
};

  2. Odbiornik jest wyzwalany tylko wtedy, gdy fanOn właściwość ulegnie zmianie:

     twin.on('properties.desired.climate.hvac.systemControl', function (fanOn) {
     console.log('setting fan state to ' + fanOn);
  });

Kompletny przykład

Ten przykład hermetyzuje zasady tej sekcji, w tym zagnieżdżanie funkcji wywołania zwrotnego na wielu poziomach.

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-amqp').Amqp;
// Copy/paste your module connection string here.
var connectionString = 'HostName=xxx.azure-devices.net;DeviceId=myFirstDevice2;ModuleId=myFirstModule2;SharedAccessKey=xxxxxxxxxxxxxxxxxx';
// Create a client using the Amqp protocol.
var client = Client.fromConnectionString(connectionString, Protocol);
client.on('error', function (err) {
  console.error(err.message);
});
// connect to the hub
client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
  console.log('client opened');
// Create device Twin
  client.getTwin(function(err, twin) {
    if (err) {
      console.error('error getting twin: ' + err);
      process.exit(1);
    }
    // Output the current properties
    console.log('twin contents:');
    console.log(twin.properties);
    // Add a handler for desired property changes
    twin.on('properties.desired', function(delta) {
        console.log('new desired properties received:');
        console.log(JSON.stringify(delta));
    });
    // create a patch to send to the hub
    var patch = {
      updateTime: new Date().toString(),
      firmwareVersion:'1.2.1',
      weather:{
        temperature: 75,
        humidity: 20
      }
    };
    // send the patch
    twin.properties.reported.update(patch, function(err) {
      if (err) throw err;
      console.log('twin state reported');
    });

  });
});

Przykłady zestawu SDK urządzeń

Zestaw SDK usługi Azure IoT dla Node.js udostępnia działające przykłady aplikacji urządzeń, które obsługują zadania bliźniaczej reprezentacji tożsamości modułu. Aby uzyskać więcej informacji, zobacz:

Tworzenie aplikacji zaplecza

W tej sekcji opisano sposób tworzenia aplikacji zaplecza, która pobiera bliźniacze reprezentacje tożsamości modułu i aktualizuje żądane właściwości.

Instalowanie pakietu zestawu SDK usługi

Uruchom to polecenie, aby zainstalować usługę azure-iothub na maszynie deweloperskiej:

npm install azure-iothub --save

Tworzenie obiektu rejestru

Klasa Registry uwidacznia wszystkie metody wymagane do interakcji z bliźniaczymi reprezentacjami tożsamości modułu z aplikacji zaplecza.

let Registry = require('azure-iothub').Registry;

Nawiązywanie połączenia z centrum IoT

Usługę zaplecza można połączyć z usługą IoT Hub przy użyciu następujących metod:

  • Zasady dostępu współdzielonego
  • Microsoft Entra

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

Nawiązywanie połączenia przy użyciu zasad dostępu współdzielonego

Użyj polecenia fromConnectionString , aby nawiązać połączenie z centrum IoT.

Metoda update używana w tej sekcji wymaga uprawnienia zasad dostępu współdzielonego programu Service Connect w celu dodania żądanych właściwości do modułu. Jako parametr fromConnectionStringparametru podaj zasady dostępu współdzielonego parametry połączenia, które obejmują uprawnienia programu Service Connect. Aby uzyskać więcej informacji na temat zasad dostępu współdzielonego, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu sygnatur dostępu współdzielonego.

let connectionString = '{IoT hub shared access policy connection string}';
let registry = Registry.fromConnectionString(serviceConnectionString);

Nawiązywanie połączenia przy użyciu usługi Microsoft Entra

Aplikacja zaplecza korzystająca z usługi Microsoft Entra musi pomyślnie uwierzytelnić się i uzyskać poświadczenia tokenu zabezpieczającego przed nawiązaniem połączenia z usługą IoT Hub. Ten token jest przekazywany do metody połączenia usługi IoT Hub. Aby uzyskać ogólne informacje na temat konfigurowania i używania usługi Microsoft Entra dla usługi IoT Hub, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu identyfikatora Microsoft Entra.

Aby zapoznać się z omówieniem uwierzytelniania zestawu NODE.JS SDK, zobacz:

Konfigurowanie aplikacji Microsoft Entra

Musisz skonfigurować aplikację Firmy Microsoft Entra skonfigurowaną dla preferowanych poświadczeń uwierzytelniania. Aplikacja zawiera parametry, takie jak klucz tajny klienta, który jest używany przez aplikację zaplecza do uwierzytelniania. Dostępne konfiguracje uwierzytelniania aplikacji to:

  • Klucz tajny klienta
  • Certyfikat
  • Poświadczenia tożsamości federacyjnej

Aplikacje Firmy Microsoft Entra mogą wymagać określonych uprawnień roli w zależności od wykonywanych operacji. Na przykład współautor bliźniaczej reprezentacji usługi IoT Hub jest wymagany do włączenia dostępu do odczytu i zapisu na urządzeniu usługi IoT Hub i bliźniaczych reprezentacjach modułów. Aby uzyskać więcej informacji, zobacz Zarządzanie dostępem do usługi IoT Hub przy użyciu przypisania roli RBAC platformy Azure.

Aby uzyskać więcej informacji na temat konfigurowania aplikacji Microsoft Entra, zobacz Szybki start: rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft.

Uwierzytelnianie przy użyciu wartości DefaultAzureCredential

Najprostszym sposobem użycia usługi Microsoft Entra do uwierzytelniania aplikacji zaplecza jest użycie wartości DefaultAzureCredential, ale zaleca się użycie innej metody w środowisku produkcyjnym, w tym określonej TokenCredential lub pared-down ChainedTokenCredential. Dla uproszczenia w tej sekcji opisano uwierzytelnianie przy użyciu i DefaultAzureCredential klucz tajny klienta. Aby uzyskać więcej informacji na temat zalet i wad korzystania z usługi DefaultAzureCredential, zobacz Łańcuchy poświadczeń w bibliotece klienta tożsamości platformy Azure dla języka JavaScript

Ustawienie domyślneAzureCredential obsługuje różne mechanizmy uwierzytelniania i określa odpowiedni typ poświadczeń na podstawie środowiska, w których jest wykonywany. Próbuje użyć wielu typów poświadczeń w kolejności, dopóki nie znajdzie działającego poświadczenia.

Firma Microsoft Entra wymaga tego pakietu:

npm install --save @azure/identity

W tym przykładzie klucz tajny klienta rejestracji aplikacji Firmy Microsoft, identyfikator klienta i identyfikator dzierżawy zostały dodane do zmiennych środowiskowych. Te zmienne środowiskowe są używane przez DefaultAzureCredential program do uwierzytelniania aplikacji. Wynikiem pomyślnego uwierzytelnienia firmy Microsoft Entra jest poświadczenie tokenu zabezpieczającego przekazywane do metody połączenia usługi IoT Hub.

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

Wynikowy token poświadczeń można następnie przekazać do elementu fromTokenCredential w celu nawiązania połączenia z usługą IoT Hub dla dowolnego klienta zestawu SDK, który akceptuje poświadczenia firmy Microsoft Entra:

fromTokenCredential wymaga dwóch parametrów:

  • Adres URL usługi platformy Azure — adres URL usługi platformy Azure powinien być w formacie {Your Entra domain URL}.azure-devices.net bez prefiksu https:// . Na przykład MyAzureDomain.azure-devices.net.
  • Token poświadczeń platformy Azure

W tym przykładzie poświadczenia platformy Azure są uzyskiwane przy użyciu polecenia DefaultAzureCredential. Następnie podano adres URL domeny i poświadczenia platformy Azure w celu Registry.fromTokenCredential utworzenia połączenia z usługą IoT Hub.

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);
Przykłady kodu

Aby zapoznać się z przykładami pracy uwierzytelniania usługi Microsoft Entra, zobacz Przykłady tożsamości platformy Azure.

Pobieranie bliźniaczej reprezentacji tożsamości modułu i aktualizowanie żądanych właściwości

Możesz utworzyć poprawkę zawierającą żądane aktualizacje właściwości dla bliźniaczej reprezentacji tożsamości modułu.

Aby zaktualizować bliźniaczą reprezentację tożsamości modułu:

  1. Wywołaj metodę getModuleTwin, aby pobrać obiekt bliźniaczej reprezentacji urządzenia.

  2. Sformatuj poprawkę zawierającą aktualizację bliźniaczej reprezentacji tożsamości modułu. Poprawka jest formatowana w formacie JSON zgodnie z opisem w klasie Twin. Poprawka usługi zaplecza zawiera żądane aktualizacje właściwości. Aby uzyskać więcej informacji o formacie poprawki, zobacz Tagi i format właściwości.

  3. Wywołaj aktualizację w celu zaktualizowania bliźniaczej reprezentacji tożsamości modułu za pomocą poprawki.

W tym przykładzie reprezentacja tożsamości modułu jest pobierana dla elementów myDeviceId i myModuleId. Następnie do bliźniaczych reprezentacji, które zawierają climate informacje, zostanie zastosowana poprawka.

// Insert your device ID and moduleId here.
var deviceId = 'myFirstDevice2';
var moduleId = 'myFirstModule2';

// Retrieve the current module identity twin
registry.getModuleTwin(deviceId, moduleId, function (err, twin) {
  console.log('getModuleTwin returned ' + (err ? err : 'success'));
  if (err) {
    console.log(err);
  } else {
    console.log('success');
    console.log('Current twin:' + JSON.stringify(twin))

    // Format a desired property patch
    const twinPatch1 = {
      properties: {
        desired: {
          climate: { minTemperature: 69, maxTemperature: 77, },
        },
      },
    };

    // Send the desired property patch to IoT Hub
    twin.update(twinPatch1, function(err) {
    if (err) throw err;
    console.log('twin state reported');
    });
  }
});

Przykłady zestawu SDK usługi

Zestaw SDK usługi Azure IoT dla Node.js udostępnia działające przykłady aplikacji usług obsługujących zadania bliźniaczej reprezentacji tożsamości modułu. Aby uzyskać więcej informacji, zobacz: