Zarządzanie urządzeniami przy użyciu metod bezpośrednich - Azure IoT Hub

Wymaga programu Visual Studio

Omówienie

W tym artykule opisano sposób używania zestawu SDK Azure IoT dla platformy .NET do tworzenia kodu aplikacji dla urządzeń i usług zaplecza dla bezpośrednich wiadomości urządzeń.

Tworzenie aplikacji urządzenia

Ta sekcja opisuje, jak używać kodu aplikacji urządzenia do tworzenia nasłuchującego metody bezpośredniej.

Wymagane pakiety urządzenia NuGet

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

Aby używać biblioteki urządzeń, dodaj te using polecenia.

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 interakcji z komunikatami urządzenia z urządzenia.

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

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

Mqtt
Mqtt_WebSocket_Only
Mqtt_Tcp_Only
Amqp
Amqp_WebSocket_Only
Amqp_Tcp_Only
Http1

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

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

Utwórz nasłuchiwacza metod bezpośrednich

Użyj SetMethodHandlerAsync, aby zainicjować odbiornik wywołania zwrotnego bezpośredniej metody. Nasłuchujący jest powiązany ze słowem kluczowym nazwy metody, takim jak "restart". Nazwa metody może być używana w usłudze IoT Hub lub w aplikacji serwerowej w celu wyzwolenia metody zwrotnej na urządzeniu.

Ten przykład ustawia nasłuchiwacz wywołań zwrotnych o nazwie onReboot, który zostanie uruchomiony, gdy wywołana zostanie bezpośrednia metoda 'reboot'.

try
{
      // setup callback for "reboot" method
      deviceClient.SetMethodHandlerAsync("reboot", onReboot, null).Wait();
      Console.WriteLine("Waiting for reboot method\n Press enter to exit.");
      Console.ReadLine();

      Console.WriteLine("Exiting...");

      // as a good practice, remove the "reboot" handler
      deviceClient.SetMethodHandlerAsync("reboot", null, null).Wait();
      deviceClient.CloseAsync().Wait();
}
catch (Exception ex)
{
      Console.WriteLine();
      Console.WriteLine("Error in sample: {0}", ex.Message);
}

Kontynuując przykład, metoda wywołania zwrotnego onReboot implementuje bezpośrednią metodę na urządzeniu.

Funkcja obsługi wywołuje metodę MethodResponse , aby wysłać potwierdzenie odpowiedzi do aplikacji wywołującej.

static Task<MethodResponse> onReboot(MethodRequest methodRequest, object userContext)
{
      // In a production device, you would trigger a reboot 
      // scheduled to start after this method returns.
      // For this sample, we simulate the reboot by writing to the console
      // and updating the reported properties.
      try
      {
         Console.WriteLine("Rebooting!");
      }
      catch (Exception ex)
      {
         Console.WriteLine();
         Console.WriteLine("Error in sample: {0}", ex.Message);
      }

      string result = @"{""result"":""Reboot started.""}";
      return Task.FromResult(new MethodResponse(Encoding.UTF8.GetBytes(result), 200));
}

Uwaga

Aby zachować prostotę, ten artykuł nie implementuje żadnych zasad ponawiania prób. W kodzie produkcyjnym należy zaimplementować zasady ponawiania prób (takie jak odstęp czasowy o wykładniczo rosnącej wartości), jak sugeruje się w kontekście obsługi błędów przejściowych.

Przykłady urządzeń z zestawem SDK

Zestaw AZURE IoT SDK dla platformy .NET udostępnia działające przykłady aplikacji urządzeń, które obsługują zadania metody bezpośredniej. Aby uzyskać więcej informacji, zobacz:

Tworzenie aplikacji zaplecza

W tej sekcji opisano sposób wyzwalania metody bezpośredniej na urządzeniu.

Klasa ServiceClient uwidacznia wszystkie metody wymagane do utworzenia aplikacji zaplecza w celu wysyłania wywołań metody bezpośredniej do urządzeń.

Wymagany pakiet usługi NuGet

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

Dodaj te using instrukcje do używania biblioteki usług.

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

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 przy użyciu metody CreateFromConnectionString.

Aby wywołać metodę bezpośrednią na urządzeniu za pośrednictwem usługi IoT Hub, usługa wymaga uprawnień połączenia usługi. Domyślnie każde centrum IoT Hub jest tworzone przy użyciu zasad dostępu współdzielonego o nazwie usługa , która przyznaje to uprawnienie.

Jako parametr dla CreateFromConnectionString podaj zasady współdzielonego dostępu do usługi. Aby uzyskać więcej informacji na temat zasad dostępu współdzielonego, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu sygnatur dostępu współdzielonego.

ServiceClient serviceClient;
string connectionString = "{IoT hub service shared access policy 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 IoT Hubem. 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:

Tajemnica 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 usługi IoT Hub za pomocą przypisania ról RBAC na platformie Azure.

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

Uwierzytelnij się przy użyciu DefaultAzureCredential

Najprostszym sposobem użycia Microsoft Entra do uwierzytelniania aplikacji zaplecza jest użycie DefaultAzureCredential. Jednak zaleca się korzystanie z innej metody w środowisku produkcyjnym, w tym określonej TokenCredential lub uproszczonej ChainedTokenCredential. Dla uproszczenia w tej sekcji opisano uwierzytelnianie przy użyciu DefaultAzureCredential i klucza tajnego klienta. Aby uzyskać więcej informacji na temat zalet i wad korzystania z DefaultAzureCredential, zobacz Wskazówki dotyczące użytkowania 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 tajny klient, identyfikator klienta i identyfikator dzierżawy rejestracji aplikacji Microsoft Entra są dodawane do zmiennych środowiskowych. Te zmienne środowiskowe są używane przez DefaultAzureCredential program do uwierzytelniania aplikacji. Wynikiem pomyślnej uwierzytelnienia Microsoft Entra jest poświadczenie tokena bezpieczeństwa, które jest przekazywane do metody połączenia z 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 IoT Hub dla dowolnego klienta SDK, który akceptuje dane uwierzytelniające Microsoft Entra.

W tym przykładzie TokenCredential jest przekazywane do ServiceClient.Create w celu utworzenia obiektu 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.

Wywoływanie metody na urządzeniu

Aby wywołać metodę na urządzeniu:

Utwórz obiekt CloudToDeviceMethod. Przekaż nazwę metody bezpośredniej urządzenia jako parametr.
Wywołaj metodę InvokeDeviceMethodAsync , aby wywołać metodę na urządzeniu.

W tym przykładzie wywoływana jest metoda "reboot", aby zainicjować ponowny rozruch na urządzeniu. Metoda "reboot" jest mapowana na odbiornik na urządzeniu zgodnie z opisem w sekcji Tworzenie odbiornika dla bezpośredniego wywołania metody zwrotnej w tym artykule.

string targetDevice = "myDeviceId";
CloudToDeviceMethod method = new CloudToDeviceMethod("reboot");
method.ResponseTimeout = TimeSpan.FromSeconds(30);

CloudToDeviceMethodResult response = await serviceClient.InvokeDeviceMethodAsync(targetDevice, method);

Console.WriteLine("Invoked firmware update on device.");

Przykłady usługi SDK

Zestaw Azure IoT SDK dla platformy .NET udostępnia działające przykłady aplikacji serwisowych, które obsługują operacje związane z komunikatami. Aby uzyskać więcej informacji, zobacz:

Wymaga zestawu Java SE Development Kit 8. Upewnij się, że wybrano Java 8 w sekcji Obsługa długoterminowa, aby przejść do pobierania JDK 8.

Omówienie

W tym artykule opisano sposób używania zestawu Azure IoT SDK dla języka Java do tworzenia kodu aplikacji dla urządzeń oraz usług backendowych do metod bezpośrednich urządzeń.

Tworzenie aplikacji urządzenia

Ta sekcja opisuje, jak używać kodu aplikacji urządzenia do tworzenia nasłuchującego metody bezpośredniej.

Klasa DeviceClient uwidacznia wszystkie metody wymagane do interakcji z metodami bezpośrednimi na urządzeniu.

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

Instrukcje importowania urządzenia

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

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodPayload;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodResponse;
import com.microsoft.azure.sdk.iot.device.twin.MethodCallback;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;
import com.microsoft.azure.sdk.iot.device.twin.SubscriptionAcknowledgedCallback;

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

Aby nawiązać połączenie z urządzeniem:

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

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

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

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

Uwierzytelnianie przy użyciu certyfikatu X.509

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

Skompiluj obiekt SSLContext przy użyciu polecenia buildSSLContext.
SSLContext Dodaj informacje do obiektu ClientOptions.
Wywołaj DeviceClient przy użyciu informacji ClientOptions, aby utworzyć połączenie urządzenia z 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 działania uwierzytelniania certyfikatu X.509 urządzenia, zobacz:

Utwórz nasłuchiwacza metod bezpośrednich

Użyj subscribeToMethods, aby zainicjować nasłuchiwacz bezpośrednich metod zwrotnych. subscribeToMethods Nasłuchuje przychodzących metod bezpośrednich do momentu zakończenia połączenia. Nazwa metody i ładunek są odbierane w przypadku każdego wywołania metody bezpośredniej.

Odbiornik powinien wywołać metodę DirectMethodResponse , aby wysłać potwierdzenie odpowiedzi metody do aplikacji wywołującej.

Na przykład:

client.subscribeToMethods(
    (methodName, methodData, context) ->
    {
        System.out.println("Received a direct method invocation with name " + methodName + " and payload " + methodData.getPayloadAsJsonString());
        return new DirectMethodResponse(200, methodData);
    },
    null);
System.out.println("Successfully subscribed to direct methods");

Uwaga

Aby zachować prostotę, ten artykuł nie implementuje żadnych zasad ponawiania prób. W kodzie produkcyjnym należy zaimplementować zasady ponawiania prób (takie jak odstęp czasowy o wykładniczo rosnącej wartości), jak sugeruje się w kontekście obsługi błędów przejściowych.

Przykłady urządzeń z zestawem SDK

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

Tworzenie aplikacji zaplecza

W tej sekcji opisano sposób inicjowania zdalnego ponownego rozruchu na urządzeniu przy użyciu metody bezpośredniej.

Klasa ServiceClientDeviceMethod zawiera metody, których usługi mogą używać do uzyskiwania dostępu do metod bezpośrednich.

Instrukcje importu usług

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

import com.microsoft.azure.sdk.iot.service.methods.DirectMethodRequestOptions;
import com.microsoft.azure.sdk.iot.service.methods.DirectMethodsClient;
import com.microsoft.azure.sdk.iot.service.methods.DirectMethodResponse;

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

Użyj konstruktora DeviceMethod, aby dodać podstawowy ciąg połączenia usługi i połączyć się z IoT Hub.

Aby wywołać metodę bezpośrednią na urządzeniu za pośrednictwem usługi IoT Hub, usługa wymaga uprawnień połączenia usługi. Domyślnie każde centrum IoT Hub jest tworzone przy użyciu zasad dostępu współdzielonego o nazwie usługa , która przyznaje to uprawnienie.

Jako parametr DeviceMethod konstruktora podaj zasady współdzielonego dostępu do usługi. Aby uzyskać więcej informacji na temat zasad dostępu współdzielonego, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu sygnatur dostępu współdzielonego.

Na przykład:

String iotHubConnectionString = "HostName=xxxxx.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey=xxxxxxxxxxxxxxxxxxxxxxxx";
DeviceMethod methodClient = new DeviceMethod(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 z IoT Hubem. 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 za pomocą Java SDK, zobacz Uwierzytelnianie w 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

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:

Tajemnica 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 usługi IoT Hub za pomocą przypisania ról RBAC na platformie Azure.

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

Uwierzytelnij się przy użyciu DefaultAzureCredential

Najprostszym sposobem użycia Microsoft Entra do uwierzytelniania aplikacji zaplecza jest użycie DefaultAzureCredential. Jednak zaleca się korzystanie z innej metody w środowisku produkcyjnym, w tym określonej TokenCredential lub uproszczonej 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 uwierzytelniać poświadczenia aplikacji Microsoft Entra za pomocą DefaultAzureCredentialBuilder. Zapisz parametry połączenia, takie jak identyfikator dzierżawy, identyfikator klienta i tajne dane 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. Rezultatem pomyślnego uwierzytelnienia Microsoft Entra jest poświadczenie tokenu zabezpieczającego, które jest 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 metoda powiedzie się, zwraca TokenCredential, które można przekazać do ServiceClient lub innego konstruktora jako parametr 'credential'.

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

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

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

Inne klasy uwierzytelniania

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

Przykłady kodu

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

Wywoływanie metody na urządzeniu

Wywołaj metodę DeviceMethod.invoke , aby wywołać metodę na urządzeniu i zwrócić stan wyniku.

Parametr ładunku invoke jest opcjonalny. Użyj null, jeśli nie podano ładunku. Parametr ładunku może przyjmować różne formularze danych, w tym ciąg, tablicę bajtów i hashMap. Aby zapoznać się z przykładami, zobacz Testy metod bezpośrednich.

W tym przykładzie wywoływana jest metoda "reboot", aby zainicjować ponowny rozruch na urządzeniu. Metoda "reboot" jest mapowana na odbiornik na urządzeniu zgodnie z opisem w sekcji Tworzenie odbiornika dla bezpośredniego wywołania metody zwrotnej w tym artykule.

Na przykład:

String deviceId = "myFirstDevice";
String methodName = "reboot";
String payload = "Test payload";
Long responseTimeout = TimeUnit.SECONDS.toSeconds(30);
Long connectTimeout = TimeUnit.SECONDS.toSeconds(5);

MethodResult result = methodClient.invoke(deviceId, methodName, responseTimeout, connectTimeout, payload);
if (result == null)
{
    throw new IOException("Method invoke returns null");
}
System.out.println("Status=" + result.getStatus());

Przykłady usługi SDK

Zestaw SDK usługi Azure IoT dla języka Java udostępnia działającą próbkę aplikacji usług, które obsługują zadania metody bezpośredniej. Aby uzyskać więcej informacji, zobacz:

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

Omówienie

W tym artykule opisano sposób używania zestawu SDK usługi Azure IoT dla języka Python do tworzenia kodu aplikacji dla bezpośrednich metod urządzeń i usług zaplecza.

Instalowanie pakietów

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

pip install azure-iot-device

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

pip install azure-iot-hub

Tworzenie aplikacji urządzenia

Ta sekcja opisuje, jak używać kodu aplikacji urządzenia do tworzenia nasłuchującego metody bezpośredniej.

Klasa IoTHubDeviceClient zawiera metody, których można użyć do pracy z metodami bezpośrednimi.

Instrukcja importowania urządzenia

Dodaj tę instrukcję importowania, aby uzyskać dostęp do IoTHubDeviceClient i MethodResponse.

# import the device client library
from azure.iot.device import IoTHubDeviceClient, MethodResponse

Nawiązywanie połączenia z urządzeniem

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

Użyj create_from_connection_string, aby połączyć aplikację z urządzeniem przy użyciu ciągu połączenia urządzenia.

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

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
Użyj 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 przykładami użycia autentykacji certyfikatu X.509 dla urządzeń, zobacz przykłady, których nazwy plików kończą się na x509 w scenariuszach centrum asynchronicznego.

Utwórz bezpośrednie wywołanie metody

Użyj on_method_request_received aby utworzyć funkcję obsługi lub korutynę, która zostanie wywołana po odebraniu metody bezpośredniej. Nasłuchujący jest powiązany ze słowem kluczowym nazwy metody, takim jak "restart". Nazwa metody może być używana w usłudze IoT Hub lub w aplikacji serwerowej w celu wyzwolenia metody zwrotnej na urządzeniu.

Funkcja obsługi powinna utworzyć metodę MethodResponse i przekazać ją do send_method_response w celu wysłania potwierdzenia odpowiedzi metody bezpośredniej do aplikacji wywołującej.

W tym przykładzie skonfigurowano bezpośrednią obsługę metody o nazwie method_request_handler.

try:
    # Attach the handler to the client
    client.on_method_request_received = method_request_handler
except:
    # In the event of failure, clean up
    client.shutdown()

W tym przykładzie metoda method_request_handler callback implementuje metodę bezpośrednią na urządzeniu. Kod jest wykonywany, gdy metoda bezpośredniego wywołania "rebootDevice" jest wywoływana z usługowej aplikacji. Metoda wywołuje send_method_response w celu przesłania potwierdzenia odbioru odpowiedzi bezpośredniej metody do aplikacji wywołującej.

# Define the handler for method requests
def method_request_handler(method_request):
    if method_request.name == "rebootDevice":
        # Act on the method by rebooting the device
        print("Rebooting device")
        time.sleep(20)
        print("Device rebooted")
        # Create a method response indicating the method request was resolved
        resp_status = 200
        resp_payload = {"Response": "This is the response from the device"}
        method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)
    else:
        # Create a method response indicating the method request was for an unknown method
        resp_status = 404
        resp_payload = {"Response": "Unknown method"}
        method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)

    # Send the method response
    client.send_method_response(method_response)

Przykłady urządzeń z zestawem SDK

Zestaw SDK usługi Azure IoT dla języka Python udostępnia działający przykład aplikacji urządzenia, która obsługuje zadania metody bezpośredniej. Aby uzyskać więcej informacji, zobacz Metoda odbierania bezpośredniego.

Tworzenie aplikacji zaplecza

W tej sekcji opisano sposób używania aplikacji usługi zaplecza do wywoływania metody bezpośredniej na urządzeniu.

Klasa IoTHubRegistryManager uwidacznia wszystkie metody wymagane do utworzenia aplikacji zaplecza w celu wysyłania komunikatów na urządzenie.

Instrukcje importu usług

Dodaj te polecenia importu, aby nawiązać połączenie z IoT Hub, wysyłać metody bezpośrednie z chmury do urządzenia i odbierać odpowiedzi na metody bezpośrednie od urządzenia.

from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import CloudToDeviceMethod, CloudToDeviceMethodResult

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

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

Aby wywołać metodę bezpośrednią na urządzeniu za pośrednictwem usługi IoT Hub, usługa wymaga uprawnień połączenia usługi. Domyślnie każde centrum IoT Hub jest tworzone przy użyciu zasad dostępu współdzielonego o nazwie usługa , która przyznaje to uprawnienie.

Jako parametr dla from_connection_string podaj zasady współdzielonego dostępu do usługi. Aby uzyskać więcej informacji na temat zasad dostępu współdzielonego, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu sygnatur dostępu współdzielonego.

Na przykład:

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

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

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

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

Konfigurowanie aplikacji Microsoft Entra

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

Tajemnica 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 usługi IoT Hub za pomocą przypisania ról RBAC na platformie Azure.

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

Uwierzytelnij się przy użyciu DefaultAzureCredential

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

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

Microsoft Entra wymaga tego pakietu importu i odpowiedniej import deklaracji:

pip install azure-identity

from azure.identity import DefaultAzureCredential

W tym przykładzie klucz tajny klienta rejestracji aplikacji Microsoft Entra, identyfikator klienta i identyfikator dzierżawy zostały dodane do zmiennych środowiskowych. Te zmienne środowiskowe są używane przez DefaultAzureCredential program do uwierzytelniania aplikacji. Wynikiem pomyślnej uwierzytelnienia Microsoft Entra jest poświadczenie tokena bezpieczeństwa, które jest przekazywane do metody połączenia z IoT Hub.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

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

IoTHubRegistryManager aby utworzyć połączenie usługowe z IoT Hub używając poświadczenia tokenu Entra.
IoTHubJobManager
Oprogramowanie DigitalTwinClient
IoTHubHttpRuntimeManager
IoTHubConfigurationManager

from_token_credential wymaga dwóch parametrów:

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

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

import sys
import os

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

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

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

# Acquire a credential object
credential = DefaultAzureCredential()

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

Przykłady kodu

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

Wywoływanie metody na urządzeniu

Możesz wywołać metodę bezpośrednią na urządzeniu, podając jej nazwę. Nazwa metody identyfikuje metodę. W poniższym i poprzednim przykładzie urządzenia pokazanym w Tworzenie wywołania zwrotnego metody bezpośredniej, nazwa tej metody to "rebootDevice".

Aby wywołać metodę bezpośrednią na urządzeniu:

Utwórz obiekt CloudToDeviceMethod. Podaj nazwę metody i ładunek jako parametry.
Wywołaj invoke_device_method , aby wywołać metodę bezpośrednią na urządzeniu. Podaj identyfikator urządzenia i CloudToDeviceMethod obiekt ładunku jako parametry.

Ten przykład wywołuje CloudToDeviceMethod aby wywołać bezpośrednią metodę o nazwie "rebootDevice" na urządzeniu. Po pomyślnym wywołaniu metody bezpośredniej, zostaje wyświetlone dane odpowiedzi tej metody.

CONNECTION_STRING = "{IoTHubConnectionString}"
DEVICE_ID = "{deviceId}"

METHOD_NAME = "rebootDevice"
METHOD_PAYLOAD = "{\"method_number\":\"42\"}"
TIMEOUT = 60
WAIT_COUNT = 10

try:
    print ( "" )
    print ( "Invoking device to reboot..." )

    # Call the direct method.
    deviceMethod = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
    response = registry_manager.invoke_device_method(DEVICE_ID, deviceMethod)

    print ( "Successfully invoked the device to reboot." )

    print ( "The device has returned this payload:" )
    print ( response.payload )

except Exception as ex:
    print ( "" )
    print ( "Unexpected error {0}".format(ex) )
    return

Przykłady usługi SDK

Zestaw SDK usługi Azure IoT dla języka Python udostępnia działające przykłady aplikacji usług, które obsługują zadania metody bezpośredniej. Aby uzyskać więcej informacji, zobacz:

Wymaga Node.js w wersji 10.0.x lub nowszej

Omówienie

W tym artykule opisano, jak używać Azure IoT SDK dla Node.js do tworzenia kodu aplikacji urządzenia oraz kodu usługi zaplecza dla metod bezpośrednich urządzenia.

Tworzenie aplikacji urządzenia

Ta sekcja opisuje, jak używać kodu aplikacji urządzenia do stworzenia bezpośredniego wywołania metody.

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

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 parametru połączenia, aby wskazać, że certyfikat jest dodany 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 certyfikacji clientOptions 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.

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

Otwieranie połączenia z usługą IoT Hub

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

Na przykład:

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

Utwórz bezpośrednie wywołanie metody

Wywołaj onDeviceMethod, aby utworzyć funkcję obsługi wywołania zwrotnego lub „coroutine” wywoływaną, gdy zostanie odebrana metoda bezpośrednia. Nasłuchujący jest powiązany ze słowem kluczowym nazwy metody, takim jak "restart". Nazwa metody może być używana w usłudze IoT Hub lub w aplikacji serwerowej w celu wyzwolenia metody zwrotnej na urządzeniu.

Funkcja obsługi wywołania zwrotnego powinna wywołać response.send, aby wysłać komunikat potwierdzający otrzymanie odpowiedzi do aplikacji wywołującej.

Ten przykład tworzy obsługę metody bezpośredniej o nazwie onReboot, która jest wywoływana, gdy używane jest bezpośrednie wywołanie metody "reboot".

client.onDeviceMethod('reboot', onReboot);

W tym przykładzie metoda onReboot callback implementuje metodę bezpośrednią na urządzeniu. Kod jest wykonywany, gdy metoda bezpośrednia "reboot" jest wywoływana z aplikacji usługi. Funkcja wywołuje response.send, aby wysłać komunikat potwierdzający odpowiedź do aplikacji wywołującej.

var onReboot = function(request, response) {

    // Respond the cloud app for the direct method
    response.send(200, 'Reboot started', function(err) {
        if (err) {
            console.error('An error occurred when sending a method response:\n' + err.toString());
        } else {
            console.log('Response to method \'' + request.methodName + '\' sent successfully.');
        }
    });

    // Add your device's reboot API for physical restart.
    console.log('Rebooting!');
};

Przykłady urządzeń z zestawem SDK

Zestaw SDK usługi Azure IoT dla Node.js udostępnia działające przykłady aplikacji urządzeń, które obsługują zadania zarządzania urządzeniami. Aby uzyskać więcej informacji, zobacz:

Tworzenie aplikacji zaplecza

W tej sekcji opisano sposób wywoływania metody bezpośredniej na urządzeniu.

Instalowanie pakietu zestawu SDK usługi

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

npm install azure-iothub --save

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

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

Aby wywołać metodę bezpośrednią na urządzeniu za pośrednictwem usługi IoT Hub, usługa wymaga uprawnień połączenia usługi. Domyślnie każde centrum IoT Hub jest tworzone przy użyciu zasad dostępu współdzielonego o nazwie usługa , która przyznaje to uprawnienie.

Jako parametr do CreateFromConnectionString podaj łańcuch połączenia polityki współdzielonego dostępu usługi. Aby uzyskać więcej informacji na temat zasad dostępu współdzielonego, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu sygnatur dostępu współdzielonego.

var Client = require('azure-iothub').Client;
var connectionString = '{IoT hub shared access policy connection string}';
var client = Client.fromConnectionString(connectionString);

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

Aplikacja zaplecza korzystająca z usługi Microsoft Entra musi pomyślnie uwierzytelnić się i uzyskać poświadczenia tokenu zabezpieczającego przed nawiązaniem połączenia z usługą IoT Hub. Ten token jest przekazywany do metody połączenia z IoT Hubem. 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:

Tajemnica 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 usługi IoT Hub za pomocą przypisania ról RBAC na platformie Azure.

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

Uwierzytelnij się przy użyciu DefaultAzureCredential

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

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.

Firma Microsoft Entra wymaga tego pakietu:

npm install --save @azure/identity

W tym przykładzie klucz tajny klienta rejestracji aplikacji Microsoft Entra, identyfikator klienta i identyfikator dzierżawy zostały dodane do zmiennych środowiskowych. Te zmienne środowiskowe są używane przez DefaultAzureCredential program do uwierzytelniania aplikacji. Wynikiem pomyślnej uwierzytelnienia Microsoft Entra jest poświadczenie tokena bezpieczeństwa, które jest przekazywane do metody połączenia z 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 dostarczane są adres URL domeny i poświadczenia platformy Azure do Registry.fromTokenCredential w celu utworzenia połączenia z usługą IoT Hub.

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

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

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

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

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

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

Przykłady kodu

Aby zapoznać się z przykładami działania uwierzytelniania w usłudze Microsoft Entra, sprawdź Przykłady tożsamości usługi Azure.

Wywoływanie metody na urządzeniu

Użyj invokeDeviceMethod aby wywołać metodę bezpośrednią według nazwy na urządzeniu. Parametr nazwy metody identyfikuje metodę bezpośrednią.

W tym przykładzie wywoływana jest metoda "reboot", aby zainicjować ponowny rozruch na urządzeniu. Metoda "reboot" jest mapowana na funkcję obsługi wywołania zwrotnego na urządzeniu, jak opisano w sekcji Tworzenie funkcji wywołania zwrotnego bezpośredniej metody tego artykułu.

var startRebootDevice = function(deviceToReboot) {

    var methodName = "reboot";

    var methodParams = {
        methodName: methodName,
        payload: null,
        timeoutInSeconds: 30
    };

    client.invokeDeviceMethod(deviceToReboot, methodParams, function(err, result) {
        if (err) {
            console.error("Direct method error: "+err.message);
        } else {
            console.log("Successfully invoked the device to reboot.");  
        }
    });
};

Przykłady usługi SDK

Zestaw SDK usługi Azure IoT dla Node.js udostępnia działające przykłady aplikacji usług obsługujących zadania zarządzania urządzeniami. Aby uzyskać więcej informacji, zobacz:

Udostępnij za pośrednictwem

Wprowadzenie do zarządzania urządzeniami

Wymagania wstępne

Omówienie

Tworzenie aplikacji urządzenia

Wymagane pakiety urządzenia NuGet

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

Utwórz nasłuchiwacza metod bezpośrednich

Przykłady urządzeń z zestawem SDK

Tworzenie aplikacji zaplecza

Wymagany pakiet usługi NuGet

Nawiązywanie połączenia z centrum IoT

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

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

Konfigurowanie aplikacji Microsoft Entra

Uwierzytelnij się przy użyciu DefaultAzureCredential

Przykład kodu

Wywoływanie metody na urządzeniu

Przykłady usługi SDK

Omówienie

Tworzenie aplikacji urządzenia

Instrukcje importowania urządzenia

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

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

Uwierzytelnianie przy użyciu certyfikatu X.509

Przykłady kodu

Utwórz nasłuchiwacza metod bezpośrednich

Przykłady urządzeń z zestawem SDK

Tworzenie aplikacji zaplecza

Instrukcje importu usług

Nawiązywanie połączenia z centrum IoT

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

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

Konfigurowanie aplikacji Microsoft Entra

Uwierzytelnij się przy użyciu DefaultAzureCredential

Uwierzytelnianie za pomocą ClientSecretCredentialBuilder

Inne klasy uwierzytelniania

Przykłady kodu

Wywoływanie metody na urządzeniu

Przykłady usługi SDK

Omówienie

Instalowanie pakietów

Tworzenie aplikacji urządzenia

Instrukcja importowania urządzenia

Nawiązywanie połączenia z urządzeniem

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

Uwierzytelnianie przy użyciu certyfikatu X.509

Przykłady kodu

Utwórz bezpośrednie wywołanie metody

Przykłady urządzeń z zestawem SDK

Tworzenie aplikacji zaplecza

Instrukcje importu usług

Nawiązywanie połączenia z centrum IoT

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

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

Konfigurowanie aplikacji Microsoft Entra

Uwierzytelnij się przy użyciu DefaultAzureCredential

Przykłady kodu

Wywoływanie metody na urządzeniu

Przykłady usługi SDK

Omówienie

Tworzenie aplikacji urządzenia

Instalowanie pakietu ZESTAWU SDK

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

Uwierzytelnianie przy użyciu certyfikatu X.509

Przykład kodu

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

Wybieranie protokołu transportowego

Tworzenie obiektu klienta

Tworzenie obiektu protokołu

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

Otwieranie połączenia z usługą IoT Hub

Utwórz bezpośrednie wywołanie metody

Przykłady urządzeń z zestawem SDK

Tworzenie aplikacji zaplecza

Instalowanie pakietu zestawu SDK usługi

Nawiązywanie połączenia z centrum IoT