Udostępnij za pośrednictwem


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 lub for ). 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 to AMQP. Aby wyświetlić wszystkie dostępne wartości, zobacz TransportType, wyliczenie.
  • transportSettings - Interfejs używany do definiowania różnych ustawień specyficznych dla transportu dla DeviceClient i ModuleClient. 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:

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

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

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 przykładami pracy uwierzytelniania certyfikatu X.509 urządzenia, zobacz:

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 lub Amqp_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 DefaultAzureCredentialdla elementu DefaultAzureCredential.

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

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

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

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

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

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

TokenCredential tokenCredential = new DefaultAzureCredential();

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

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

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

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

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

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

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 i Positive 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 celu CompleteAsync usunięcia określonego wysłanego komunikatu z kolejki komunikatów na podstawie parametru Task .
  • 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:

  1. Skompiluj obiekt SSLContext przy użyciu polecenia buildSSLContext.
  2. SSLContext Dodaj informacje do obiektu ClientOptions.
  3. 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:

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 typu object. Użyj null 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 lub MQTT_WS nie mogą ABANDON ani REJECT 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:

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:

  • 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ć 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:

  1. Wywołaj create_from_connection_string, aby dodać parametry połączenia podstawowego urządzenia.
  2. 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:

  1. Użyj create_from_x509_certificate , aby dodać parametry certyfikatu X.509
  2. 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:

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 DefaultAzureCredentialdla elementu DefaultAzureCredential.

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

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

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

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

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

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

TokenCredential tokenCredential = new DefaultAzureCredential();

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

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

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

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

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

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

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

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

    • Parametry połączenia urządzenia:

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

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

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

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

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

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

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

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

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

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

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

Przykład kodu

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

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

Wybieranie protokołu transportowego

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

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

Zainstaluj wymagane protokoły transportu na maszynie dewelopera.

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

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

Aby uzyskać więcej informacji na temat różnic między obsługą protokołów MQTT, AMQP i HTTPS, zobacz Wskazówki dotyczące komunikacji między chmurą 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:

Konfigurowanie aplikacji Microsoft Entra

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

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

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

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

Uwierzytelnianie przy użyciu wartości DefaultAzureCredential

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

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

Firma Microsoft Entra wymaga tego pakietu:

npm install --save @azure/identity

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

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

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

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

fromTokenCredential wymaga dwóch parametrów:

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

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

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

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

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

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

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

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

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

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

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.