Rozpocznij pracę z bliźniakami urządzeń

Użyj zestawu SDK urządzenia Azure IoT Hub oraz zestawu SDK usługi, aby opracowywać aplikacje obsługujące typowe zadania bliźniaczy model urządzenia. Twiny urządzeń to dokumenty JSON, które przechowują informacje o stanie urządzenia, w tym metadane, konfiguracje i warunki. Usługa IoT Hub przechowuje bliźniaka urządzenia dla każdego urządzenia, które się z nią łączy.

Możesz używać 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
Synchronizowanie stanu 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

Aby uzyskać więcej informacji o bliźniaczych urządzeniach, w tym o tym, kiedy ich używać, zobacz Omówienie bliźniaczych urządzeń i korzystanie z nich w usłudze 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 i rozmiaru usługi IoT Hub dla rozwiązania.

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

Aplikacje urządzeń mogą obsługiwać żądania aktualizacji żądanych właściwości i reagować na zmiany w zgłoszonych właściwościach.
Aplikacje usługi mogą aktualizować tagi bliźniaczych urządzeń, ustawiać nowe właściwości żądane i wykonywać zapytania w oparciu o wartości bliźniaczych urządzeń.

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
Zarejestrowane urządzenie
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życia zestawu Azure IoT SDK dla .NET do tworzenia kodu aplikacji urządzeń i usług backendowych dla twinów urządzeń.

Tworzenie aplikacji urządzenia

Aplikacje urządzeń mogą odczytywać i zapisywać zgłaszane właściwości bliźniacze oraz otrzymywać powiadomienia o zmianach żądanych właściwości bliźniaczych, które są ustawiane przez aplikację backend lub usługę IoT Hub.

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

Pobierz bliźniaczą reprezentację urządzenia i sprawdź zgłoszone właściwości
Aktualizacja zgłoszonych bliźniaczych właściwości urządzenia
Tworzenie procedury obsługi wywołania zwrotnego żądanej aktualizacji właściwości

Pakiet NuGet wymagany dla urządzenia

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

Dodaj tę using instrukcję, aby użyć biblioteki sprzętowej.

using Microsoft.Azure.Devices.Client;

Łą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 Security best practices for IoT solutions Connection security (Najlepsze rozwiązania w zakresie zabezpieczeń rozwiązań > IoT Connection Security).

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

Klasa DeviceClient udostępnia wszystkie metody wymagane do interakcji z bliźniakami urządzeń bezpośrednio z urządzenia.

Nawiąż połączenie z urządzeniem przy użyciu metody CreateFromConnectionString razem z ciągiem połączeniowym urządzenia i protokołem transportu połączenia.

Parametr CreateFromConnectionStringprotokołu transportowego TransportType obsługuje następujące protokoły transportu:

Mqtt
Mqtt_WebSocket_Only
Mqtt_Tcp_Only
Amqp
Amqp_WebSocket_Only
Amqp_Tcp_Only

Protokół Http1 nie jest obsługiwany w przypadku aktualizacji bliźniaczych cyfrowych urządzeń.

Ten przykład łączy się z urządzeniem przy użyciu protokołu transportowego Mqtt .

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

static string DeviceConnectionString = "{IoT hub device connection string}";
static _deviceClient = null;
_deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
   TransportType.Mqtt);

Uwierzytelnianie przy użyciu certyfikatu X.509

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

Użyj elementu DeviceAuthenticationWithX509Certificate , aby utworzyć obiekt zawierający informacje o urządzeniu i certyfikacie. DeviceAuthenticationWithX509Certificate parametr jest przekazywany jako drugi parametr do DeviceClient.Create (krok 2).
Użyj elementu DeviceClient.Create , aby połączyć urządzenie z usługą IoT Hub przy użyciu certyfikatu X.509.

W tym przykładzie informacje o urządzeniu i certyfikacie są wprowadzane do obiektu authDeviceAuthenticationWithX509Certificate, który jest przekazywany do DeviceClient.Create.

W tym przykładzie przedstawiono wartości parametrów wejściowych certyfikatu jako zmienne lokalne w celu zapewnienia przejrzystości. W systemie produkcyjnym przechowuj poufne parametry wejściowe w zmiennych środowiskowych lub innej bezpieczniejszej lokalizacji przechowywania. Na przykład użyj polecenia Environment.GetEnvironmentVariable("HOSTNAME") , aby odczytać zmienną środowiskową nazwy hosta.

RootCertPath = "~/certificates/certs/sensor-thl-001-device.cert.pem";
Intermediate1CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate1.cert.pem";
Intermediate2CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate2.cert.pem";
DevicePfxPath = "~/certificates/certs/sensor-thl-001-device.cert.pfx";
DevicePfxPassword = "1234";
DeviceName = "MyDevice";
HostName = "xxxxx.azure-devices.net";

var chainCerts = new X509Certificate2Collection();
chainCerts.Add(new X509Certificate2(RootCertPath));
chainCerts.Add(new X509Certificate2(Intermediate1CertPath));
chainCerts.Add(new X509Certificate2(Intermediate2CertPath));
using var deviceCert = new X509Certificate2(DevicePfxPath, DevicePfxPassword);
using var auth = new DeviceAuthenticationWithX509Certificate(DeviceName, deviceCert, chainCerts);

using var deviceClient = DeviceClient.Create(
    HostName,
    auth,
    TransportType.Amqp);

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

Przykłady kodu

Aby zapoznać się z działającymi przykładami uwierzytelniania certyfikatu X.509 dla urządzeń, zobacz:

Nawiązywanie połączenia z certyfikatem X.509
DeviceClientX509AuthenticationE2ETests Testy autoryzacji X509 za pomocą klienta urządzenia
Projekt z przewodnikiem — bezpieczne aprowizowanie urządzeń IoT na dużą skalę za pomocą usługi IoT Hub Device Provisioning

Pobieranie bliźniaka urządzenia i sprawdzanie właściwości

Wywołaj GetTwinAsync, aby pobrać bieżące właściwości bliźniacze urządzenia. Możesz wykorzystać wiele właściwości obiektu bliźniaczego, aby uzyskać dostęp do określonych obszarów danych JSON, w tym Properties, Status, Tags i Version.

Ten przykład pobiera właściwości bliźniaka urządzenia i wyświetla wartości bliźniaka w formacie JSON.

Console.WriteLine("Retrieving twin...");
Twin twin = await _deviceClient.GetTwinAsync();
Console.WriteLine("\tInitial twin value received:");
Console.WriteLine($"\t{twin.ToJson()}");

Aktualizowanie zgłoszonych bliźniaczych właściwości urządzenia

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

Tworzenie obiektu TwinCollection dla zgłaszanej aktualizacji właściwości
Aktualizowanie co najmniej jednej zgłoszonej właściwości w TwinCollection obiekcie
Użyj metody UpdateReportedPropertiesAsync, aby przesłać zmiany zgłaszanych 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 _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}
catch (Exception ex)
{
   Console.WriteLine();
   Console.WriteLine("Error in sample: {0}", ex.Message);
}

Utworzenie obsługi wywołań zwrotnych dla aktualizacji właściwości.

Utwórz żą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 urządzenia, przekazując nazwę metody obsługi wywołania zwrotnego na SetDesiredPropertyUpdateCallbackAsync.

Na przykład to wywołanie konfiguruje system w celu powiadomienia metody o nazwieOnDesiredPropertyChangedAsync za każdym razem, gdy żądana właściwość zostanie zmieniona.

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

Właściwości bliźniaczej reprezentacji 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 TwinCollection, a następnie iteruje i wyświetla KeyValuePair aktualizacje kolekcji. Po przeiterowaniu przez kolekcję KeyValuePair, kod wywołuje UpdateReportedPropertiesAsync w celu aktualizowania zgłaszanej właściwości DateTimeLastDesiredPropertyChangeReceived i zachowania aktualności 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 _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}

Przykład urządzenia z zestawem SDK

Zestaw SDK usługi Azure IoT dla platformy .NET udostępnia działający przykład aplikacji urządzenia, który obsługuje zadania związane z bliźniakiem urządzenia. Aby uzyskać więcej informacji, zobacz TwinSample.

Tworzenie aplikacji zaplecza

Aplikacja zaplecza łączy się z urządzeniem za pośrednictwem usługi IoT Hub i może odczytywać zgłaszane i żądane właściwości urządzenia, zapisywać żądane właściwości urządzenia i uruchamiać zapytania dotyczące urządzeń.

W tej sekcji opisano sposób tworzenia kodu aplikacji zaplecza w celu:

Odczytywanie i aktualizowanie pól modelu bliźniaczego urządzenia
Utwórz zapytanie bliźniak urządzenia

Klasa RegistryManager zapewnia wszystkie metody wymagane do utworzenia aplikacji backendowej w celu interakcji z twinami urządzeń z usługi.

Dodaj pakiet NuGet usługi

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

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 Najlepsze rozwiązania w zakresie zabezpieczeń rozwiązań > IoT w chmurze.

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

Połącz aplikację zaplecza z urządzeniem przy użyciu polecenia CreateFromConnectionString. Aplikacja potrzebuje uprawnienia service connect, aby zmodyfikować żądane właściwości bliźniaka urządzenia oraz uprawnienia registry read, aby wykonywać zapytania dotyczące rejestru tożsamości. Nie ma domyślnych zasad dostępu współdzielonego, które zawierają tylko te dwa uprawnienia, więc należy utworzyć je, jeśli jeszcze nie istnieje. Podaj ten parametr łańcucha połączenia zawierający zasady dostępu współdzielonego do fromConnectionString. 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.

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{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świadczenie 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.

Uwierzytelnij się przy użyciu DefaultAzureCredential

Najprostszym sposobem użycia Microsoft Entra do uwierzytelniania aplikacji zaplecza jest użycie DefaultAzureCredential, ale zaleca się zastosowanie innej metody w środowisku produkcyjnym, w tym użycia określonego rodzaju uwierzytelnienia lub uproszczonego procesu. Dla uproszczenia w tej sekcji opisano uwierzytelnianie przy użyciu DefaultAzureCredential i klucza tajnego klienta. Aby uzyskać więcej informacji na temat zalet i wad korzystania z DefaultAzureCredential, zobacz Wskazówki dotyczące użycia 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.

Microsoft Entra wymaga tych pakietów NuGet i odpowiednich using deklaracji.

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

W tym przykładzie klucz tajny klienta, identyfikator klienta i identyfikator dzierżawy aplikacji Microsoft Entra 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 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 cyfrowego bliźniaka urządzenia

Bieżące pola bliźniaczej reprezentacji urządzenia można pobrać do obiektu Twin przez wywołanie GetTwinAsync.

Klasa Twin zawiera właściwości odpowiadające poszczególnym sekcjom urządzenia bliźniaczego. Użyj właściwości klasy Twin, aby wyświetlić i zaktualizować pola bliźniaczej reprezentacji urządzenia. Właściwości obiektu Twin umożliwiają aktualizowanie wielu pól bliźniaczych przed zapisaniem aktualizacji na urządzeniu za pomocą UpdateTwinAsync.

Po wprowadzeniu aktualizacji pól dla obiektu bliźniaczego, wywołaj metodę UpdateTwinAsync, aby zapisać zmiany tych pól z powrotem na urządzeniu. Użyj logiki try i catch, powiązanej z procedurą obsługi błędów, aby przechwycić błędy niepoprawnie sformatowanych poprawek z UpdateTwinAsync.

Odczytywanie i aktualizowanie tagów podwójników urządzeń

Użyj właściwości Tagi podwójnego obiektu urządzenia, aby odczytywać i zapisywać informacje o tagach urządzenia.

Zaktualizuj tagi przy użyciu obiektu bliźniaczego

W tym przykładzie tworzona jest poprawka tagu location, przypisana do obiektu Twin za pomocą właściwości Tags, a następnie stosowana przy użyciu UpdateTwinAsync.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the tag patch
var tagspatch =
   @"{
   tags: {
         location: {
            region: 'US',
            plant: 'Redmond43'
         }
   }
}";

// Assign the patch to the Twin object
twin.Tags["location"] = tagspatch;

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

Aktualizowanie tagów przy użyciu ciągu JSON

Możesz utworzyć i zastosować poprawkę aktualizacji danych bliźniaka urządzenia w formacie JSON. Usługa IoT Hub analizuje i stosuje poprawkę, jeśli jest poprawnie sformatowana.

W tym przykładzie wywołano metodę GetTwinAsync pobierania bieżących pól bliźniaczej reprezentacji urządzenia do Twin obiektu, tworzy poprawkę w tag formacie JSON z informacjami o regionie i lokalizacji zakładu, a następnie wywołuje UpdateTwinAsync metodę stosowania poprawki w celu zaktualizowania bliźniaczej reprezentacji urządzenia. Wyświetlany jest komunikat o błędzie, jeśli UpdateTwinAsync się nie powiedzie.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the JSON tags patch
var patch =
   @"{
      tags: {
            location: {
               region: 'US',
               plant: 'Redmond43'
            }
      }
   }";
// Apply the patch to update the device twin tags
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}

Wyświetlanie i aktualizowanie żądanych właściwości bliźniaka

Użyj właściwości TwinProperties.Desired bliźniaczej reprezentacji urządzenia, aby odczytywać i zapisywać informacje o docelowej właściwości urządzenia. Zaktualizuj właściwości bliźniaczych Desired za pomocą poprawki w formacie JSON.

W tym przykładzie wywoływana jest funkcja GetTwinAsync w celu pobrania bieżących pól reprezentacji bliźniaczej urządzenia do obiektu Twin, zaktualizowania żądanej właściwości bliźniaczej speed, a następnie wywoływana jest funkcja UpdateTwinAsync w celu zastosowania obiektu Twin do aktualizacji bliźniaczej reprezentacji urządzenia.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

twin.Properties.Desired["speed"] = "type: '5G'";
await registryManager.UpdateTwinAsync(twin.DeviceId, twin, twin.ETag);

Inne metody aktualizacji bliźniaków

Aktualizacje bliźniaczych można również stosować przy użyciu następujących metod zestawu SDK.

Wywołaj ReplaceTwinAsync, aby zastąpić całą bliźniaczą reprezentację urządzenia.
Wywołaj UpdateTwins2Async, aby zaktualizować listę bliźniaków utworzonych wcześniej w systemie.

Utwórz zapytanie bliźniaka urządzenia

W tej sekcji przedstawiono dwa zapytania dotyczące bliźniaczego modelu urządzenia. Zapytania podwójnych reprezentacji urządzeń to zapytania podobne do języka SQL, które zwracają zestaw wyników podwójnych reprezentacji urządzeń.

Aby utworzyć zapytanie bliźniaczej reprezentacji urządzenia, wywołaj metodę CreateQuery, aby przesłać zapytanie SQL bliźniaczych reprezentacji i uzyskać interfejs IQuery. Opcjonalnie można wywołać CreateQuery przy użyciu drugiego parametru, aby określić maksymalną liczbę elementów na stronę.

Następnie wywołaj metodę GetNextAsTwinAsync lub GetNextAsJsonAsync tyle razy, ile to konieczne, aby uzyskać wszystkie wyniki bliźniacze.

GetNextAsTwinAsync, aby pobrać następny stronicowany wynik jako obiekty Twin.
GetNextAsJsonAsync służy do pobierania następnego stronicowanego wyniku w postaci ciągów JSON.

Interfejs IQuery zawiera właściwość logiczną HasMoreResults, której można użyć, aby sprawdzić, czy są jeszcze wyniki bliźniacze do pobrania.

To przykładowe zapytanie wybiera tylko bliźniaki urządzeń znajdujące się w zakładzie Redmond43.

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

To przykładowe zapytanie uściśli pierwsze zapytanie, aby wybrać tylko urządzenia, które są również połączone za pośrednictwem sieci komórkowej.

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

Przykład usługi SDK

Azure IoT SDK dla platformy .NET udostępnia działający przykład aplikacji serwisowej obsługującej zadania device twin (bliźniacze urządzenie). Aby uzyskać więcej informacji, zobacz Przykład Menedżera rejestru.

Wymaga zestawu Java SE Development Kit 8. Upewnij się, że w sekcji Wsparcie długoterminowe wybierzesz Java 8, aby przejść do pobierania JDK 8.

Omówienie

W tym artykule opisano sposób używania Azure IoT SDK dla Java do tworzenia kodu aplikacji dla bliźniaków urządzeń i usług backendowych.

Tworzenie aplikacji urządzenia

Aplikacje urządzeń mogą odczytywać i zapisywać zgłaszane właściwości bliźniacze oraz otrzymywać powiadomienia o zmianach właściwości bliźniaczych żądanych przez aplikację zaplecza lub IoT Hub.

W tej sekcji opisano sposób tworzenia kodu aplikacji urządzenia w celu:

Pobieranie i wyświetlanie bliźniaczej reprezentacji urządzenia
Aktualizuj zgłoszone właściwości cyfrowego bliźniaka urządzenia
Subskrybowanie żądanych zmian właściwości

Klasa DeviceClient udostępnia wszystkie metody wymagane do interakcji z bliźniakami urządzeń z poziomu urządzenia.

Ważne

Instrukcje importowania urządzenia

Użyj poniższych instrukcji importowania urządzeń, aby uzyskać dostęp do zestawu AZURE IoT SDK dla języka Java.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.DeviceTwin.*;

Łą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

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

Aby połączyć urządzenie z usługą IoT Hub:

Użyj protokołu IotHubClientProtocol , aby wybrać protokół transportu. Na przykład:
```
IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
```

Użyj konstruktoraDeviceClient, aby dodać podstawowe parametry połączenia i protokół urządzenia.

String connString = "{IoT hub device connection string}";
DeviceClient client = new DeviceClient(connString, protocol);

Użyj otwórz aby połączyć urządzenie z centrum IoT. Jeśli klient jest już otwarty, metoda nic nie robi.
```
client.open(true);
```

Uwierzytelnianie przy użyciu certyfikatu X.509

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

Skompiluj obiekt SSLContext przy użyciu polecenia buildSSLContext.
SSLContext Dodaj informacje do obiektu ClientOptions.
Wywołaj DeviceClient przy użyciu informacji ClientOptions, aby utworzyć połączenie urządzenia z usługą IoT Hub.

W tym przykładzie przedstawiono wartości parametrów wejściowych certyfikatu jako zmienne lokalne w celu zapewnienia przejrzystości. W systemie produkcyjnym przechowuj poufne parametry wejściowe w zmiennych środowiskowych lub innej bezpieczniejszej lokalizacji przechowywania. Na przykład użyj polecenia Environment.GetEnvironmentVariable("PUBLICKEY") , aby odczytać zmienną środowiskową ciągu certyfikatu klucza publicznego.

private static final String publicKeyCertificateString =
        "-----BEGIN CERTIFICATE-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END CERTIFICATE-----\n";

//PEM encoded representation of the private key
private static final String privateKeyString =
        "-----BEGIN EC PRIVATE KEY-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END EC PRIVATE KEY-----\n";

SSLContext sslContext = SSLContextBuilder.buildSSLContext(publicKeyCertificateString, privateKeyString);
ClientOptions clientOptions = ClientOptions.builder().sslContext(sslContext).build();
DeviceClient client = new DeviceClient(connString, protocol, clientOptions);

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

Przykłady kodu

Aby zapoznać się z działającymi przykładami uwierzytelniania certyfikatu X.509 dla urządzeń, zobacz:

Pobieranie i wyświetlanie bliźniaka urządzenia

Po otwarciu połączenia klienta wywołaj metodę getTwin, aby pobrać bieżące właściwości bliźniacze do Twin obiektu.

Na przykład:

private static Twin twin;
System.out.println("Getting current twin");
twin = client.getTwin();
System.out.println("Received current twin:");
System.out.println(twin);

Aktualizować zgłoszone właściwości bliźniaka urządzenia

Po pobraniu bieżącego cyfrowego bliźniaka możesz rozpocząć wprowadzanie aktualizacji zgłoszonych właściwości. Można również aktualizować zgłaszane właściwości bez pobierania bieżącej reprezentacji bliźniaka, o ile masz poprawną wersję zgłaszanych właściwości. Jeśli wysyłasz zgłoszone właściwości i otrzymujesz błąd "Niepowodzenie warunku wstępnego", zgłoszona wersja właściwości jest nieaktualna. W takim przypadku pobierz najnowszą wersję, wywołując getTwin ponownie.

Aby zaktualizować zgłoszone właściwości:

Wywołaj getReportedProperties, aby pobrać zgłoszone właściwości do obiektu TwinCollection.
Użyj polecenia put , aby zaktualizować zgłoszoną właściwość w TwinCollection obiekcie. Wywołaj put każdą zgłoszoną aktualizację właściwości.
Użyj właściwości updateReportedProperties , aby zastosować grupę zgłoszonych właściwości, które zostały zaktualizowane przy użyciu put metody .

Na przykład:

TwinCollection reportedProperties = twin.getReportedProperties();

int newTemperature = new Random().nextInt(80);
reportedProperties.put("HomeTemp(F)", newTemperature);
System.out.println("Updating reported property \"HomeTemp(F)\" to value " + newTemperature);

ReportedPropertiesUpdateResponse response = client.updateReportedProperties(reportedProperties);
System.out.println("Successfully set property \"HomeTemp(F)\" to value " + newTemperature);

Wywołaj metodę subscribeToDesiredProperties , aby zasubskrybować żądane zmiany właściwości. Ten klient otrzymuje wywołanie zwrotne z obiektem Twin za każdym razem, gdy żądana właściwość jest aktualizowana. Wywołanie zwrotne zawiera pełny zestaw żądanych właściwości lub tylko zaktualizowaną żądaną właściwość w zależności od sposobu zmiany żądanej właściwości.

W tym przykładzie subskrybuje się zmiany oczekiwanych właściwości. Wszelkie żądane zmiany właściwości są przekazywane do programu obsługi o nazwie DesiredPropertiesUpdatedHandler.

client.subscribeToDesiredProperties(new DesiredPropertiesUpdatedHandler(), null);

W tym przykładzie procedura obsługi zmiany żądanej właściwości DesiredPropertiesUpdatedHandler wywołuje metodę getDesiredProperties, aby pobrać zmiany właściwości, a następnie wyświetla zaktualizowane właściwości bliźniaka.

  private static class DesiredPropertiesUpdatedHandler implements DesiredPropertiesCallback
  {
      @Override
      public void onDesiredPropertiesUpdated(Twin desiredPropertyUpdateTwin, Object context)
      {
          if (twin == null)
          {
              // No need to care about this update because these properties will be present in the twin retrieved by getTwin.
              System.out.println("Received desired properties update before getting current twin. Ignoring this update.");
              return;
          }

          // desiredPropertyUpdateTwin.getDesiredProperties() contains all the newly updated desired properties as well as the new version of the desired properties
          twin.getDesiredProperties().putAll(desiredPropertyUpdateTwin.getDesiredProperties());
          twin.getDesiredProperties().setVersion(desiredPropertyUpdateTwin.getDesiredProperties().getVersion());
          System.out.println("Received desired property update. Current twin:");
          System.out.println(twin);
      }
  }

Przykład urządzenia z zestawem SDK

Zestaw SDK usługi Azure IoT dla języka Java zawiera działający przykład testowania pojęć dotyczących aplikacji urządzenia opisanych w tym artykule. Aby uzyskać więcej informacji, zobacz Przykład bliźniaczej reprezentacji urządzenia.

Tworzenie aplikacji zaplecza

W tej sekcji opisano sposób tworzenia aplikacji zaplecza, która:

Aktualizuje tagi reprezentacji urządzenia typu "device twin"
Wysyła zapytania do urządzeń przy użyciu filtrów w tagach i właściwościach

Klasa ServiceClientDeviceTwin zawiera metody, których usługi mogą używać do uzyskiwania dostępu do bliźniaczych reprezentacji urządzeń.

Instrukcje importowania usługi

Użyj poniższych instrukcji importowania usługi, aby uzyskać dostęp do zestawu AZURE IoT SDK dla języka Java.

import com.microsoft.azure.sdk.iot.service.devicetwin.*;
import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;

Nawiązywanie połączenia 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

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

Użyj konstruktora DeviceTwin , aby utworzyć połączenie z centrum IoT Hub. Obiekt DeviceTwin obsługuje komunikację z centrum IoT Hub.

Aplikacja potrzebuje uprawnienia do połączenia z usługą, aby zmodyfikować żądane właściwości Wirtualnego Bliźniaka urządzenia, oraz uprawnienia do odczytu rejestru, aby wykonywać zapytania dotyczące rejestru tożsamości. Nie ma domyślnych zasad dostępu współdzielonego, które zawierają tylko te dwa uprawnienia, więc należy utworzyć je, jeśli jeszcze nie istnieje. Podaj te zasady dostępu współdzielonego parametry połączenia jako parametr do fromConnectionString. 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.

Obiekt DeviceTwinDevice reprezentuje bliźniaczy obiekt urządzenia wraz z jego właściwościami i tagami.

Na przykład:

public static final String iotHubConnectionString = "{Shared access policy connection string}";
public static final String deviceId = "myDeviceId";
public static final String region = "US";
public static final String plant = "Redmond43";

// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = new DeviceTwin(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);

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 nawiązania połączenia z usługą 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 Java SDK, zobacz Uwierzytelnianie platformy Azure przy użyciu języka Java i tożsamości platformy Azure.

Dla uproszczenia ta sekcja koncentruje się na opisywaniu uwierzytelniania przy użyciu klucza tajnego klienta.

Konfigurowanie aplikacji Microsoft Entra

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 kontrybutor bliźniaków IoT Hub jest wymagany do włączenia dostępu do odczytu i zapisu na urządzeniach i bliźniakach modułów usługi IoT Hub. 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.

Uwierzytelnij się przy użyciu 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. Aby uzyskać więcej informacji na temat zalet i wad używania programu DefaultAzureCredential, zobacz Łańcuchy poświadczeń w bibliotece klienta tożsamości platformy Azure dla języka Java.

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.

Możesz uwierzytelnić poświadczenia aplikacji Microsoft Entra przy użyciu polecenia DefaultAzureCredentialBuilder. Zapisz parametry połączenia, takie jak tenantID, clientID oraz wartości client secret jako zmienne środowiskowe. Po utworzeniu TokenCredential, przekaż go do ServiceClient lub innego konstruktora jako parametr "credential".

W tym przykładzie DefaultAzureCredentialBuilder próbuje uwierzytelnić połączenie z listy opisanej w DefaultAzureCredential. Wynikiem pomyślnego uwierzytelnienia firmy Microsoft Entra jest poświadczenie tokenu zabezpieczającego przekazywane do konstruktora takiego jak ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();

Uwierzytelnianie przy użyciu ClientSecretCredentialBuilder

Aby utworzyć poświadczenia przy użyciu informacji o kluczu tajnym klienta, możesz użyć elementu ClientSecretCredentialBuilder . Jeśli ta metoda powiedzie się, zwraca wartość TokenCredential, która może zostać przekazana do ServiceClient lub innego konstruktora jako parametr "credential".

W tym przykładzie do zmiennych środowiskowych dodano wartości tajnego klucza klienta, identyfikatora klienta oraz identyfikatora dzierżawy aplikacji Microsoft Entra. Te zmienne środowiskowe są używane przez ClientSecretCredentialBuilder do budowania poświadczeń.

string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");

TokenCredential credential =
     new ClientSecretCredentialBuilder()
          .tenantId(tenantID)
          .clientId(clientID)
          .clientSecret(clientSecretValue)
          .build();

Inne klasy uwierzytelniania

Zestaw JAVA SDK zawiera również te klasy, które uwierzytelniają aplikację zaplecza za pomocą usługi Microsoft Entra:

Przykłady kodu

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

Aktualizowanie pól obiektu bliźniaczego urządzenia

Aby zaktualizować pola bliźniaczego urządzenia:

Użyj getTwin , aby pobrać bieżące pola bliźniaka urządzenia

W tym przykładzie są pobierane i drukowane pola bliźniaczej reprezentacji urządzenia:
```
// Get the device twin from IoT Hub
System.out.println("Device twin before update:");
twinClient.getTwin(device);
System.out.println(device);
```
Użyj obiektu HashSet do add grupy par tagów bliźniaczych
Dodawanie grupy par tagów z obiektu do tags obiektu za pomocą DeviceTwinDevice

Użyj updateTwin do zaktualizowania bliźniaka w centrum IoT.

W tym przykładzie zaktualizowano tagi dotyczące regionu i zakładu dla bliźniaczej reprezentacji urządzenia.

// Update device twin tags if they are different
// from the existing values
String currentTags = device.tagsToString();
if ((!currentTags.contains("region=" + region) && !currentTags.contains("plant=" + plant))) {

// Create the tags and attach them to the DeviceTwinDevice object
Set<Pair> tags = new HashSet<Pair>();
tags.add(new Pair("region", region));
tags.add(new Pair("plant", plant));
device.setTags(tags);

// Update the device twin in IoT Hub
System.out.println("Updating device twin");
twinClient.updateTwin(device);
}

// Retrieve and display the device twin with the tag values from IoT Hub
System.out.println("Device twin after update:");
twinClient.getTwin(device);
System.out.println(device);

Tworzenie zapytania cyfrowego bliźniaka urządzenia

W tej sekcji przedstawiono dwa zapytania dotyczące bliźniaczych urządzeń. Zapytania dotyczące bliźniaków urządzeń to zapytania przypominające SQL, które zwracają zestaw wyników bliźniaków urządzeń.

Klasa Query zawiera metody, których można użyć do tworzenia zapytań w stylu SQL dla IoT Hub dla bliźniaków, zadań, zadań urządzeń lub danych surowych.

Aby utworzyć zapytanie dotyczące urządzenia:

Użyj createSqlQuery do zbudowania zapytania SQL dla bliźniaków.
Wykonywanie zapytania przy użyciu metody queryTwin
Użyj hasNextDeviceTwin, aby sprawdzić, czy w zestawie wyników znajduje się inny bliźniak urządzenia.
Użyj getNextDeviceTwin, aby pobrać następną reprezentację urządzenia z zestawu wyników

Poniższe przykładowe zapytania zwracają maksymalnie 100 urządzeń.

To przykładowe zapytanie wybiera tylko cyfrowe bliźniaki urządzeń znajdujące się w zakładzie Redmond43.

// Query the device twins in IoT Hub
System.out.println("Devices in Redmond:");

// Construct the query
SqlQuery sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43'", null);

// Run the query, returning a maximum of 100 devices
Query twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 100);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

To przykładowe zapytanie uściśli pierwsze zapytanie, aby wybrać tylko urządzenia, które są również połączone za pośrednictwem sieci komórkowej.

System.out.println("Devices in Redmond using a cellular network:");

// Construct the query
sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43' AND properties.reported.connectivityType = 'cellular'", null);

// Run the query, returning a maximum of 100 devices
twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 3);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

Przykład usługi SDK

Zestaw SDK Azure IoT dla Javy udostępnia działający przykład aplikacji serwisowej obsługującej zadania bliźniaczej reprezentacji urządzenia. Aby uzyskać więcej informacji, zobacz Przykład Device Twin.

Zestaw PYTHON SDK — 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, jak używać Azure IoT SDK dla Pythona do tworzenia kodu aplikacji urządzeń i usług zaplecza dla bliźniaków cyfrowych.

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

Tworzenie aplikacji urządzenia

Aplikacje urządzeń mogą odczytywać i zapisywać zgłaszane właściwości bliźniaczej oraz otrzymywać powiadomienia o zmianach właściwości żądanej, które są ustawiane przez aplikacje serwerowe lub IoT Hub.

Klasa IoTHubDeviceClient zawiera metody, których można użyć do pracy z bliźniaczymi urządzeniami.

W tej sekcji opisano sposób tworzenia kodu aplikacji urządzenia, który:

Pobiera bliźniacze reprezentacje urządzenia i sprawdza zgłaszane właściwości
Zgłoszone właściwości bliźniacze urządzenia

Instrukcja importowania urządzenia

Dodaj ten kod, aby zaimportować funkcje IoTHubDeviceClient z zestawu SDK Azure.IoT.Device.

from azure.iot.device import IoTHubDeviceClient

Łą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

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

Aby połączyć urządzenie z usługą IoT Hub:

Wywołaj create_from_connection_string, aby dodać parametry połączenia podstawowego urządzenia.
Wywołaj connect, aby nawiązać połączenie z klientem urządzenia.

Na przykład:

# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

# Connect the client
device_client.connect()

Uwierzytelnianie przy użyciu certyfikatu X.509

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

Użyj create_from_x509_certificate , aby dodać parametry certyfikatu X.509
Zadzwoń do connect, aby połączyć klienta urządzenia

W tym przykładzie przedstawiono wartości parametrów wejściowych certyfikatu jako zmienne lokalne w celu zapewnienia przejrzystości. W systemie produkcyjnym przechowuj poufne parametry wejściowe w zmiennych środowiskowych lub innej bezpieczniejszej lokalizacji przechowywania. Na przykład użyj polecenia os.getenv("HOSTNAME") , aby odczytać zmienną środowiskową nazwy hosta.

# The Azure IoT hub name
hostname = "xxxxx.azure-devices.net"

# The device that has been created on the portal using X509 CA signing or self-signing capabilities
device_id = "MyDevice"

# The X.509 certificate file name
cert_file = "~/certificates/certs/sensor-thl-001-device.cert.pfx"
key_file = "~/certificates/certs/sensor-thl-001-device.cert.key"
# The optional certificate pass phrase
pass_phrase = "1234"

x509 = X509(
    cert_file,
    key_file,
    pass_phrase,
)

# The client object is used to interact with your Azure IoT hub.
device_client = IoTHubDeviceClient.create_from_x509_certificate(
    hostname=hostname, device_id=device_id, x509=x509
)

# Connect to IoT Hub
await device_client.connect()

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

Przykłady kodu

Aby zapoznać się z przykładami pracy uwierzytelniania certyfikatu X.509 urządzenia, zobacz przykłady, których nazwy plików kończą się na x509 w scenariuszach centrum asynchronicznego.

** Pobierz bliźniaczy model urządzenia i przeanalizuj zgłoszone właściwości

Możesz pobrać i zbadać informacje o bliźniaczym stanie urządzenia, w tym tagi i właściwości. Pobrane informacje o bliźniaczym urządzeniu są zgodne z danymi w formacie JSON, które można wyświetlić dla urządzenia w portalu Azure.

Wywołaj get_twin, aby uzyskać zdublowaną reprezentację urządzenia z usługi Azure IoT Hub. Informacje o bliźniakach są umieszczane w zmiennej, którą można wyświetlić lub 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))

Zaktualizowane zgłoszone właściwości bliźniaczej reprezentacji urządzenia

Możesz zastosować poprawkę w celu zaktualizowania właściwości zgłoszonych przez urządzenie w formacie JSON.

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

Przypisz poprawkę JSON zgłaszanej właściwości do zmiennej.
Wywołaj patch_twin_reported_properties , aby zastosować poprawkę JSON do zgłoszonych właściwości. Jest to wywołanie synchroniczne, co oznacza, że ta funkcja nie zwraca się do momentu wysłania poprawki do usługi i potwierdzenia.

Jeśli patch_twin_reported_properties zwraca błąd, ta funkcja zgłasza odpowiedni błąd.

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

Można również wywołać te metody, aby zaktualizować bliźniaki urządzeń.

Wywołaj replace_twin , aby zastąpić tagi bliźniaczej reprezentacji urządzenia i żądane właściwości.
Wywołaj update_twin, aby zaktualizować tagi i żądane właściwości bliźniaczego urządzenia.

Przychodzący żądany program obsługi poprawek właściwości

Wywołaj on_twin_desired_properties_patch_received, aby utworzyć funkcję obsługi lub coroutine wywoływaną po odebraniu poprawki żądanych właściwości bliźniaka. Obsługiwacz przyjmuje jeden argument, który jest w postaci poprawki bliźniaka w formie 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 pożądanych 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 AZURE IoT SDK dla języka Python zawiera następujące przykłady:

get_twin - Połącz się z urządzeniem i pobierz informacje o jego bliźniaku.
update_twin_reported_properties — aktualizowanie zgłoszonych właściwości bliźniaczej reprezentacji.
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:

Aktualizuj tagi bliźniacze i żądane właściwości
Wysyła zapytania do urządzeń przy użyciu filtrów w tagach i właściwościach

Klasa IoTHubRegistryManager udostępnia wszystkie metody wymagane do stworzenia aplikacji backendowej umożliwiającej interakcję z bliźniaczymi modelami urządzeń w ramach usługi.

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

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

Nawiąż połączenie z centrum IoT za pomocą from_connection_string. Aplikacja potrzebuje uprawnienia połączenia z usługą do modyfikacji żądanych właściwości bliźniaka urządzenia i wymaga uprawnienia odczytu rejestru do wykonywania zapytań w rejestrze tożsamości. Nie ma domyślnych zasad dostępu współdzielonego, które zawierają tylko te dwa uprawnienia, więc należy utworzyć je, jeśli jeszcze nie istnieje. Podaj te zasady dostępu współdzielonego parametry połączenia jako parametr do fromConnectionString. 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:

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

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub service 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 przesyłany do metody łączenia z usługą 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

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

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 DefaultAzureCredential, ale zaleca się użycie innej metody w środowisku produkcyjnym, w tym określonego TokenCredential lub odchudzonego ChainedTokenCredential. Dla uproszczenia w tej sekcji opisano uwierzytelnianie przy użyciu DefaultAzureCredential i sekretem 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.

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

Microsoft Entra wymaga pakietu do importu i odpowiedniej import instrukcji.

pip install azure-identity

from azure.identity import DefaultAzureCredential

W tym przykładzie klucz tajny klienta rejestracji aplikacji Microsoft Entra, 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 za pomocą Microsoft Entra jest poświadczenie tokenu zabezpieczającego, które jest przekazywane do metody połączenia usługi IoT Hub.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

Wynikowy AccessToken można następnie przekazać do from_token_credential w celu podłączenia się do usługi IoT Hub dla dowolnego klienta SDK akceptującego poświadczenia Microsoft Entra.

IoTHubRegistryManager w celu utworzenia połączenia z usługą IoT Hub przy użyciu poświadczeń tokenu Entra.
IoTHubJobManager
DigitalTwinClient
IoTHubHttpRuntimeManager
IoTHubConfigurationManager

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 usługi platformy Azure oraz poświadczenia są następnie dostarczane do IoTHubRegistryManager.from_token_credential, aby utworzyć połączenie 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.

Aktualizowanie tagów bliźniaków i pożądanych właściwości

Tagi bliźniaczej reprezentacji urządzenia i żądane właściwości można zaktualizować z poziomu aplikacji zaplecza w tym samym czasie przy użyciu update_twin.

Wywołaj get_twin, aby pobrać bieżącą wersję bliźniaczego urządzenia.
Użyj klasy Twin, aby dodać tagi i właściwości w formacie JSON.
Wywołaj metodę update_twin , aby zastosować poprawkę do bliźniaczej reprezentacji urządzenia. Można również użyć replace_twin , aby zastąpić żądane właściwości i tagi bliźniaczej reprezentacji urządzenia.

Ten przykład aktualizuje region informacje o tagach i plant ustawia żądaną power_level właściwość na 1wartość .

new_tags = {
        'location' : {
            'region' : 'US',
            'plant' : 'Redmond43'
        }
    }

DEVICE_ID = "[Device Id]"
twin = iothub_registry_manager.get_twin(DEVICE_ID)
twin_patch = Twin(tags=new_tags, properties= TwinProperties(desired={'power_level' : 1}))
twin = iothub_registry_manager.update_twin(DEVICE_ID, twin_patch, twin.etag)

Tworzenie zapytania bliźniaczej reprezentacji urządzenia

Zapytania dotyczące bliźniaczej reprezentacji urządzenia można wykonywać przy użyciu zapytań bliźniaczych reprezentacji urządzenia. Zapytania bliźniaczych urządzeń to zapytania podobne do SQL, które zwracają zestaw wyników bliźniaczych urządzeń.

Aby użyć zapytania bliźniaczej reprezentacji urządzenia:

Użyj obiektu QuerySpecification, aby zdefiniować żądanie zapytania przypominające sql.
Użyj query_iot_hub , aby wysłać zapytanie do usługi IoTHub i pobrać informacje o bliźniaczej reprezentacji urządzenia przy użyciu specyfikacji zapytania przypominającej język SQL.

W tym przykładzie są uruchamiane dwa zapytania. Pierwszy wybiera tylko bliźniacze reprezentacje urządzeń znajdujących się w Redmond43 zakładzie, a drugi uściśli zapytanie, aby wybrać tylko urządzenia połączone za pośrednictwem sieci komórkowej. Wyniki są drukowane po każdym zapytaniu.

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity = 'cellular'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant using cellular network: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

Przykład usługi SDK

Zestaw SDK Azure IoT dla języka Python udostępnia działający przykład aplikacji serwisowej, która obsługuje zadania bliźniaczej definicji urządzenia. Aby uzyskać więcej informacji, zobacz Przykład zapytania Menedżera rejestru.

Wymaga Node.js w wersji 10.0.x lub nowszej

Omówienie

W tym artykule opisano sposób używania zestawu SDK usługi Azure IoT dla Node.js do tworzenia kodu aplikacji usługi urządzenia i zaplecza dla bliźniaczych reprezentacji urządzeń.

Tworzenie aplikacji urządzenia

Aplikacje urządzeń mogą odczytywać i zapisywać zgłaszane właściwości bliźniaczej reprezentacji bliźniaczej oraz otrzymywać powiadomienia o zmianach właściwości żądanej reprezentacji bliźniaczej, które są ustawiane przez aplikację zaplecza lub usługę IoT Hub.

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 urządzenia i badanie zgłoszonych właściwości
Aktualizowanie zgłoszonych właściwości bliźniaczego modelu urządzenia
Powiadomienia o oczekiwanych zmianach w nieruchomościach

Ważne

Instalowanie pakietu zestawu SDK urządzenia

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:

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

Ważne

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:

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 parametru połączenia, aby wskazać, że certyfikat został dodany do DeviceClientOptions. Na przykład:
- Parametry połączenia urządzenia:
  
  HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
- Ciąg połączenia modułu tożsamości:
  
  HostName=xxxxx.azure-devices.net;DeviceId=Device-1;ModuleId=Module-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
Skonfiguruj zmienną JSON ze szczegółami certyfikatu i przekaż ją do elementu DeviceClientOptions.
Wywołaj setOptions, aby dodać certyfikat i klucz X.509 (i opcjonalnie hasło) do transportu klienta.
Wywołaj open w celu otwarcia połączenia z urządzenia do IoT Hub.

W tym przykładzie przedstawiono informacje o konfiguracji certyfikatu w zmiennej JSON. Konfiguracja certyfikacji clientOptions jest przekazywana do setOptions, a połączenie jest otwierane za pomocą 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).

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

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źniaka urządzenia.

Wybieranie protokołu transportowego

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

Amqp
Http — W przypadku korzystania z Http, wystąpienie Client sprawdza komunikaty z IoT Hub przynajmniej raz na 25 minut.
Mqtt
MqttWs
AmqpWs

Zainstaluj wymagane protokoły transportu na maszynie dewelopera.

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

npm install azure-iot-device-mqtt --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ą a urządzeniem i Wybieranie protokołu komunikacyjnego.

Tworzenie modułu klienta

Client Utwórz moduł przy użyciu zainstalowanego pakietu.

Na przykład:

const Client = require('azure-iot-device').Client;

Tworzenie modułu protokołu

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

W tym przykładzie przypisano protokół MQTT:

const Protocol = require('azure-iot-device-mqtt').Mqtt;

Dodaj ciąg połączenia urządzenia i protokół transportowy

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

connStr — łańcuch połączenia, który hermetyzuje uprawnienia „device connect” dla centrum IoT. Parametry połączenia zawiera nazwę hosta, identyfikator urządzenia i klucz dostępu współużytkowanego w tym formacie: "HostName=<iothub_host_name>; DeviceId=<device_id>; SharedAccessKey=<device_key>".
transportCtor — protokół transportowy.

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

const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Mqtt;
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. Użyj .catch(err), aby przechwycić błąd i wykonać kod obsługującego.

Na przykład:

client.open()  //open the connection
.catch((err) => {
  console.error('Could not connect: ' + err.message);
});

Pobieranie bliźniaka urządzenia i przegląd zgłoszonych właściwości

Wywołaj getTwin, aby pobrać bieżące informacje o bliźniaczej reprezentacji urządzenia do obiektu Twin.

Na przykład:

client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

Aktualizowanie zgłoszonych bliźniaczych właściwości urządzenia

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, aktualizacja bliźniaczego urządzenia w formacie JSON jest przechowywana w zmiennej patch. Poprawka zawiera aktualizację wartości bliźniaczego modelu urządzenia connectivity o wartości cellular. Procedury obsługi poprawek i błędów są przekazywane do metody update. Jeśli wystąpi błąd, zostanie wyświetlony komunikat o błędzie konsoli.

var patch = {
    connectivity: {
        type: 'cellular'
    }
}
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

Otrzymywanie powiadomienia o zmianach żądanych właściwości

Utwórz żądany odbiornik zdarzeń aktualizacji właściwości, który jest wykonywany po zmianie żądanej właściwości na urządzeniu, przekazując nazwę metody obsługi wywołania zwrotnego do twin.on.

Odbiornik zdarzeń żądanej właściwości może mieć jedną z następujących form:

Odbieranie wszystkich poprawek za pomocą pojedynczej procedury obsługi zdarzeń
Otrzymywanie zdarzenia, jeśli zachodzą jakieś zmiany w ramach grupowania właściwości
Odbieranie zdarzenia zmiany jednej 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ś ulegnie zmianie w ramach grupowania właściwości.

Na przykład:

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

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, },
    },
  },
 };

Ten kod konfiguruje żądany odbiornik zdarzeń zmiany właściwości, który wyzwala wszelkie zmiany w properties.desired.climate obrębie grupowania właściwości. Jeśli w tej grupie zostanie zmieniona żądana właściwość, minimalna i maksymalna liczba komunikatów o zmianie temperatury wyświetlanych 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.

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

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

Nasłuchiwacz jest uruchamiany tylko wtedy, gdy właściwość fanOn ulegnie zmianie.

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

Przykłady zestawu SDK urządzeń

SDK Azure IoT dla Node.js zawiera dwa przykłady urządzenia typu device twin:

Tworzenie aplikacji zaplecza

W tej sekcji opisano sposób tworzenia aplikacji zaplecza, która:

Pobiera i aktualizuje bliźniaczy obraz urządzenia
Tworzy zapytanie pary urządzenia

Instalowanie pakietu zestawu SDK usługi

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

npm install azure-iothub --save

Klasa Registry udostępnia wszystkie metody potrzebne do interakcji z bliźniaczymi obiektami urządzeń z aplikacji zaplecza.

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

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

Użyj polecenia fromConnectionString , aby nawiązać połączenie z centrum IoT. Aplikacja wymaga uprawnień połączenia usługi w celu zmodyfikowania żądanych właściwości bliźniaczej postaci urządzenia i wymaga 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 należy utworzyć je, jeśli jeszcze nie istnieje. Podaj ten ciąg połączenia zasad dostępu współdzielonego jako parametr do fromConnectionString. 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.

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Shared access policy connection string}';
var registry = iothub.Registry.fromConnectionString(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 przekazujemy do metody połączenia z usługą 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

Tajny klucz klienta
Certyfikat
Poświadczenie tożsamości federacyjnej

Aplikacje Firmy Microsoft Entra mogą wymagać określonych uprawnień roli w zależności od wykonywanych operacji. Na przykład IoT Hub Twin Contributor jest wymagany do włączenia dostępu do odczytu i zapisu dla urządzeń IoT Hub oraz bliźniaczych reprezentacji 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.

Uwierzytelnij się przy użyciu DefaultAzureCredential

Najprostszym sposobem użycia usługi Microsoft Entra do uwierzytelniania aplikacji zaplecza jest użycie DefaultAzureCredential, ale zaleca się użycie innej metody w środowisku produkcyjnym, takiej jak specyficzna TokenCredential lub uproszczona ChainedTokenCredential. Dla uproszczenia w tej sekcji opisano uwierzytelnianie przy użyciu klucza tajnego klienta DefaultAzureCredential. 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

Firma Microsoft Entra wymaga tego pakietu:

npm install --save @azure/identity

W tym przykładzie tajny klucz, identyfikator klienta oraz identyfikator dzierżawy zarejestrowane przez aplikację Microsoft Entra zostały dodane do zmiennych środowiskowych. Te zmienne środowiskowe są używane przez DefaultAzureCredential program do uwierzytelniania aplikacji. Wynikiem pomyślnego uwierzytelnienia za pomocą Microsoft Entra jest poświadczenie tokenu zabezpieczeń przekazywane do metody połączenia 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 adres URL domeny i poświadczenia platformy Azure są przekazywane do Registry.fromTokenCredential w celu 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 działającymi przykładami uwierzytelniania usługi Microsoft Entra, zobacz Przykłady Azure Identity.

Pobieranie i aktualizowanie bliźniaka urządzenia

Możesz utworzyć poprawkę zawierającą tagi i żądane aktualizacje właściwości dla bliźniaka urządzenia.

Aby zaktualizować bliźniaka urządzenia:

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

Sformatuj łatkę zawierającą aktualizację bliźniaczego modelu urządzenia. Poprawka jest formatowana w formacie JSON zgodnie z opisem w klasie Twin. Poprawka usługi zaplecza może zawierać aktualizacje tagów i żądanych właściwości. Aby uzyskać więcej informacji o formacie poprawki, zobacz Tagi i format właściwości.

Wywołaj update w celu zaktualizowania twina urządzenia za pomocą poprawki.

W tym przykładzie bliźniacze reprezentacje urządzenia są pobierane dla myDeviceIdelementu , a następnie poprawka jest stosowana do bliźniaczych reprezentacji zawierających location aktualizację tagu region: 'US', plant: 'Redmond43'.

     registry.getTwin('myDeviceId', function(err, twin){
         if (err) {
             console.error(err.constructor.name + ': ' + err.message);
         } else {
             var patch = {
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                   }
                 }
             };

             twin.update(patch, function(err) {
               if (err) {
                 console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
               } else {
                 console.log(twin.deviceId + ' twin updated successfully');
                 queryTwins();
               }
             });
         }
     });

Utwórz zapytanie dotyczące cyfrowego bliźniaka urządzenia

Zapytania dotyczące urządzeń przypominających język SQL można tworzyć w celu zbierania informacji z bliźniaczych reprezentacji urządzeń.

Użyj createQuery do utworzenia zapytania, które można uruchomić na instancji usługi IoT Hub, aby znaleźć informacje o urządzeniach lub zadaniach.

createQuery zawiera dwa parametry:

sqlQuery — zapytanie napisane jako ciąg SQL.
pageSize — żądana liczba wyników na stronę (opcjonalnie. wartość domyślna: 1000, maksymalna: 10000).

Jeśli parametr pageSize jest określony, obiekt zapytania zawiera właściwość typu logicznego, którą można sprawdzić, i użyć hasMoreResults metody, aby otrzymać kolejną nextAsTwin stronę wyników tyle razy, ile potrzeba, aby pobrać wszystkie wyniki. Metoda o nazwie next jest dostępna dla wyników, które nie są bliźniaczymi reprezentacjami urządzeń, na przykład wynikami zapytań agregacji.

To przykładowe zapytanie wybiera tylko bliźniaki urządzeń znajdujące się w Redmond43 zakładzie.

var queryTwins = function() {
var query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});

To przykładowe zapytanie uściśli pierwsze zapytanie, aby wybrać tylko urządzenia, które są również połączone za pośrednictwem sieci komórkowej.

query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});
};

Przykład zestawu SDK usługi

Zestaw SDK Azure IoT dla Node.js udostępnia działający przykład aplikacji serwisowej obsługującej zadania związane z bliźniaczymi reprezentacjami urządzeń. Aby uzyskać więcej informacji, zobacz Usługa zaplecza Bliźniaka Urządzenia — ten projekt służy do wysyłania aktualizacji poprawek bliźniaka urządzenia dla określonego urządzenia.

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-04-10

Udostępnij za pomocą

Rozpocznij pracę z bliźniakami urządzeń

Wymagania wstępne

Omówienie

Tworzenie aplikacji urządzenia

Pakiet NuGet wymagany dla urządzenia

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

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

Uwierzytelnianie przy użyciu certyfikatu X.509

Przykłady kodu

Pobieranie bliźniaka urządzenia i sprawdzanie właściwości

Aktualizowanie zgłoszonych bliźniaczych właściwości urządzenia

Utworzenie obsługi wywołań zwrotnych dla aktualizacji właściwości.

Przykład urządzenia z zestawem SDK

Tworzenie aplikacji zaplecza

Dodaj pakiet NuGet usługi

Nawiązywanie połączenia z centrum IoT

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

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

Konfigurowanie aplikacji Microsoft Entra

Uwierzytelnij się przy użyciu DefaultAzureCredential

Przykład kodu

Odczytywanie i aktualizowanie pól cyfrowego bliźniaka urządzenia

Odczytywanie i aktualizowanie tagów podwójników urządzeń

Zaktualizuj tagi przy użyciu obiektu bliźniaczego

Aktualizowanie tagów przy użyciu ciągu JSON

Wyświetlanie i aktualizowanie żądanych właściwości bliźniaka

Inne metody aktualizacji bliźniaków

Utwórz zapytanie bliźniaka urządzenia

Przykład usługi SDK

Omówienie

Tworzenie aplikacji urządzenia

Instrukcje importowania urządzenia

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

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

Uwierzytelnianie przy użyciu certyfikatu X.509

Przykłady kodu

Pobieranie i wyświetlanie bliźniaka urządzenia

Aktualizować zgłoszone właściwości bliźniaka urządzenia

Subskrybowanie żądanych zmian właściwości

Przykład urządzenia z zestawem SDK

Tworzenie aplikacji zaplecza

Instrukcje importowania usługi

Nawiązywanie połączenia z usługą IoT Hub

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

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

Konfigurowanie aplikacji Microsoft Entra

Uwierzytelnij się przy użyciu DefaultAzureCredential

Uwierzytelnianie przy użyciu ClientSecretCredentialBuilder

Inne klasy uwierzytelniania

Przykłady kodu

Aktualizowanie pól obiektu bliźniaczego urządzenia

Tworzenie zapytania cyfrowego bliźniaka urządzenia

Przykład usługi SDK

Omówienie

Instalowanie pakietów

Tworzenie aplikacji urządzenia

Instrukcja importowania urządzenia

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

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

Uwierzytelnianie przy użyciu certyfikatu X.509

Przykłady kodu

** Pobierz bliźniaczy model urządzenia i przeanalizuj zgłoszone właściwości

Zaktualizowane zgłoszone właściwości bliźniaczej reprezentacji urządzenia

Przychodzący żądany program obsługi poprawek właściwości

Przykłady urządzeń z zestawem SDK

Tworzenie aplikacji zaplecza

Nawiązywanie połączenia z centrum IoT

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

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

Konfigurowanie aplikacji Microsoft Entra

Uwierzytelnianie przy użyciu wartości DefaultAzureCredential

Przykłady kodu

Aktualizowanie tagów bliźniaków i pożądanych właściwości

Tworzenie zapytania bliźniaczej reprezentacji urządzenia

Przykład usługi SDK

Omówienie

Tworzenie aplikacji urządzenia

Instalowanie pakietu zestawu SDK urządzenia

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