Wysyłanie i odbieranie komunikatów z chmury do urządzenia

2025-06-23

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ą i obsługują komunikaty z kolejki wiadomości w IoT Hub, przesyłane z chmury do urządzenia.
Aplikacje zaplecza, które wysyłają komunikaty z chmury 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 i rozmiaru 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
Tworzenie i wysyłanie wiadomości
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 punkt-do-punktu 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, IoT Hub przechowuje komunikaty z chmury do urządzenia w kolejkach dla 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 działający na urządzeniu pobiera komunikat z kolejki, usługa IoT Hub blokuje komunikat, ustawiając jego stan 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, ukończy komunikat. Jednak w razie potrzeby urządzenie może również:

Odrzuć wiadomość, co powoduje, że IoT Hub ustawia ją w stanie listu martwego. 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.
Porzuć komunikat, co powoduje, że usługa IoT Hub umieszcza komunikat z powrotem w kolejce ze stanem Enqueued. Urządzenia łączące się za pośrednictwem protokołu MQTT nie mogą zrezygnować z komunikatów typu chmura-do-urządzenia.

Aby uzyskać więcej informacji na temat cyklu życia komunikatów z chmury do urządzenia i tego, jak IoT Hub przetwarza komunikaty z chmury do urządzenia, zobacz Wysyłanie komunikatów z chmury do urządzenia z 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 pętli while lub pętli for). Pętla wykonuje się ciągle, sprawdzając wiadomości.

Wymagany pakiet NuGet dla urządzenia

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

Dodaj te instrukcje using, aby użyć 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 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 uwidacznia wszystkie metody wymagane do odbierania komunikatów na urządzeniu.

Podaj główny łańcuch połączenia usługi IoT Hub i identyfikator urządzenia do DeviceClient, używając metody CreateFromConnectionString. Oprócz wymaganego podstawowego ciągu połączenia IoT Hub, metodę CreateFromConnectionString można przeciążyć, by uwzględnić te parametry opcjonalne:

transportType - Protokół transportowy: odmiany protokołu HTTP w wersji 1, AMQP lub MQTT. Wartość domyślna to AMQP. Aby wyświetlić wszystkie dostępne wartości, zobacz wyliczenie TransportType.
transportSettings - Interfejs używany do definiowania różnych ustawień specyficznych dla transportu dla DeviceClient i ModuleClient. Aby uzyskać więcej informacji, zobacz Interfejs ITransportSettings.
ClientOptions - Opcje umożliwiające konfigurację urządzenia lub instancji klienta modułu podczas inicjalizacji.

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 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ą wypełniane w obiekcie authDeviceAuthenticationWithX509Certificate, który jest przekazywany do obiektu 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 certyfikatów 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 i na dużą skalę wdrożenie urządzeń IoT za pomocą usługi Provisioning Service IoT Hub

Oddzwonienie

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. Do urządzenia są odbierane komunikaty przychodzące 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, gdy odbierany jest komunikat. Utworzenie metody wywołania zwrotnego w celu odbierania komunikatów eliminuje konieczność ciągłego sprawdzania otrzymywanych komunikatów.

Callback jest dostępny tylko przy użyciu tych 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 i tak sondować w poszukiwaniu odebranych komunikatów, co narusza zasadę wywołań zwrotnych.

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() — Odczekaj domyślny czas oczekiwania na komunikat przed kontynuowaniem.
ReceiveAsync (Timespan) — Odbieranie komunikatu z kolejki urządzenia przy użyciu ustalonego limitu czasu.
ReceiveAsync (CancellationToken) — Odbierz komunikat z kolejki urządzenia za pomocą tokenu anulowania. W przypadku korzystania z tokenu anulowania domyślny okres limitu czasu nie jest używany.

Metoda ReceiveAsync zwraca wynik natychmiast, gdy używany jest transport HTTP 1 zamiast protokołu MQTT lub AMQP. Obsługiwany wzorzec dla komunikatów z chmury do urządzenia z protokołem HTTP 1 dotyczy urządzeń z przerywanym połączeniem, które rzadko sprawdzają wiadomości (co najmniej co 25 minut). Wydawanie większej liczby żądań HTTP/1.1 prowadzi do ograniczenia tych żądań przez usługę 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.

Porzucenie komunikatu, odrzucenie lub przekroczenie limitu czasu

W przypadku protokołów AMQP i HTTP w wersji 1, ale nie protokołu MQTT, urządzenie może również:

Porzuć komunikat, wywołując AbandonAsync. Dzięki temu usługa IoT Hub przechowuje wiadomość w kolejce urządzenia do późniejszego wykorzystania.
Odrzuć komunikat, wywołując polecenie RejectAsync. Spowoduje to trwałe usunięcie wiadomości z kolejki urządzenia.

Jeśli wystąpi coś, co uniemożliwia ukończenie, porzucenie lub odrzucenie komunikatu przez urządzenie, IoT Hub, po upływie ustalonego czasu, ponownie umieści komunikat w kolejce 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.

Pętla sondowania

Aplikacja korzysta z sondowania, używając pętli kodu, która wielokrotnie wywołuje metodę ReceiveAsync w celu sprawdzenia nowych komunikatów, aż do momentu zatrzymania.

Jeśli używasz ReceiveAsync z wartością limitu czasu lub domyślnego limitu czasu, w pętli każde wywołanie ReceiveAsync czeka przez określony okres oczekiwania. Jeśli ReceiveAsync upłynie, zostanie zwrócona wartość null, a pętla będzie kontynuowana.

Po odebraniu komunikatu, zwracany jest obiekt Task przez element ReceiveAsync, który powinien zostać przekazany do CompleteAsync. Wywołanie CompleteAsync powiadamia IoT Hub, aby usunąć określony komunikat z kolejki komunikatów na podstawie parametru Task.

W tym przykładzie pętla wywołuje ReceiveAsync aż do momentu odebrania komunikatu lub zatrzymania 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 odbieranego przez SDK

Pakiet SDK .NET/C# 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ć informacje zwrotne dotyczące dostarczania wiadomości wysyłanej do usługi IoT Hub, przeznaczonej do dostarczenia na urządzenie za pośrednictwem kolejki wiadomości.

Dodaj pakiet NuGet dla 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. Oprócz wymaganego podstawowego ciągu połączenia IoT Hub, metodę CreateFromConnectionString można przeciążyć, by uwzględnić te parametry opcjonalne:

transportType - Amqp lub Amqp_WebSocket_Only.
transportSettings — Ustawienia protokołu AMQP i serwera proxy HTTP dla klienta usługi.
ServiceClientOptions - Opcje, które umożliwiają konfigurację instancji klienta usług podczas inicjowania. Aby uzyskać więcej informacji, zobacz ServiceClientOptions.

Obiekt ServiceClient jest tworzony w tym przykładzie przy użyciu parametru połączenia z IoT Hub oraz domyślnego transportuAmqp.

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 z hubem IoT. 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:

Sekret 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, aby umożliwić dostęp do odczytu i zapisu do urządzenia IoT Hub oraz podwójnych modułów. Aby uzyskać więcej informacji, zobacz Zarządzaj dostępem do IoT Hub, korzystając z przypisywania ról RBAC w 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 za pomocą 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 określonego TokenCredential lub uproszczonego ChainedTokenCredential. Dla uproszczenia, ta sekcja opisuje uwierzytelnianie przy użyciu DefaultAzureCredential i tajnego klucza klienta. Aby uzyskać więcej informacji na temat zalet i wad korzystania z DefaultAzureCredential, zobacz Wskazówki dotyczące użycia dla 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.

Korzystanie z Microsoft Entra wymaga tych pakietów NuGet oraz odpowiednich instrukcji using:

Azure.Core (Rdzeń Azure)
Azure.Identity (tożsamość azure)

using Azure.Core;
using Azure.Identity;

W tym przykładzie klucz tajny klienta rejestracji aplikacji Microsoft Entra, 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 Microsoft Entra jest token zabezpieczający, który jest przekazywany do metody połączenia 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 połączenia z IoT Hub dla dowolnego klienta SDK, który akceptuje poświadczenia Microsoft Entra.

W tym przykładzie parametr TokenCredential jest przekazywany do ServiceClient.Create, aby 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.

Wyślij asynchroniczną wiadomość z 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 znaków 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 sprzężenia zwrotnego wiadomości opisano w Sprzężenie zwrotne wiadomości.

Aby otrzymywać opinie dotyczące dostarczania wiadomości:

Utwórz feedbackReceiver obiekt
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 potwierdzenia dostarczenia. 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 Positive i Negative.

W tym przykładzie właściwość Ack jest ustawiona na Full, żądając informacji zwrotnej dotyczącej dostarczenia wiadomości, zarówno pozytywnej, jak i negatywnej, 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 wielokrotnie wywołuj ReceiveAsync, sprawdzając wiadomości zwrotne o dostarczeniu. 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 null i pętla kontynuuje.
Jeśli zostanie odebrany komunikat z informacją zwrotną, obiekt Task zostanie zwrócony przez ReceiveAsync, który powinien zostać przekazany do metody CompleteAsync wraz z tokenem anulowania. Wywołanie CompleteAsync usuwa określony wysłany komunikat z kolejki komunikatów na podstawie parametru Task.
W razie potrzeby kod odbioru może wywołać metodę AbandonAsync, aby ponownie umieścić wiadomość do wysł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 timeout 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 połączenie klienta

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 ograniczenia przepustowości/przekroczenia limitu, monitoruj lub modyfikuj częstotliwość wysyłania żądań albo 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

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

Do utworzenia obiektu DeviceClient potrzebne są następujące parametry:

connString — parametry połączenia urządzenia IoT. Ciąg połączenia to zestaw par klucz-wartość, które są oddzielone średnikiem ';', a klucze i wartości oddzielone znakiem '='. 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 DeviceClient przy użyciu informacji ClientOptions, aby utworzyć połączenie urządzenia z 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 certyfikatów X.509 dla urządzeń, zobacz:

Ustaw metodę wywołania zwrotnego komunikatu

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 zwrotnej. Może to być null.
context - Opcjonalny kontekst typu object. Użyj null jeśli nie określono.

W tym przykładzie metoda callback bez parametru kontekstu jest przekazywana do MessageCallback.

client.setMessageCallback(new MessageCallback(), null);

Utwórz obsługę wywołań zwrotnych dla komunikatów

Obsługiwacz komunikatów wywołania zwrotnego odbiera i przetwarza przychodzący komunikat z kolejki komunikatów 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 zwrócić IotHubMessageResult.COMPLETE po pomyślnym zakończeniu przetwarzania, informując usługę IoT Hub, że komunikat powinien zostać usunięty z kolejki komunikatów, niezależnie od tego, jaki protokół jest używany.

  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, może być konieczne porzucenie lub odrzucenie komunikatu.

W przypadku protokołów AMQP i HTTPS, ale nie MQTT, aplikacja może:
- IotHubMessageResult.ABANDON wiadomość. Usługa IoT Hub ustawia ją w kolejce i wysyła ponownie później.
- IotHubMessageResult.REJECT wiadomość. Usługa IoT Hub nie kolejkuje ponownie komunikatu i trwale usuwa komunikat z kolejki komunikatów.
Klienci korzystający z MQTT lub MQTT_WS nie mogą ABANDON ani REJECT wiadomości.

Uwaga

Jeśli używasz protokołu HTTPS zamiast protokołu MQTT lub AMQP jako transportu, wystąpienie DeviceClient rzadko sprawdza wiadomości z usługi IoT Hub (najrzadziej 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.

Utwórz metodę wywołania zwrotnego stanu wiadomości

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. W ten sposób aplikacja może wykryć zerwane połączenie komunikatów i spróbuje ponownie nawiązać połączenie.

W tym przykładzie IotHubConnectionStatusChangeCallbackLogger jest rejestrowana jako metoda wywołania zwrotnego zmiany stanu połączenia.

client.registerConnectionStatusChangeCallback(new IotHubConnectionStatusChangeCallbackLogger(), new Object());

Wywołanie zwrotne jest uruchamiane i przekazuje obiekt ConnectionStatusChangeContext.

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ć 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ładu odbioru wiadomości w ramach SDK w tym artykule, aby zapoznać się z pełnym przykładem przedstawiającym sposób wyodrębniania metody zwrotnej zmiany stanu połączenia, przyczyny zmiany stanu urządzenia oraz kontekstu.

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 odbieranego przez 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.

Dodaj instrukcję zależności

Dodaj zależność, aby twoja aplikacja mogła korzystać z pakietu iothub-java-service-client 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>

Dodaj instrukcje 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

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 AMQPS lub AMQPS_WS.

IotHubServiceClientProtocol protocol = IotHubServiceClientProtocol.AMQPS;

Tworzenie obiektu ServiceClient

Utwórz obiekt ServiceClient, podając ciąg połączenia z IoT Hub oraz protokół.

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

Aby zapoznać się z omówieniem uwierzytelniania w Java SDK, zobacz Uwierzytelnianie platformy Azure przy użyciu Java i Azure Identity.

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

Konfigurowanie aplikacji Microsoft Entra

Sekret klienta
Certyfikat
Poświadczenie 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.

Uwierzytelnij za pomocą 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 określonego TokenCredential lub uproszczonego 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.

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.

Możesz uwierzytelnić poświadczenia aplikacji Microsoft Entra za pomocą DefaultAzureCredentialBuilder. Zapisz parametry połączenia, takie jak tajny klucz klienta, identyfikator dzierżawy, identyfikator klienta i wartości tajne klienta 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 udanego uwierzytelnienia Microsoft Entra jest poświadczenie tokenu zabezpieczającego przekazywane do konstruktora takiego jak ServiceClient.

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

Uwierzytelnianie za pomocą 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 klucza tajnego klienta rejestracji aplikacji Microsoft Entra, identyfikatora klienta i identyfikatora dzierżawy. Te zmienne środowiskowe są używane przez ClientSecretCredentialBuilder do tworzenia 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.

Otwieranie odbiornika opinii w celu uzyskania opinii dotyczącej dostarczania komunikatów

Możesz użyć FeedbackReceiver, aby uzyskać informacje zwrotne dotyczące dostarczania wysłanych wiadomości do usługi IoT Hub. A FeedbackReceiver jest wyspecjalizowanym odbiornikiem, którego Receive metoda zwraca wartość FeedbackBatch zamiast Message.

W tym przykładzie tworzony jest obiekt FeedbackReceiver, a wywoływana jest instrukcja open(), aby oczekiwać na opinię.

FeedbackReceiver feedbackReceiver = serviceClient
  .getFeedbackReceiver();
if (feedbackReceiver != null) feedbackReceiver.open();

Dodawanie właściwości komunikatu

Opcjonalnie możesz użyć metody 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 z chmury do urządzenia.

Użyj setDeliveryAcknowledgement, aby zażądać potwierdzenia dostarczenia lub niedostarczenia wiadomości do kolejki komunikatów w usłudze IoT Hub. W tym przykładzie żądane potwierdzenie to Full, zostało dostarczone lub nie.

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ć receive z limitem czasu lub bez niego. Jeśli nie podano wartości limitu czasu, zostanie użyty domyślny limit czasu. Zwraca to obiekt FeedbackBatch, który zawiera właściwości opinii zwrotnej dotyczących dostarczania komunikatów, które można zbadać.

W tym przykładzie tworzony jest odbiornik i wywoływana jest metoda FeedbackBatch, która drukuje czas zakolejkowania wiadomości.

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:

Przykład klienta usługi — przykład wysyłania komunikatu, #1.
Przykład klienta usługi — przykład wysyłania komunikatu, #2.

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ć funkcje IoTHubDeviceClient z pakietu 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ć podstawowy łańcuch połączeniowy 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
Wywołaj connect, aby połączyć się 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:

Przykłady kodu

Aby zapoznać się z działającymi przykładami uwierzytelniania za pomocą certyfikatów X.509 urządzenia, przejrzyj przykłady, których nazwy plików kończą się na x509 w scenariuszach asynchronicznego huba.

Zarządzaj ponownym połączeniem

IoTHubDeviceClient domyślnie podejmie próbę ponownego nawiązania zerwanego połączenia. Zachowanie ponownego IoTHubDeviceClientłączenia jest regulowane przez parametry connection_retry i connection_retry_interval.

Utwórz obsługę 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 obsługa wiadomości zwrotnej.

W tym przykładzie message_handler jest wywoływane po odebraniu wiadomości. Właściwości komunikatu (.items) są wypisywane na 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 IoTHubDeviceClientclient obiektu. Obiekt client oczekuje na otrzymanie wiadomości z cloud-to-device od 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 odbieranego przez 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 deklarację. 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

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

Nawiąż połączenie z hubem 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

Konfigurowanie aplikacji Microsoft Entra

Sekret klienta
Certyfikat
Poświadczenie 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.

Uwierzytelnij za pomocą DefaultAzureCredential

Korzystanie z Microsoft Entra wymaga tych pakietów NuGet oraz odpowiednich instrukcji using:

Azure.Core (Rdzeń Azure)
Azure.Identity (tożsamość azure)

using Azure.Core;
using Azure.Identity;

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 połączenia z IoT Hub dla dowolnego klienta SDK, który akceptuje poświadczenia Microsoft Entra.

W tym przykładzie parametr TokenCredential jest przekazywany do ServiceClient.Create, aby 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.

Zbuduj i wyślij wiadomość

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 znaków urządzenia docelowego.
message - Komunikat chmura-urządzenie. Komunikat jest typu str (ciąg).
properties- Opcjonalna kolekcja właściwości typu dict. 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, który pokazuje, 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 i obsługi rozłączeń w przypadku zerwania połączenia między urządzeniem a 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

Uwierzytelnianie przy użyciu certyfikatu X.509

Certyfikat X.509 jest dołączony do kanału łączności urządzenia z 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 ciągu połączenia, aby wskazać, że certyfikat jest dodawany do DeviceClientOptions. Na przykład:
- Parametry połączenia urządzenia:
  
  HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
- Łańcuch 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, aby otworzyć połączenie z urządzenia do IoT Hub.

W tym przykładzie przedstawiono informacje o konfiguracji certyfikatu w zmiennej JSON. Konfiguracja clientOptions certyfikatów jest przekazywana do setOptions, a połączenie jest otwierane przy użyciu 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

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 usługi IoT Hub rzadko (przynajmniej 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 parametrów 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. IoT Hub trwale usuwa wiadomość z kolejki urządzenia. Metoda przyjmuje formę client.reject(message, callback function).
Porzuć — jeśli porzucisz komunikat, usługa IoT Hub natychmiast spróbuje wysłać go ponownie. Usługa IoT Hub zachowuje komunikat w kolejce urządzenia do przyszłego wykorzystania. Metoda przyjmuje formę client.abandon(message, callback function).

protokół komunikacyjny 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

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;

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

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

Utwórz moduł obsługi wiadomości przychodzących

Procedura obsługi komunikatów jest uruchamiana dla każdego przychodzącego komunikatu.

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 wyświetla identyfikator komunikatu i treść komunikatu na konsoli, a następnie wywołuje client.complete w celu powiadomienia usługi IoT Hub, że komunikat został przetworzony i może być bezpiecznie usunięty z kolejki urządzenia. Wywołanie complete nie jest wymagane, jeśli używasz transportu MQTT i można je pominąć. Wywołanie complete jest wymagane dla transportu AMQP lub HTTPS.

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 na konsoli.

function disconnectHandler() {
  clearInterval(sendInterval);
  sendInterval = null;
  client.open().catch((err) => {
    console.error(err.message);
  });
}

Dodaj odbiorniki zdarzeń

Te nasłuchiwacze zdarzeń można określić metodą .on.

Obsługiwacz połączeń
Obsługa błędów
Rozłącz program obsługi
Obsługiwacz wiadomości

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 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 Twoim centrum IoT i odbiera wiadomości 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.

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 obiekt Client używając klasy Client z pakietu azure-iothub.

Zadeklaruj obiekt Message używając klasy Message z pakietu azure-iot-common.

'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

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 obiekt serviceClient jest tworzony z transportem typu Amqp.

var connectionString = '{IoT hub device connection string}';
var serviceClient = Client.fromConnectionString(connectionString,`Amqp`);

Otwieranie połączenia klienta

Wywołaj metodę Clientopen , aby otworzyć połączenie między aplikacją a usługą IoT Hub.

open może być wywołany z funkcją wywołania zwrotnego, która jest wywoływana po zakończeniu operacji open, lub bez określania takiej funkcji.

W tym przykładzie metoda open zawiera opcjonalną funkcję wywołania zwrotnego err dla 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, wartość wywołania zwrotnego null zostanie zwrócona.

serviceClient.open(function (err)
if (err)
  console.error('Could not connect: ' + err.message);

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

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

Konfigurowanie aplikacji Microsoft Entra

Sekret klienta
Certyfikat
Poświadczenie 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.

Uwierzytelnij za pomocą 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 określonego TokenCredential lub uproszczonego ChainedTokenCredential. Dla uproszczenia, ta sekcja opisuje uwierzytelnianie przy użyciu DefaultAzureCredential i tajnego klucza 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

Firma Microsoft Entra wymaga tego pakietu:

npm install --save @azure/identity

W tym przykładzie tajny klucz 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 Microsoft Entra jest token zabezpieczający, który jest przekazywany do metody połączenia IoT Hub.

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

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

Otrzymany token poświadczeń można następnie przekazać do fromTokenCredential w celu nawiązania połączenia z usługą IoT Hub dla dowolnego klienta zestawu SDK, który akceptuje poświadczenia 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 do Registry.fromTokenCredential przekazywane są adres URL domeny platformy Azure oraz poświadczenia 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 przykładami działania uwierzytelniania usługi Microsoft Entra, zobacz Azure identity examples.

Tworzenie komunikatu

Obiekt komunikat zawiera asynchroniczną wiadomość z chmury do urządzenia. 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 i wartości ciągów znaków do przechowywania niestandardowych właściwości komunikatów.
messageId — służy do korelowania komunikacji dwukierunkowej.

Dodaj treść komunikatu przy instancjacji obiektu wiadomości. W tym przykładzie dodawana jest wiadomość 'Cloud to device message.'.

var message = new Message('Cloud to device message.');
message.ack = 'full';
message.messageId = "My Message ID";

Potwierdzenie dostarczenia

Każda wiadomość, która ma otrzymać informację zwrotną, musi zawierać wartość dla właściwości potwierdzenia dostarczenia oznaczonej jako 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 wiadomość wygasła (lub osiągnięto maksymalną liczbę prób dostarczenia) bez dostarczenia jej 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ść ack jest ustawiona na full, żądając zarówno wysłanych, jak i niewysłanych informacji zwrotnej dotyczącej dostarczenia komunikatów dla jednej wiadomości.

message.ack = 'full';

Połącz odbiorcę informacji zwrotnej dotyczącej wiadomości

Funkcja zwrotna odbiorcy komunikatów jest związana z Client za pomocą getFeedbackReceiver.

Odbiorca opinii o wiadomościach otrzymuje dwa argumenty:

Obiekt błędu (może mieć wartość null)
Obiekt AmqpReceiver — emituje zdarzenia, gdy nowe wiadomości zwrotne są odbierane przez klienta.

Ta przykładowa funkcja odbiera i wyświetla na konsoli wiadomość z informacją zwrotną dotyczącą dostawy.

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

serviceClient.getFeedbackReceiver(receiveFeedback);

Zdefiniuj obsługiwacz wyników uzupełniania komunikatów

Funkcja zwrotna zakończenia wysyłania wiadomości jest wywoływana po wysłaniu każdej wiadomości.

Ta przykładowa funkcja wyświetla wyniki operacji komunikatu send w konsoli. W tym przykładzie funkcja printResultFor jest dostarczana jako parametr do funkcji send, 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. Funkcja 'Done' jest wywoływana z dwoma argumentami:
- Obiekt błędu (może mieć wartość null).
- obiekt odpowiedzi specyficzny dla transportu przydatny do rejestrowania lub debugowania.

Ten kod używa send do wysyłania komunikatu z chmury do aplikacji na urządzeniu za pośrednictwem usługi IoT Hub. Funkcja printResultFor wywołania zwrotnego zdefiniowana w poprzedniej sekcji odbiera informacje o potwierdzeniu dostarczenia.

var targetDevice = '{device ID}';
serviceClient.send(targetDevice, message, printResultFor('send'));

W tym przykładzie pokazano, jak wysłać wiadomość do urządzenia i obsłużyć wiadomość zwrotną, gdy urządzenie potwierdzi wiadomość 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 strategii ponawiania próby komunikatów dla połączenia urządzenia z IoT Hub ani połączenia zewnętrznej aplikacji z 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 i maksymalna liczba prób dostarczenia

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 życia (TTL) — czas, przez jaki komunikat jest dostępny dla urządzenia do wykorzystania, zanim zostanie unieważniony przez usługę IoT Hub.
Czas przechowywania informacji zwrotnych — okres, przez jaki usługa IoT Hub zachowuje informacje zwrotne dotyczące wygaśnięcia lub dostarczenia komunikatów z chmury do urządzenia.
Liczba prób dostarczenia komunikatu z chmury do urządzenia przez usługę IoT Hub.

Udostępnij za pośrednictwem

Wysyłanie i odbieranie komunikatów z chmury do urządzenia

Omówienie

Omówienie kolejki komunikatów

Tworzenie aplikacji urządzenia

Wymagany pakiet NuGet 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

Oddzwonienie

Sondowanie

CompleteAsync, metoda

Porzucenie komunikatu, odrzucenie lub przekroczenie limitu czasu

Pętla sondowania

Zasady ponawiania próby odbierania komunikatów

Przykład komunikatu odbieranego przez SDK

Tworzenie aplikacji zaplecza

Dodaj pakiet NuGet dla 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 za pomocą DefaultAzureCredential

Przykład kodu

Wyślij asynchroniczną wiadomość z chmury do urządzenia

Odbieranie opinii o dostawie

Tworzenie obiektu feedbackReceiver

Wysyłanie komunikatów przy użyciu parametru Ack

Poczekaj, aż otrzymasz opinię

Ponowne połączenie klienta

Zasady ponawiania wysyłania komunikatów

Przykład wysyłania komunikatu z zestawu SDK

Tworzenie aplikacji urządzenia

Importowanie bibliotek zestawu Java SDK usługi Azure IoT

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

Ustaw metodę wywołania zwrotnego komunikatu

Utwórz obsługę wywołań zwrotnych dla komunikatów

Opcje porzucania i odrzucania komunikatów

Utwórz metodę wywołania zwrotnego stanu wiadomości

Otwieranie połączenia między urządzeniem a usługą IoT Hub

Przykład komunikatu odbieranego przez SDK

Tworzenie aplikacji zaplecza

Dodaj instrukcję zależności

Dodaj instrukcje importu

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

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

Definiowanie protokołu połączenia

Tworzenie obiektu ServiceClient

Otwieranie połączenia między aplikacją a usługą IoT Hub

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

Konfigurowanie aplikacji Microsoft Entra

Uwierzytelnij za pomocą DefaultAzureCredential

Uwierzytelnianie za pomocą ClientSecretCredentialBuilder

Inne klasy uwierzytelniania

Przykłady kodu

Otwieranie odbiornika opinii w celu uzyskania opinii dotyczącej dostarczania komunikatów

Dodawanie właściwości komunikatu

Tworzenie i wysyłanie komunikatu asynchronicznego

Odbieranie opinii dotyczącej dostarczania komunikatów

Przykłady wiadomości wysyłanych przez zestaw SDK

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

Zarządzaj ponownym połączeniem

Utwórz obsługę komunikatów

Przypisywanie programu obsługi komunikatów

Przykład komunikatu odbieranego przez SDK

Tworzenie aplikacji zaplecza

Importowanie obiektu IoTHubRegistryManager

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