Wysyłanie i odbieranie komunikatów z chmury do urządzenia
Azure IoT Hub to w pełni zarządzana usługa, która umożliwia komunikację dwukierunkową, w tym komunikaty z chmury do urządzenia (C2D) z zaplecza rozwiązania do milionów urządzeń.
W tym artykule opisano sposób użycia zestawów SDK usługi Azure IoT do tworzenia następujących typów aplikacji:
Aplikacje urządzeń, które odbierają komunikaty z chmury do urządzenia i obsługują je z kolejki obsługi komunikatów usługi IoT Hub.
Aplikacje zaplecza, które wysyłają komunikaty z chmury do urządzenia do jednego urządzenia za pośrednictwem kolejki obsługi komunikatów usługi IoT Hub.
Ten artykuł ma na celu uzupełnienie przykładów zestawu SDK z możliwością uruchamiania, do których odwołuje się ten artykuł.
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.
Omówienie
Aby aplikacja urządzenia odbierała komunikaty z chmury do urządzenia, musi połączyć się z usługą IoT Hub, a następnie skonfigurować procedurę obsługi komunikatów w celu przetwarzania komunikatów przychodzących. Zestawy SDK urządzeń usługi Azure IoT Hub udostępniają klasy i metody, których urządzenie może używać do odbierania i obsługi komunikatów z usługi. W tym artykule omówiono kluczowe elementy dowolnej aplikacji urządzenia, która odbiera komunikaty, w tym:
- Deklarowanie obiektu klienta urządzenia
- Łączenie z usługą IoT Hub
- Pobieranie komunikatów z kolejki komunikatów usługi IoT Hub
- Przetwarzanie komunikatu i wysyłanie potwierdzenia z powrotem do usługi IoT Hub
- Konfigurowanie zasad ponawiania próby odbierania komunikatów
Aby aplikacja zaplecza wysyłała komunikaty z chmury do urządzenia, musi połączyć się z usługą IoT Hub i wysyłać komunikaty za pośrednictwem kolejki komunikatów usługi IoT Hub. Zestawy SDK usługi Azure IoT Hub udostępniają klasy i metody, których aplikacja może używać do wysyłania komunikatów do urządzeń. W tym artykule omówiono kluczowe elementy każdej aplikacji, która wysyła komunikaty do urządzeń, w tym:
- Deklarowanie obiektu klienta usługi
- Łączenie z usługą IoT Hub
- Kompilowanie i wysyłanie komunikatu
- Odbieranie opinii o dostawie
- Konfigurowanie zasad ponawiania próby wysyłania komunikatów
Omówienie kolejki komunikatów
Aby zrozumieć obsługę komunikatów z chmury na urządzenie, ważne jest, aby zrozumieć pewne podstawy dotyczące działania kolejek komunikatów urządzenia usługi IoT Hub.
Komunikaty z chmury do urządzenia wysyłane z aplikacji zaplecza rozwiązania do urządzenia IoT są kierowane za pośrednictwem usługi IoT Hub. Nie ma bezpośredniej komunikacji komunikacji równorzędnej między aplikacją zaplecza rozwiązania a urządzeniem docelowym. Usługa IoT Hub umieszcza przychodzące komunikaty w kolejce komunikatów, które są gotowe do pobrania przez docelowe urządzenia IoT.
Aby zagwarantować co najmniej jednokrotne dostarczanie komunikatów, usługa IoT Hub utrzymuje komunikaty z chmury do urządzenia w kolejkach poszczególnych urządzeń. Urządzenia muszą jawnie potwierdzić ukończenie komunikatu, zanim usługa IoT Hub usunie komunikat z kolejki. Takie podejście gwarantuje odporność na łączność i awarie urządzeń.
Gdy usługa IoT Hub umieszcza komunikat w kolejce komunikatów urządzenia, ustawia stan komunikatu na Enqueued. Gdy wątek urządzenia pobiera komunikat z kolejki, usługa IoT Hub blokuje komunikat, ustawiając stan komunikatu na Niewidoczny. Ten stan uniemożliwia innym wątkom na urządzeniu przetwarzanie tego samego komunikatu. Gdy wątek urządzenia pomyślnie ukończy przetwarzanie komunikatu, powiadamia centrum IoT Hub, a następnie usługa IoT Hub ustawia stan komunikatu na Ukończono.
Aplikacja urządzenia, która pomyślnie odbiera i przetwarza komunikat, zostanie wyświetlony komunikat Complete the message (Ukończ komunikat). Jednak w razie potrzeby urządzenie może również:
- Odrzuć komunikat, co powoduje, że usługa IoT Hub ustawiła ją na stan Utracony. Urządzenia łączące się za pośrednictwem protokołu transportu telemetrii kolejkowania komunikatów (MQTT) nie mogą odrzucać komunikatów z chmury do urządzenia.
- Porzucanie komunikatu, co powoduje, że usługa IoT Hub umieścić komunikat z powrotem w kolejce z ustawionym stanem komunikatu na wartość Enqueued. Urządzenia łączące się za pośrednictwem protokołu MQTT nie mogą porzucić komunikatów chmura-urządzenie.
Aby uzyskać więcej informacji na temat cyklu życia komunikatów chmury do urządzenia i sposobu przetwarzania komunikatów z chmury do urządzenia w usłudze IoT Hub, zobacz Wysyłanie komunikatów z chmury do urządzenia z centrum IoT Hub.
Tworzenie aplikacji urządzenia
W tej sekcji opisano sposób odbierania komunikatów z chmury do urządzenia.
Istnieją dwie opcje, których aplikacja kliencka urządzenia może używać do odbierania komunikatów:
- Wywołanie zwrotne: aplikacja urządzenia konfiguruje asynchroniczną metodę obsługi komunikatów, która jest wywoływana natychmiast po nadejściu komunikatu.
- Sondowanie: aplikacja urządzenia sprawdza nowe komunikaty usługi IoT Hub przy użyciu pętli kodu (na przykład
while
pętli lubfor
). Pętla jest wykonywana stale, sprawdzając komunikaty.
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;
Łą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
Klasa DeviceClient uwidacznia wszystkie metody wymagane do odbierania komunikatów na urządzeniu.
Podaj parametry połączenia
Podaj podstawowe parametry połączenia usługi IoT Hub i identyfikator urządzenia, aby DeviceClient
użyć metody CreateFromConnectionString. Oprócz wymaganych parametry połączenia podstawowych usługi CreateFromConnectionString
IoT Hub można przeciążyć metodę, aby uwzględnić następujące parametry opcjonalne:
transportType
- Protokół transportowy: odmiany protokołu HTTP w wersji 1, AMQP lub MQTT. Wartość domyślna toAMQP
. Aby wyświetlić wszystkie dostępne wartości, zobacz TransportType, wyliczenie.transportSettings
- Interfejs używany do definiowania różnych ustawień specyficznych dla transportu dlaDeviceClient
iModuleClient
. Aby uzyskać więcej informacji, zobacz ITransportSettings, interfejs.ClientOptions
— Opcje umożliwiające konfigurację wystąpienia klienta urządzenia lub modułu podczas inicjowania.
Ten przykład łączy się z urządzeniem przy użyciu protokołu transportowego Mqtt
.
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 doDeviceClient.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ą wypełniane w obiekcie przekazywanym auth
DeviceAuthenticationWithX509Certificate
do DeviceClient.Create
obiektu .
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:
- Uwierzytelnianie tożsamości przy użyciu certyfikatów X.509
- Samouczek: tworzenie i przekazywanie certyfikatów na potrzeby testowania
Przykłady kodu
Aby zapoznać się z przykładami pracy uwierzytelniania certyfikatu X.509 urządzenia, zobacz:
- Nawiązywanie połączenia z certyfikatem X.509
- DeviceClientX509AuthenticationE2ETests
- Projekt z przewodnikiem — bezpieczne aprowizowanie urządzeń IoT na dużą skalę za pomocą usługi IoT Hub Device Provisioning
Oddzwanianie
Aby odbierać komunikaty z chmury do urządzenia w aplikacji urządzenia, aplikacja musi połączyć się z usługą IoT Hub i skonfigurować odbiornik wywołania zwrotnego w celu przetwarzania komunikatów przychodzących. Przychodzące komunikaty do urządzenia są odbierane z kolejki komunikatów usługi IoT Hub.
Za pomocą wywołania zwrotnego aplikacja urządzenia konfiguruje metodę obsługi komunikatów przy użyciu metody SetReceiveMessageHandlerAsync. Procedura obsługi komunikatów jest wywoływana, a następnie odbierany jest komunikat. Utworzenie metody wywołania zwrotnego w celu odbierania komunikatów eliminuje konieczność ciągłego sondowania dla odebranych komunikatów.
Wywołanie zwrotne jest dostępne tylko przy użyciu następujących protokołów:
Mqtt
Mqtt_WebSocket_Only
Mqtt_Tcp_Only
Amqp
Amqp_WebSocket_Only
Amqp_Tcp_only
Opcja Http1
protokołu nie obsługuje wywołań zwrotnych, ponieważ metody zestawu SDK musiałyby mimo to sondować pod kątem odebranych komunikatów, co powoduje pokonanie reguły wywołania zwrotnego.
W tym przykładzie SetReceiveMessageHandlerAsync
konfiguruje metodę obsługi wywołania zwrotnego o nazwie OnC2dMessageReceivedAsync
, która jest wywoływana za każdym razem, gdy zostanie odebrany komunikat.
// Subscribe to receive C2D messages through a callback (which isn't supported over HTTP).
await deviceClient.SetReceiveMessageHandlerAsync(OnC2dMessageReceivedAsync, deviceClient);
Console.WriteLine($"\n{DateTime.Now}> Subscribed to receive C2D messages over callback.");
Sondowanie
Sondowanie używa funkcji ReceiveAsync do sprawdzania komunikatów.
Wywołanie metody ReceiveAsync
może przyjąć następujące formy:
ReceiveAsync()
— Przed kontynuowaniem poczekaj domyślny okres limitu czasu dla komunikatu.ReceiveAsync (Timespan)
— Odbieranie komunikatu z kolejki urządzenia przy użyciu określonego limitu czasu.ReceiveAsync (CancellationToken)
— Odbieranie komunikatu z kolejki urządzenia przy użyciu tokenu anulowania. W przypadku korzystania z tokenu anulowania domyślny okres limitu czasu nie jest używany.
W przypadku korzystania z typu transportu HTTP 1 zamiast protokołu MQTT lub AMQP ReceiveAsync
metoda zwraca natychmiast. Obsługiwany wzorzec dla komunikatów z chmury do urządzenia z protokołem HTTP 1 jest sporadycznie połączonych urządzeń, które sprawdzają komunikaty rzadko (co najmniej co 25 minut). Wysłanie większej liczby żądań HTTP 1 powoduje ograniczenie żądań w usłudze IoT Hub. Aby uzyskać więcej informacji na temat różnic między obsługą protokołów MQTT, AMQP i HTTP 1, zobacz Wskazówki dotyczące komunikacji między chmurą a urządzeniem i Wybieranie protokołu komunikacyjnego.
CompleteAsync, metoda
Gdy urządzenie otrzyma komunikat, aplikacja urządzenia wywołuje metodę CompleteAsync , aby powiadomić usługę IoT Hub o pomyślnym przetworzeniu komunikatu i bezpiecznie usunąć komunikat z kolejki urządzeń usługi IoT Hub. Urządzenie powinno wywołać tę metodę po pomyślnym zakończeniu przetwarzania niezależnie od używanego protokołu transportowego.
Porzucanie, odrzucanie lub przekroczenie limitu czasu komunikatu
W przypadku protokołów AMQP i HTTP w wersji 1, ale nie protokołu MQTT, urządzenie może również:
- Porzucanie komunikatu przez wywołanie metody AbandonAsync. Dzięki temu usługa IoT Hub zachowuje komunikat w kolejce urządzenia na potrzeby przyszłego użycia.
- Odrzuć komunikat, wywołując polecenie RejectAsync. Spowoduje to trwałe usunięcie komunikatu z kolejki urządzenia.
Jeśli wystąpi coś, co uniemożliwia ukończenie, porzucenie lub odrzucenie komunikatu przez urządzenie, usługa IoT Hub otrzyma komunikat po upływie ustalonego limitu czasu, ponownie w kolejce komunikat do dostarczenia. Z tego powodu logika przetwarzania komunikatów w aplikacji urządzenia musi być idempotentna, dzięki czemu odbieranie tego samego komunikatu wielokrotnie generuje ten sam wynik.
Aby uzyskać więcej informacji na temat cyklu życia komunikatów chmury do urządzenia i sposobu przetwarzania komunikatów z chmury do urządzenia w usłudze IoT Hub, zobacz Wysyłanie komunikatów z chmury do urządzenia z centrum IoT Hub.
Pętla sondowania
Korzystając z sondowania, aplikacja używa pętli kodu, która wielokrotnie wywołuje ReceiveAsync
metodę w celu sprawdzenia nowych komunikatów do momentu zatrzymania.
Jeśli używasz ReceiveAsync
wartości limitu czasu lub domyślnego limitu czasu, w pętli każde wywołanie ReceiveAsync
czeka na określony okres limitu czasu. Jeśli ReceiveAsync
wartość zostanie upłynął, null
zostanie zwrócona wartość, a pętla będzie kontynuowana.
Po odebraniu komunikatu obiekt Task jest zwracany przez ReceiveAsync
element , który powinien zostać przekazany do metody CompleteAsync. Wywołanie w celu CompleteAsync
powiadomienia usługi IoT Hub o usunięciu określonego komunikatu z kolejki komunikatów na podstawie parametru Task
.
W tym przykładzie pętla wywołuje do ReceiveAsync
momentu odebrania komunikatu lub zatrzymania pętli sondowania.
static bool stopPolling = false;
while (!stopPolling)
{
// Check for a message. Wait for the default DeviceClient timeout period.
using Message receivedMessage = await _deviceClient.ReceiveAsync();
// Continue if no message was received
if (receivedMessage == null)
{
continue;
}
else // A message was received
{
// Print the message received
Console.WriteLine($"{DateTime.Now}> Polling using ReceiveAsync() - received message with Id={receivedMessage.MessageId}");
PrintMessage(receivedMessage);
// Notify IoT Hub that the message was received. IoT Hub will delete the message from the message queue.
await _deviceClient.CompleteAsync(receivedMessage);
Console.WriteLine($"{DateTime.Now}> Completed C2D message with Id={receivedMessage.MessageId}.");
}
// Check to see if polling loop should end
stopPolling = ShouldPollingstop ();
}
Zasady ponawiania próby odbierania komunikatów
Zasady ponawiania komunikatów klienta urządzenia można zdefiniować przy użyciu elementu DeviceClient.SetRetryPolicy.
Limit czasu ponawiania próby komunikatu jest przechowywany we właściwości DeviceClient.OperationTimeoutInMilliseconds .
Przykład komunikatu odbierania zestawu SDK
Zestaw .NET/C# SDK zawiera przykład Odbieranie komunikatów, który zawiera metody odbierania komunikatów opisane w tej sekcji.
Tworzenie aplikacji zaplecza
W tej sekcji opisano podstawowy kod służący do wysyłania komunikatu z aplikacji zaplecza rozwiązania do urządzenia IoT przy użyciu klasy ServiceClient w zestawie SDK usługi Azure IoT dla platformy .NET. Jak wspomniano wcześniej, aplikacja zaplecza rozwiązania łączy się z usługą IoT Hub i komunikaty są wysyłane do usługi IoT Hub zakodowanej przy użyciu urządzenia docelowego. Usługa IoT Hub przechowuje komunikaty przychodzące do kolejki komunikatów, a komunikaty są dostarczane z kolejki komunikatów usługi IoT Hub do urządzenia docelowego.
Aplikacja zaplecza rozwiązania może również żądać i odbierać opinie dotyczące dostarczania komunikatu wysyłanego do usługi IoT Hub przeznaczonego do dostarczania urządzeń za pośrednictwem kolejki komunikatów.
Dodawanie pakietu 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 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
Podaj parametry połączenia
Połącz aplikację zaplecza z urządzeniem przy użyciu polecenia CreateFromConnectionString. Oprócz wymaganych parametry połączenia podstawowych usługi CreateFromConnectionString
IoT Hub można przeciążyć metodę, aby uwzględnić następujące parametry opcjonalne:
- Usługa
transportType
-Amqp
lubAmqp_WebSocket_Only
. transportSettings
— Ustawienia protokołu AMQP i serwera proxy HTTP dla klienta usługi.ServiceClientOptions
- Opcje, które umożliwiają konfigurację wystąpienia klienta usługi podczas inicjowania. Aby uzyskać więcej informacji, zobacz ServiceClientOptions.
W tym przykładzie obiekt jest ServiceClient
tworzony przy użyciu usługi IoT Hub parametry połączenia i transportu domyślnegoAmqp
.
static string connectionString = "{your IoT hub connection string}";
serviceClient = ServiceClient.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 DefaultAzureCredential
dla 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.
Wysyłanie asynchronicznego komunikatu chmury do urządzenia
Użyj metody sendAsync , aby wysłać do urządzenia komunikat asynchroniczny z aplikacji za pośrednictwem chmury (IoT Hub). Wywołanie jest wykonywane przy użyciu protokołu AMQP.
sendAsync
używa następujących parametrów:
deviceID
— identyfikator ciągu urządzenia docelowego.message
- Komunikat chmura-urządzenie. Komunikat jest typu Komunikat i można odpowiednio sformatować.timeout
— opcjonalna wartość limitu czasu. Wartość domyślna to jedna minuta, jeśli nie zostanie określona.
Ten przykład wysyła komunikat testowy do urządzenia docelowego z 10-sekundową wartością limitu czasu.
string targetDevice = "Device-1";
static readonly TimeSpan operationTimeout = TimeSpan.FromSeconds(10);
var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
await serviceClient.SendAsync(targetDevice, commandMessage, operationTimeout);
Odbieranie opinii o dostawie
Program wysyłający może zażądać potwierdzenia dostarczenia (lub wygaśnięcia) z usługi IoT Hub dla każdego komunikatu z chmury do urządzenia. Ta opcja umożliwia programowi wysyłającego korzystanie z logiki informowania, ponawiania próby lub kompensacji. Pełny opis operacji i właściwości opinii o wiadomościach opisano w sekcji Opinie o wiadomościach.
Aby otrzymywać opinie dotyczące dostarczania wiadomości:
feedbackReceiver
Tworzenie obiektu- Wysyłanie komunikatów przy użyciu parametru
Ack
- Poczekaj, aż otrzymasz opinię
Tworzenie obiektu feedbackReceiver
Wywołaj metodę GetFeedbackReceiver, aby utworzyć obiekt FeedbackReceiver. FeedbackReceiver
zawiera metody, których usługi mogą używać do wykonywania operacji odbierania opinii.
var feedbackReceiver = serviceClient.GetFeedbackReceiver();
Wysyłanie komunikatów przy użyciu parametru Ack
Każda wiadomość musi zawierać wartość właściwości potwierdzenia dostawy Ack w celu otrzymania opinii o dostarczeniu. Właściwość Ack
może być jedną z następujących wartości:
none (wartość domyślna): nie jest generowany żaden komunikat z opiniami.
Positive
: otrzymuj wiadomość zwrotną, jeśli wiadomość została ukończona.Negative
: otrzymuj wiadomość zwrotną, jeśli komunikat wygasł (lub osiągnięto maksymalną liczbę dostaw) bez ukończenia przez urządzenie.Full
: opinie dotyczące wyników iPositive
Negative
.
W tym przykładzie właściwość jest ustawiona Ack
na Full
, żądając zarówno pozytywnej, jak i negatywnej opinii dotyczącej dostarczania komunikatów dla jednej wiadomości.
var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
commandMessage.Ack = DeliveryAcknowledgement.Full;
await serviceClient.SendAsync(targetDevice, commandMessage);
Poczekaj, aż otrzymasz opinię
Zdefiniuj element CancellationToken
. Następnie w pętli wywołaj metodę ReceiveAsync wielokrotnie, sprawdzając komunikaty zwrotne dotyczące dostarczania. Każde wywołanie ReceiveAsync
czeka na limit czasu zdefiniowany dla ServiceClient
obiektu.
ReceiveAsync
Jeśli limit czasu wygaśnie bez odebranego komunikatu,ReceiveAsync
zwraca wartość ,null
a pętla będzie kontynuowana.- Jeśli zostanie odebrany komunikat z informacją zwrotną, obiekt Task zostanie zwrócony przez
ReceiveAsync
obiekt , który powinien zostać przekazany do metody CompleteAsync wraz z tokenem anulowania. Wywołanie w celuCompleteAsync
usunięcia określonego wysłanego komunikatu z kolejki komunikatów na podstawie parametruTask
. - W razie potrzeby kod odbioru może wywołać metodę AbandonAsync , aby ponownie umieścić komunikat wysyłania w kolejce.
var feedbackReceiver = serviceClient.GetFeedbackReceiver();
// Define the cancellation token.
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;
// Call ReceiveAsync, passing the token. Wait for the timout period.
var feedbackBatch = await feedbackReceiver.ReceiveAsync(token);
if (feedbackBatch == null) continue;
W tym przykładzie przedstawiono metodę obejmującą te kroki.
private async static void ReceiveFeedbackAsync()
{
var feedbackReceiver = serviceClient.GetFeedbackReceiver();
Console.WriteLine("\nReceiving c2d feedback from service");
while (true)
{
// Check for messages, wait for the timeout period.
var feedbackBatch = await feedbackReceiver.ReceiveAsync();
// Continue the loop if null is received after a timeout.
if (feedbackBatch == null) continue;
Console.ForegroundColor = ConsoleColor.Yellow;
Console.WriteLine("Received feedback: {0}",
string.Join(", ", feedbackBatch.Records.Select(f => f.StatusCode)));
Console.ResetColor();
await feedbackReceiver.CompleteAsync(feedbackBatch);
}
}
Zwróć uwagę, że ten wzorzec odbierania opinii jest podobny do wzorca używanego do odbierania komunikatów z chmury do urządzenia w aplikacji urządzenia.
Ponowne nawiązywanie połączenia klienta usługi
W przypadku wystąpienia wyjątku klient usługi przekazuje te informacje do aplikacji wywołującej. W tym momencie zaleca się sprawdzenie szczegółów wyjątku i podjęcie niezbędnych działań.
Na przykład:
- Jeśli jest to wyjątek sieciowy, możesz ponowić próbę wykonania operacji.
- Jeśli jest to wyjątek zabezpieczeń (nieautoryzowany wyjątek), sprawdź poświadczenia i upewnij się, że są aktualne.
- Jeśli jest to wyjątek ograniczania przepustowości/limitu przydziału, monitoruj i/lub modyfikuj częstotliwość wysyłania żądań lub zaktualizuj jednostkę skalowania wystąpienia centrum. Aby uzyskać szczegółowe informacje, zobacz Limity przydziału i ograniczanie przepustowości usługi IoT Hub.
Zasady ponawiania wysyłania komunikatów
Zasady ServiceClient
ponawiania komunikatów można zdefiniować przy użyciu elementu ServiceClient.SetRetryPolicy.
Przykład wysyłania komunikatu z zestawu SDK
Zestaw .NET/C# SDK zawiera przykład klienta usługi, który zawiera metody wysyłania komunikatów opisane w tej sekcji.
Tworzenie aplikacji urządzenia
W tej sekcji opisano sposób odbierania komunikatów z chmury do urządzenia przy użyciu klasy DeviceClient z zestawu AZURE IoT SDK dla języka Java.
Aby aplikacja urządzenia oparta na języku Java odbierała komunikaty z chmury do urządzenia, musi połączyć się z usługą IoT Hub, a następnie skonfigurować odbiornik wywołania zwrotnego i procedurę obsługi komunikatów w celu przetwarzania komunikatów przychodzących z usługi IoT Hub.
Importowanie bibliotek zestawu Java SDK usługi Azure IoT
Kod, do których odwołuje się ten artykuł, używa tych bibliotek zestawu SDK.
import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;
Łą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
Wystąpienie obiektu DeviceClient wymaga następujących parametrów:
- connString — parametry połączenia urządzenia IoT. Parametry połączenia jest zestawem par klucz-wartość, które są oddzielone ciągiem ";", z kluczami i wartościami oddzielonymi znakami "=". Powinien zawierać wartości dla tych kluczy:
HostName, DeviceId, and SharedAccessKey
. - Protokół transportu —
DeviceClient
połączenie może używać jednego z następujących protokołów transportu IoTHubClientProtocol .AMQP
jest najbardziej wszechstronny, umożliwia częste sprawdzanie komunikatów i umożliwia odrzucenie i anulowanie komunikatów. Protokół MQTT nie obsługuje odrzucania komunikatów ani porzucania metod:AMQPS
AMQPS_WS
HTTPS
MQTT
MQTT_WS
Na przykład:
static string connectionString = "{IOT hub device connection string}";
static protocol = IotHubClientProtocol.AMQPS;
DeviceClient client = new DeviceClient(connectionString, protocol);
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 element DeviceClient przy użyciu informacji,
ClientOptions
aby utworzyć połączenie z urządzeniem do usługi 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:
- Uwierzytelnianie tożsamości przy użyciu certyfikatów X.509
- Samouczek: tworzenie i przekazywanie certyfikatów na potrzeby testowania
Przykłady kodu
Aby zapoznać się z przykładami pracy uwierzytelniania certyfikatu X.509 urządzenia, zobacz:
Ustawianie metody wywołania zwrotnego komunikatów
Użyj metody setMessageCallback, aby zdefiniować metodę obsługi komunikatów, która jest powiadamiana o odebraniu komunikatu z usługi IoT Hub.
setMessageCallback
zawiera następujące parametry:
callback
- Nazwa metody wywołania zwrotnego. Może to byćnull
.context
- Opcjonalny kontekst typuobject
. Użyjnull
polecenia , jeśli nie określono.
W tym przykładzie callback
metoda o nazwie MessageCallback
bez parametru kontekstu jest przekazywana do setMessageCallback
.
client.setMessageCallback(new MessageCallback(), null);
Tworzenie procedury obsługi wywołania zwrotnego komunikatów
Procedura obsługi komunikatów wywołania zwrotnego odbiera i przetwarza przychodzący komunikat przekazywany z kolejki komunikatów usługi IoT Hub.
W tym przykładzie program obsługi komunikatów przetwarza komunikat przychodzący, a następnie zwraca element IotHubMessageResult.COMPLETE. Wartość zwracana IotHubMessageResult.COMPLETE
powiadamia usługę IoT Hub o pomyślnym przetworzeniu komunikatu i bezpiecznym usunięciu komunikatu z kolejki urządzenia. Urządzenie powinno zostać zwrócone IotHubMessageResult.COMPLETE
po pomyślnym zakończeniu przetwarzania, powiadamiając usługę IoT Hub o tym, że komunikat powinien zostać usunięty z kolejki komunikatów, niezależnie od używanego protokołu.
protected static class MessageCallback implements com.microsoft.azure.sdk.iot.device.MessageCallback
{
public IotHubMessageResult onCloudToDeviceMessageReceived(Message msg, Object context)
{
System.out.println(
"Received message with content: " + new String(msg.getBytes(), Message.DEFAULT_IOTHUB_MESSAGE_CHARSET));
// Notify IoT Hub that the message
return IotHubMessageResult.COMPLETE;
}
}
Opcje porzucania i odrzucania komunikatów
Chociaż duża liczba przychodzących komunikatów na urządzeniu powinna zostać pomyślnie odebrana i spowodować IotHubMessageResult.COMPLETE
, że konieczne może być porzucenie lub odrzucenie komunikatu.
- W przypadku protokołów AMQP i HTTPS, ale nie MQTT, aplikacja może:
IotHubMessageResult.ABANDON
komunikat. Usługa IoT Hub ponownie zapisuje ją w kolejce i wysyła ją ponownie później.IotHubMessageResult.REJECT
komunikat. Usługa IoT Hub nie kolejkuje ponownie komunikatu i trwale usuwa komunikat z kolejki komunikatów.
- Klienci korzystający z
MQTT
programu lubMQTT_WS
nie mogąABANDON
aniREJECT
komunikatów.
Jeśli wystąpi coś, co uniemożliwia ukończenie, porzucenie lub odrzucenie komunikatu przez urządzenie, usługa IoT Hub otrzyma komunikat po upływie ustalonego limitu czasu, ponownie w kolejce komunikat do dostarczenia. Z tego powodu logika przetwarzania komunikatów w aplikacji urządzenia musi być idempotentna, dzięki czemu odbieranie tego samego komunikatu wielokrotnie generuje ten sam wynik.
Aby uzyskać więcej informacji na temat cyklu życia komunikatów chmury do urządzenia i sposobu przetwarzania komunikatów z chmury do urządzenia w usłudze IoT Hub, zobacz Wysyłanie komunikatów z chmury do urządzenia z centrum IoT Hub.
Uwaga
Jeśli używasz protokołu HTTPS zamiast protokołu MQTT lub AMQP jako transportu, wystąpienie DeviceClient sprawdza, czy komunikaty z usługi IoT Hub są rzadko (co najmniej co 25 minut). 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 metody wywołania zwrotnego stanu komunikatu
Aplikacja może użyć metody registerConnectionStatusChangeCallback, aby zarejestrować metodę wywołania zwrotnego, która ma zostać wykonana po zmianie stanu połączenia urządzenia. Dzięki temu aplikacja może wykryć zaniżone połączenie komunikatów i spróbować ponownie nawiązać połączenie.
W tym przykładzie IotHubConnectionStatusChangeCallbackLogger
jest rejestrowana jako metoda zmiany stanu połączenia wywołania zwrotnego.
client.registerConnectionStatusChangeCallback(new IotHubConnectionStatusChangeCallbackLogger(), new Object());
Wywołanie zwrotne jest wyzwalane i przekazywane ConnectionStatusChangeContext
obiekt.
Wywołaj metodę connectionStatusChangeContext.getNewStatus()
, aby uzyskać bieżący stan połączenia.
IotHubConnectionStatus status = connectionStatusChangeContext.getNewStatus();
Zwrócony stan połączenia może być jedną z następujących wartości:
IotHubConnectionStatus.DISCONNECTED
IotHubConnectionStatus.DISCONNECTED_RETRYING
IotHubConnectionStatus.CONNECTED
Wywołaj metodę connectionStatusChangeContext.getNewStatusReason()
, aby uzyskać przyczynę zmiany stanu połączenia.
IotHubConnectionStatusChangeReason statusChangeReason = connectionStatusChangeContext.getNewStatusReason();
Wywołaj metodę connectionStatusChangeContext.getCause()
, aby znaleźć przyczynę zmiany stanu połączenia. getCause()
może zwrócić informację null
, jeśli nie są dostępne żadne informacje.
Throwable throwable = connectionStatusChangeContext.getCause();
if (throwable != null)
throwable.printStackTrace();
Zobacz przykład HandleMessages wymieniony w sekcji przykładowej komunikatu odbieranego przez zestaw SDK w tym artykule, aby zapoznać się z kompletnym przykładem przedstawiającym sposób wyodrębniania stanu zmiany stanu stanu zmiany stanu stanu zmiany stanu stanu zmiany stanu zmiany stanu stanu zmiany stanu stanu i przyczyny zmiany stanu oraz kontekstu stanu urządzenia.
Otwieranie połączenia między urządzeniem a usługą IoT Hub
Użyj opcji otwórz , aby utworzyć połączenie między urządzeniem i usługą IoT Hub. Urządzenie może teraz asynchronicznie wysyłać i odbierać komunikaty do i z usługi IoT Hub. Jeśli klient jest już otwarty, metoda nic nie robi.
client.open(true);
Przykład komunikatu odbierania zestawu SDK
HandleMessages: przykładowa aplikacja urządzenia dołączona do zestawu SDK usługi Microsoft Azure IoT dla języka Java, która łączy się z centrum IoT i odbiera komunikaty z chmury do urządzenia.
Tworzenie aplikacji zaplecza
W tej sekcji opisano sposób wysyłania komunikatu z chmury do urządzenia przy użyciu klasy ServiceClient z zestawu AZURE IoT SDK dla języka Java. Aplikacja zaplecza rozwiązania łączy się z usługą IoT Hub i komunikaty są wysyłane do usługi IoT Hub zakodowanej przy użyciu urządzenia docelowego. Usługa IoT Hub przechowuje komunikaty przychodzące do kolejki komunikatów, a komunikaty są dostarczane z kolejki komunikatów usługi IoT Hub do urządzenia docelowego.
Aplikacja zaplecza rozwiązania może również żądać i odbierać opinie dotyczące dostarczania komunikatu wysyłanego do usługi IoT Hub przeznaczonego do dostarczania urządzeń za pośrednictwem kolejki komunikatów.
Dodawanie instrukcji zależności
Dodaj zależność, aby używać pakietu iothub-java-service-client w aplikacji do komunikowania się z usługą centrum IoT:
<dependency>
<groupId>com.microsoft.azure.sdk.iot</groupId>
<artifactId>iot-service-client</artifactId>
<version>1.7.23</version>
</dependency>
Dodawanie instrukcji importu
Dodaj te instrukcje importowania , aby użyć zestawu SDK java usługi Azure IoT i procedury obsługi wyjątków.
import com.microsoft.azure.sdk.iot.service.*;
import java.io.IOException;
import java.net.URISyntaxException;
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
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
Definiowanie protokołu połączenia
Użyj elementu IotHubServiceClientProtocol , aby zdefiniować protokół warstwy aplikacji używany przez klienta usługi do komunikowania się z usługą IoT Hub.
IotHubServiceClientProtocol
akceptuje tylko wyliczenie AMQPS
lub AMQPS_WS
.
IotHubServiceClientProtocol protocol = IotHubServiceClientProtocol.AMQPS;
Tworzenie obiektu ServiceClient
Utwórz obiekt ServiceClient, podając parametry połączenia i protokół usługi Iot Hub.
String connectionString = "{yourhubconnectionstring}";
ServiceClient serviceClient (connectionString, protocol);
Otwieranie połączenia między aplikacją a usługą IoT Hub
otwórz połączenie nadawcy AMQP. Ta metoda tworzy połączenie między aplikacją a usługą IoT Hub.
serviceClient.open();
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 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
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
.
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 identyfikator dzierżawy klucza tajnego klienta, identyfikator klienta i wartości wpisów tajnych klienta jako zmienne środowiskowe. Po utworzeniu TokenCredential
elementu przekaż go do elementu ServiceClient lub innego konstruktora jako parametru "credential".
W tym przykładzie DefaultAzureCredentialBuilder
próbuje uwierzytelnić połączenie z listy opisanej w artykule 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 elementu 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 klasy ServiceClient lub innego konstruktora jako parametru "credential".
W tym przykładzie do zmiennych środowiskowych dodano wartości klucza tajnego klienta rejestracji aplikacji Firmy Microsoft, identyfikatora klienta i identyfikatora dzierżawy. Te zmienne środowiskowe są używane przez ClientSecretCredentialBuilder
program do kompilowania 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:
- AuthorizationCodeCredential
- AzureCliCredential
- AzureDeveloperCliCredential
- AzurePipelinesCredential
- ChainedTokenCredential
- ClientAssertionCredential
- ClientCertificateCredential
- DeviceCodeCredential
- EnvironmentCredential
- InteractiveBrowserCredential
- ManagedIdentityCredential
- OnBehalfOfCredential
Przykłady kodu
Aby zapoznać się z roboczymi przykładami uwierzytelniania usługi Entra firmy Microsoft, zobacz Przykład uwierzytelniania opartego na rolach.
Otwieranie odbiornika opinii w celu uzyskania opinii dotyczącej dostarczania komunikatów
Możesz użyć elementu FeedbackReceiver , aby uzyskać wysyłanie wiadomości do opinii usługi IoT Hub. A FeedbackReceiver
jest wyspecjalizowanym odbiornikiem, którego Receive
metoda zwraca wartość FeedbackBatch
zamiast Message
.
W tym przykładzie FeedbackReceiver
obiekt jest tworzony, a instrukcja jest wywoływana w open()
celu oczekiwania na opinię.
FeedbackReceiver feedbackReceiver = serviceClient
.getFeedbackReceiver();
if (feedbackReceiver != null) feedbackReceiver.open();
Dodawanie właściwości komunikatu
Opcjonalnie możesz użyć właściwości setProperties , aby dodać właściwości komunikatu. Te właściwości są uwzględniane w komunikacie wysyłanym do urządzenia i mogą zostać wyodrębnione przez aplikację urządzenia po otrzymaniu.
Map<String, String> propertiesToSend = new HashMap<String, String>();
propertiesToSend.put(messagePropertyKey,messagePropertyKey);
messageToSend.setProperties(propertiesToSend);
Tworzenie i wysyłanie komunikatu asynchronicznego
Obiekt Message przechowuje wiadomość do wysłania. W tym przykładzie jest dostarczany komunikat "Chmura do urządzenia".
Użyj polecenia setDeliveryAcknowledgement , aby zażądać dostarczenia/nie dostarczenia do potwierdzenia kolejki komunikatów usługi IoT Hub. W tym przykładzie żądane potwierdzenie to Full
, dostarczone lub nie dostarczone.
Użyj polecenia SendAsync , aby wysłać asynchroniczny komunikat z klienta do urządzenia. Alternatywnie można użyć Send
metody (nie asynchronicznej), ale ta funkcja jest synchronizowana wewnętrznie, tak aby tylko jedna operacja wysyłania mogła być dozwolona naraz. Komunikat jest dostarczany z aplikacji do usługi IoT Hub. Usługa IoT Hub umieszcza komunikat w kolejce komunikatów gotowy do dostarczenia do urządzenia docelowego.
Message messageToSend = new Message("Cloud to device message.");
messageToSend.setDeliveryAcknowledgementFinal(DeliveryAcknowledgement.Full);
serviceClient.sendAsync(deviceId, messageToSend);
Odbieranie opinii dotyczącej dostarczania komunikatów
Po wysłaniu komunikatu z aplikacji aplikacja może wywołać metodę odbierania z wartością limitu czasu lub bez tego limitu czasu. Jeśli nie podano wartości limitu czasu, zostanie użyty domyślny limit czasu. Spowoduje to powrót obiektu FeedbackBatch , który zawiera właściwości opinii dotyczącej dostarczania komunikatów, które można zbadać.
W tym przykładzie tworzony jest odbiornik i wywołuje metodę FeedbackBatch
getEnqueuedTimeUtc, wyświetlaną w kolejce komunikatu.
FeedbackBatch feedbackBatch = feedbackReceiver.receive(10000);
if (feedbackBatch != null) {
System.out.println("Message feedback received, feedback time: "
+ feedbackBatch.getEnqueuedTimeUtc().toString());
}
Przykłady wiadomości wysyłanych przez zestaw SDK
Istnieją dwa przykłady wiadomości wysyłania:
Tworzenie aplikacji urządzenia
W tej sekcji opisano sposób odbierania komunikatów z chmury do urządzenia.
Klasa IoTHubDeviceClient zawiera metody tworzenia synchronicznego połączenia z urządzenia do usługi Azure IoT Hub i odbierania komunikatów z usługi IoT Hub.
Aby tworzyć aplikacje urządzeń, należy zainstalować bibliotekę azure-iot-device .
pip install azure-iot-device
Aby aplikacja urządzenia oparta na języku Python odbierała komunikaty z chmury do urządzenia, musi połączyć się z usługą IoT Hub, a następnie skonfigurować procedurę obsługi komunikatów zwrotnych w celu przetwarzania komunikatów przychodzących z usługi IoT Hub.
Instrukcja importowania urządzenia
Dodaj ten kod, aby zaimportować IoTHubDeviceClient
funkcje 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
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
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 połączenie , 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
- Wywołanie połączenia w celu nawiązania połączenia z klientem 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:
- Uwierzytelnianie tożsamości przy użyciu certyfikatów X.509
- Samouczek: tworzenie i przekazywanie certyfikatów na potrzeby testowania
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.
Obsługa ponownego nawiązywania połączenia
IoTHubDeviceClient
domyślnie podejmie próbę ponownego opublikowania porzuconego połączenia. Zachowanie ponownego IoTHubDeviceClient
łączenia podlega connection_retry i connection_retry_interval
parametrom.
Tworzenie procedury obsługi komunikatów
Utwórz funkcję obsługi komunikatów w celu przetwarzania przychodzących komunikatów na urządzeniu. Zostanie to przypisane przez on_message_received
(następny krok) jako procedurę obsługi komunikatów wywołania zwrotnego.
W tym przykładzie message_handler
jest wywoływana po odebraniu komunikatu. Właściwości komunikatu (.items
) są drukowane w konsoli przy użyciu pętli .
def message_handler(message):
global RECEIVED_MESSAGES
RECEIVED_MESSAGES += 1
print("")
print("Message received:")
# print data from both system and application (custom) properties
for property in vars(message).items():
print (" {}".format(property))
print("Total calls received: {}".format(RECEIVED_MESSAGES))
Przypisywanie programu obsługi komunikatów
Użyj metody on_message_received, aby przypisać metodę obsługi komunikatów.
W tym przykładzie metoda obsługi komunikatów o nazwie message_handler
jest dołączona do IoTHubDeviceClient
client
obiektu. Obiekt client
czeka na odebranie komunikatu z chmury do urządzenia z usługi IoT Hub. Ten kod czeka do 300 sekund (5 minut) na komunikat lub kończy działanie w przypadku naciśnięcia klawiatury.
try:
# Attach the handler to the client
client.on_message_received = message_handler
while True:
time.sleep(300)
except KeyboardInterrupt:
print("IoT Hub C2D Messaging device sample stopped")
finally:
# Graceful exit
print("Shutting down IoT Hub Client")
client.shutdown()
Przykład komunikatu odbierania zestawu SDK
Odbieranie komunikatów — odbieranie komunikatów z chmury do urządzenia (C2D) wysyłanych z usługi Azure IoT Hub do urządzenia.
Tworzenie aplikacji zaplecza
W tej sekcji opisano sposób wysyłania komunikatu z chmury do urządzenia. Aplikacja zaplecza rozwiązania łączy się z usługą IoT Hub i komunikaty są wysyłane do usługi IoT Hub zakodowanej przy użyciu urządzenia docelowego. Usługa IoT Hub przechowuje komunikaty przychodzące do kolejki komunikatów, a komunikaty są dostarczane z kolejki komunikatów usługi IoT Hub do urządzenia docelowego.
Klasa IoTHubRegistryManager uwidacznia wszystkie metody wymagane do utworzenia aplikacji zaplecza w celu interakcji z komunikatami z chmury do urządzenia z usługi. Aby tworzyć aplikacje usługi zaplecza, należy zainstalować bibliotekę azure-iot-hub .
pip install azure-iot-hub
Importowanie obiektu IoTHubRegistryManager
Dodaj następującą import
instrukcję. IoTHubRegistryManager zawiera interfejsy API dla operacji menedżera rejestru usługi IoT Hub.
from azure.iot.hub import IoTHubRegistryManager
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.
Na przykład:
IoTHubConnectionString = "{IoT hub service connection string}"
registry_manager = IoTHubRegistryManager.from_connection_string(IoTHubConnectionString)
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 DefaultAzureCredential
dla 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.
Kompilowanie i wysyłanie komunikatu
Użyj send_c2d_message , aby wysłać komunikat za pośrednictwem chmury (IoT Hub) do urządzenia.
send_c2d_message
używa następujących parametrów:
deviceID
— identyfikator ciągu urządzenia docelowego.message
- Komunikat chmura-urządzenie. Komunikat jest typustr
(ciąg).properties
- Opcjonalna kolekcja właściwości typudict
. Właściwości mogą zawierać właściwości aplikacji i właściwości systemu. Domyślna wartość to{}
.
Ten przykład wysyła komunikat testowy do urządzenia docelowego.
# define the device ID
deviceID = "Device-1"
# define the message
message = "{\"c2d test message\"}"
# include optional properties
props={}
props.update(messageId = "message1")
props.update(prop1 = "test property-1")
props.update(prop1 = "test property-2")
prop_text = "Test message"
props.update(testProperty = prop_text)
# send the message through the cloud (IoT Hub) to the device
registry_manager.send_c2d_message(deviceID, message, properties=props)
Przykład wysyłania komunikatu z zestawu SDK
Zestaw SDK usługi Azure IoT dla języka Python udostępnia działający przykład aplikacji usługi, która demonstruje sposób wysyłania komunikatu z chmury do urządzenia. Aby uzyskać więcej informacji, zobacz send_message.py pokazano , jak wysyłać komunikat z chmury do urządzenia.
Tworzenie aplikacji urządzenia
W tej sekcji opisano sposób odbierania komunikatów z chmury do urządzenia przy użyciu pakietu azure-iot-device w zestawie SDK usługi Azure IoT dla Node.js.
Aby aplikacja urządzenia oparta na Node.js odbierała komunikaty z chmury do urządzenia, musi połączyć się z usługą IoT Hub, a następnie skonfigurować odbiornik wywołania zwrotnego i procedurę obsługi komunikatów w celu przetwarzania komunikatów przychodzących z usługi IoT Hub. Aplikacja urządzenia powinna również mieć możliwość wykrywania rozłączeń i obsługi ich w przypadku przerwania połączenia komunikatów urządzenia z usługą IoT Hub.
Instalowanie pakietów zestawu SDK
Pakiet azure-iot-device zawiera obiekty interfejsu z urządzeniami IoT. 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
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 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. Dodajx509=true
do parametry połączenia, aby wskazać, że certyfikat został dodany do elementuDeviceClientOptions
. 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
Skonfiguruj zmienną JSON ze szczegółami certyfikatu i przekaż ją do elementu DeviceClientOptions.
Wywołaj metodę setOptions , aby dodać certyfikat I klucz X.509 (i opcjonalnie hasło) do transportu klienta.
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:
- Uwierzytelnianie tożsamości przy użyciu certyfikatów X.509
- Tworzenie i przekazywanie certyfikatów na potrzeby testowania
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
Wybieranie protokołu transportowego
Obiekt Client
obsługuje następujące protokoły:
Amqp
Http
— W przypadku korzystania zHttp
usługiClient
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ą a urządzeniem i Wybieranie protokołu komunikacyjnego.
W tym przykładzie protokół AMQP jest przypisywany do zmiennej Protocol
. Ta zmienna Protokołu jest przekazywana do Client.fromConnectionString
metody w sekcji Dodawanie parametry połączenia tego artykułu.
const Protocol = require('azure-iot-device-mqtt').Amqp;
Możliwości uzupełniania, odrzucania i porzucania komunikatów
Metody uzupełniania komunikatów, odrzucania i porzucania mogą być używane w zależności od wybranego protokołu.
Protokół AMQP i HTTP
Transporty PROTOKOŁU AMQP i HTTP mogą zakończyć, odrzucić lub porzucić komunikat:
- Ukończono — aby ukończyć komunikat, usługa, która wysłała komunikat z chmury do urządzenia, zostanie powiadomiona o odebraniu komunikatu. Usługa IoT Hub usuwa komunikat z kolejki komunikatów. Metoda przyjmuje formę
client.complete(message, callback function)
. - Odrzuć — aby odrzucić komunikat, usługa, która wysłała komunikat z chmury do urządzenia, zostanie powiadomiona, że komunikat nie jest przetwarzany przez urządzenie. Usługa IoT Hub trwale usuwa komunikat z kolejki urządzenia. Metoda przyjmuje formę
client.reject(message, callback function)
. - Porzuć — aby porzucić komunikat, usługa IoT Hub natychmiast spróbuje wysłać ją ponownie. Usługa IoT Hub zachowuje komunikat w kolejce urządzenia na potrzeby przyszłego użycia. Metoda przyjmuje formę
client.abandon(message, callback function)
.
MQTT
Protokół MQTT nie obsługuje funkcji uzupełniania, odrzucania ani porzucania komunikatów. Zamiast tego protokół MQTT domyślnie akceptuje komunikat i komunikat jest usuwany z kolejki komunikatów usługi IoT Hub.
Próby ponownego dostarczenia
Jeśli wystąpi coś, co uniemożliwia ukończenie, porzucenie lub odrzucenie komunikatu przez urządzenie, usługa IoT Hub otrzyma komunikat po upływie ustalonego limitu czasu, ponownie w kolejce komunikat do dostarczenia. Z tego powodu logika przetwarzania komunikatów w aplikacji urządzenia musi być idempotentna, dzięki czemu odbieranie tego samego komunikatu wielokrotnie generuje ten sam wynik.
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 — parametry połączenia urządzenia.
- transportCtor — protokół transportowy.
W tym przykładzie użyto Amqp
protokołu transportu:
const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);
Tworzenie przychodzącej procedury obsługi komunikatów
Procedura obsługi komunikatów jest wywoływana dla każdego komunikatu przychodzącego.
Po pomyślnym odebraniu komunikatu, jeśli używasz protokołu AMQP lub transportu HTTP, wywołaj metodę client.complete
, aby poinformować usługę IoT Hub, że komunikat można usunąć z kolejki komunikatów.
Na przykład ta procedura obsługi komunikatów drukuje identyfikator komunikatu i treść komunikatu do konsoli, a następnie wywołuje funkcję client.complete
powiadamiania usługi IoT Hub o przetworzeniu komunikatu i bezpiecznym usunięciu go z kolejki urządzenia. Wywołanie complete
polecenia nie jest wymagane, jeśli używasz transportu MQTT i można go pominąć. Do transportu protokołu AMQP lub HTTPS jest wymagane wywołaniecomplete
.
function messageHandler(msg) {
console.log('Id: ' + msg.messageId + ' Body: ' + msg.data);
client.complete(msg, printResultFor('completed'));
}
Tworzenie procedury obsługi rozłączania połączenia
Program obsługi rozłączania jest wywoływany po rozłączeniu połączenia. Procedura obsługi rozłączania jest przydatna do implementowania kodu ponownego nawiązywania połączenia.
Ten przykład przechwytuje i wyświetla komunikat o błędzie rozłączenia w konsoli.
function disconnectHandler() {
clearInterval(sendInterval);
sendInterval = null;
client.open().catch((err) => {
console.error(err.message);
});
}
Dodawanie odbiorników zdarzeń
Te odbiorniki zdarzeń można określić przy użyciu metody .on .
- Procedura obsługi połączeń
- Procedura obsługi błędów
- Rozłącz program obsługi
- Procedura obsługi komunikatów
W tym przykładzie przedstawiono wcześniej zdefiniowane programy obsługi komunikatów i rozłączania.
client.on('connect', connectHandler);
client.on('error', errorHandler);
client.on('disconnect', disconnectHandler);
client.on('message', messageHandler);
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)
polecenia , aby przechwycić błąd i wywołać kod procedury obsługi.
Na przykład:
client.open()
.catch((err) => {
console.error('Could not connect: ' + err.message);
});
Przykłady urządzeń z zestawem SDK
Zestaw SDK usługi Azure IoT dla Node.js udostępnia działający przykład aplikacji urządzenia obsługującej odbieranie komunikatów. Aby uzyskać więcej informacji, zobacz:
simple_sample_device — aplikacja urządzenia, która łączy się z centrum IoT Hub i odbiera komunikaty z chmury do urządzenia.
Tworzenie aplikacji zaplecza
W tej sekcji opisano sposób wysyłania komunikatu z chmury do urządzenia. Jak wspomniano wcześniej, aplikacja zaplecza rozwiązania łączy się z usługą IoT Hub i komunikaty są wysyłane do usługi IoT Hub zakodowanej przy użyciu urządzenia docelowego. Usługa IoT Hub przechowuje komunikaty przychodzące do kolejki komunikatów, a komunikaty są dostarczane z kolejki komunikatów usługi IoT Hub do urządzenia docelowego.
Aplikacja zaplecza rozwiązania może również żądać i odbierać opinie dotyczące dostarczania komunikatu wysyłanego do usługi IoT Hub przeznaczonego do dostarczania urządzeń za pośrednictwem kolejki komunikatów.
Instalowanie pakietu zestawu SDK usługi
Pakiet azure-iothub zawiera obiekty interfejsu z usługą IoT Hub. W tym artykule opisano Client
kod klasy, który wysyła komunikat z aplikacji do urządzenia za pośrednictwem usługi IoT Hub.
Uruchom to polecenie, aby zainstalować usługę azure-iothub na maszynie deweloperskiej:
npm install azure-iothub --save
Ładowanie klienta i modułów komunikatów
Zadeklaruj Client
Client
obiekt przy użyciu klasy z azure-iothub
pakietu.
Zadeklaruj Message
Message
obiekt przy użyciu klasy z azure-iot-common
pakietu.
'use strict';
var Client = require('azure-iothub').Client;
var Message = require('azure-iot-common').Message;
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.
W tym przykładzie serviceClient
obiekt jest tworzony z typem Amqp
transportu.
var connectionString = '{IoT hub device connection string}';
var serviceClient = Client.fromConnectionString(connectionString,`Amqp`);
Otwieranie połączenia klienta
Wywołaj metodę Client
open , aby otworzyć połączenie między aplikacją a usługą IoT Hub.
open
może być wywoływany z funkcją wywołania zwrotnego wywoływaną po zakończeniu operacji lub bez określania open
funkcji wywołania zwrotnego.
W tym przykładzie open
metoda zawiera opcjonalną err
funkcję wywołania zwrotnego otwartego połączenia. Jeśli wystąpi błąd otwierania, zwracany jest obiekt błędu. Jeśli otwarte połączenie zakończy się pomyślnie, null
zostanie zwrócona wartość wywołania zwrotnego.
serviceClient.open(function (err)
if (err)
console.error('Could not connect: ' + err.message);
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:
- Wprowadzenie do uwierzytelniania użytkowników na platformie Azure
- Biblioteka klienta tożsamości platformy Azure dla języka JavaScript
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 prefiksuhttps://
. Na przykładMyAzureDomain.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.
Tworzenie komunikatu
Obiekt komunikatu zawiera asynchroniczny komunikat chmura-urządzenie. Funkcja komunikatów działa tak samo jak w przypadku protokołu AMQP, MQTT i HTTP.
Obiekt komunikatu obsługuje kilka właściwości, w tym te właściwości. Zobacz właściwości komunikatu, aby uzyskać pełną listę.
ack
— Przekazywanie opinii. Opisane w następnej sekcji.properties
- Mapa zawierająca klucze ciągów i wartości do przechowywania niestandardowych właściwości komunikatów.- messageId — służy do korelowania komunikacji dwukierunkowej.
Dodaj treść komunikatu po utworzeniu wystąpienia obiektu komunikatu. W tym przykładzie 'Cloud to device message.'
zostanie dodany komunikat.
var message = new Message('Cloud to device message.');
message.ack = 'full';
message.messageId = "My Message ID";
Potwierdzenie dostarczenia
Program wysyłający może zażądać potwierdzenia dostarczenia (lub wygaśnięcia) z usługi IoT Hub dla każdego komunikatu z chmury do urządzenia. Ta opcja umożliwia programowi wysyłającego korzystanie z logiki informowania, ponawiania próby lub kompensacji. Pełny opis operacji i właściwości opinii o wiadomościach opisano w sekcji Opinie o wiadomościach.
Każda wiadomość, która ma otrzymywać opinie o wiadomościach, musi zawierać wartość właściwości potwierdzenia dostarczenia ack . Właściwość ack
może być jedną z następujących wartości:
none (wartość domyślna): nie jest generowany żaden komunikat z opiniami.
sent
: otrzymuj wiadomość zwrotną, jeśli wiadomość została ukończona.: otrzymuj wiadomość zwrotną, jeśli komunikat wygasł (lub osiągnięto maksymalną liczbę dostaw) bez ukończenia przez urządzenie.
full
: opinia dotycząca zarówno wysłanych, jak i nie wysłanych wyników.
W tym przykładzie właściwość jest ustawiona ack
na full
, żądając zarówno wysłanej, jak i nie wysłanej opinii dotyczącej dostarczania komunikatów dla jednej wiadomości.
message.ack = 'full';
Łączenie odbiorcy opinii o wiadomościach
Funkcja wywołania zwrotnego odbiorcy komunikatów jest połączona z funkcją Client
getFeedbackReceiver.
Odbiorca opinii o wiadomościach otrzymuje dwa argumenty:
- Obiekt błędu (może mieć wartość null)
- Obiekt AmqpReceiver — emituje zdarzenia, gdy nowe komunikaty opinii są odbierane przez klienta.
Ta przykładowa funkcja odbiera i wyświetla komunikat z informacją zwrotną do konsoli.
function receiveFeedback(err, receiver){
receiver.on('message', function (msg) {
console.log('Feedback message:')
console.log(msg.getData().toString('utf-8'));
});
}
Ten kod łączy funkcję wywołania zwrotnego receiveFeedback
opinii z obiektem usługi Client
przy użyciu polecenia getFeedbackReceiver
.
serviceClient.getFeedbackReceiver(receiveFeedback);
Definiowanie procedury obsługi wyników uzupełniania komunikatów
Funkcja wywołania zwrotnego wysyłania komunikatów jest wywoływana po wysłaniu każdego komunikatu.
Ta przykładowa funkcja wyświetla wyniki operacji komunikatu send
w konsoli. W tym przykładzie printResultFor
funkcja jest dostarczana jako parametr send
funkcji opisanej w następnej sekcji.
function printResultFor(op) {
return function printResult(err, res) {
if (err) console.log(op + ' error: ' + err.toString());
if (res) console.log(op + ' status: ' + res.constructor.name);
};
}
Wysyłanie wiadomości
Użyj funkcji send, aby wysłać asynchroniczny komunikat z chmury do urządzenia do aplikacji urządzenia za pośrednictwem usługi IoT Hub.
send
obsługuje następujące parametry:
- deviceID — identyfikator urządzenia docelowego.
- message — treść komunikatu do wysłania na urządzenie.
- gotowe — opcjonalna funkcja do wywołania po zakończeniu operacji. Gotowe jest wywoływane z dwoma argumentami:
- Obiekt błędu (może mieć wartość null).
- obiekt odpowiedzi specyficzny dla transportu przydatny do rejestrowania lub debugowania.
Ten kod wywołuje metodę send
wysyłania komunikatu z chmury do urządzenia do aplikacji urządzenia za pośrednictwem usługi IoT Hub. Funkcja printResultFor
wywołania zwrotnego zdefiniowana w poprzedniej sekcji odbiera informacje o potwierdzeniu dostarczania.
var targetDevice = '{device ID}';
serviceClient.send(targetDevice, message, printResultFor('send'));
W tym przykładzie pokazano, jak wysłać komunikat do urządzenia i obsłużyć komunikat opinii, gdy urządzenie potwierdzi komunikat z chmury do urządzenia:
serviceClient.open(function (err) {
if (err) {
console.error('Could not connect: ' + err.message);
} else {
console.log('Service client connected');
serviceClient.getFeedbackReceiver(receiveFeedback);
var message = new Message('Cloud to device message.');
message.ack = 'full';
message.messageId = "My Message ID";
console.log('Sending message: ' + message.getData());
serviceClient.send(targetDevice, message, printResultFor('send'));
}
});
Przykład wysyłania komunikatu z zestawu SDK
Zestaw SDK usługi Azure IoT dla Node.js udostępnia działające przykłady aplikacji usługi obsługującej zadania wysyłania komunikatów. Aby uzyskać więcej informacji, zobacz:
send_c2d_message.js — wysyłanie komunikatów C2D do urządzenia za pośrednictwem usługi IoT Hub.
Zasady ponownego łączenia połączeń
W tym artykule nie przedstawiono zasad ponawiania próby komunikatów dla urządzenia z połączeniem usługi IoT Hub lub aplikacją zewnętrzną z połączeniem usługi IoT Hub. W kodzie produkcyjnym należy zaimplementować zasady ponawiania połączeń zgodnie z opisem w temacie Zarządzanie ponownymi połączeniami urządzeń w celu tworzenia odpornych aplikacji.
Czas przechowywania komunikatów, próby ponawiania prób i maksymalna liczba dostaw
Zgodnie z opisem w artykule Wysyłanie komunikatów z chmury do urządzenia z usługi IoT Hub można wyświetlać i konfigurować wartości domyślne dla następujących wartości komunikatów przy użyciu opcji konfiguracji usługi IoT Hub w portalu lub interfejsu wiersza polecenia platformy Azure. Te opcje konfiguracji mogą mieć wpływ na dostarczanie komunikatów i opinie.
- Domyślny czas wygaśnięcia (czas wygaśnięcia) — czas, przez jaki komunikat jest dostępny dla urządzenia do użytku, zanim wygaśnie przez usługę IoT Hub.
- Czas przechowywania opinii — czas, przez jaki usługa IoT Hub zachowuje opinię na temat wygaśnięcia lub dostarczania komunikatów z chmury do urządzenia.
- Liczba prób dostarczenia komunikatu z chmury do urządzenia przez usługę IoT Hub.