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 usługi Azure IoT dla platformy .NET do tworzenia kodu aplikacji usługi urządzenia i zaplecza dla komunikatów bezpośrednich urządzeń.

Tworzenie aplikacji urządzenia

W tej sekcji opisano sposób używania kodu aplikacji urządzenia do tworzenia odbiornika wywołania zwrotnego metody bezpośredniej.

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

Nawiąż połączenie z urządzeniem przy użyciu metody CreateFromConnectionString wraz z parametry połączenia urządzenia i protokołem transportu połączenia.

Parametr CreateFromConnectionString protokoł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 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:

Tworzenie odbiornika wywołania zwrotnego metody bezpośredniej

Użyj metody SetMethodHandlerAsync , aby zainicjować odbiornik wywołania zwrotnego metody bezpośredniej. Odbiornik jest skojarzony ze słowem kluczowym nazwy metody, takim jak "reboot". Nazwa metody może być używana w usłudze IoT Hub lub aplikacji zaplecza w celu wyzwolenia metody wywołania zwrotnego na urządzeniu.

W tym przykładzie skonfigurowano odbiornik wywołania zwrotnego o nazwie onReboot , który będzie wyzwalany po wywołaniu nazwy metody bezpośredniej "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, onReboot metoda wywołania zwrotnego implementuje metodę bezpośrednią 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 wycofywanie wykładnicze), zgodnie z sugestią w obsłudze 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 NuGet usługi

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

Dodaj te using instrukcje, aby używać 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 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

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 z usługą. 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 parametru CreateFromConnectionStringpodaj zasady dostępu współdzielonego 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 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.

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 wywołania zwrotnego metody bezpośredniej 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 ZESTAWU SDK

Zestaw SDK usługi Azure IoT dla platformy .NET udostępnia działające przykłady aplikacji usługi, które obsługują zadania komunikatów. Aby uzyskać więcej informacji, zobacz:

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

Omówienie

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

Tworzenie aplikacji urządzenia

W tej sekcji opisano sposób używania kodu aplikacji urządzenia do tworzenia odbiornika wywołania zwrotnego 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 Zabezpieczenia najlepszych rozwiązań > zabezpieczeń Zabezpieczenia zabezpieczeń Zabezpieczenia zabezpieczeń.

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 Zabezpieczenia najlepszych rozwiązań > zabezpieczeń Zabezpieczenia zabezpieczeń Zabezpieczenia zabezpieczeń.

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 opcji otwórz , aby połączyć urządzenie z centrum 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 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:

Tworzenie odbiornika wywołania zwrotnego metody bezpośredniej

Użyj elementu subscribeToMethods , aby zainicjować odbiornik wywołania zwrotnego metody bezpośredniej. subscribeToMethods Nasłuchuje przychodzących metod bezpośrednich do momentu zakończenia połączenia. Nazwa metody i ładunek są odbierane dla 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 wycofywanie wykładnicze), zgodnie z sugestią w obsłudze 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 ServiceClient DeviceMethod zawiera metody, których usługi mogą używać do uzyskiwania dostępu do metod bezpośrednich.

Instrukcje importowania usługi

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

import com.microsoft.azure.sdk.iot.service.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 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 konstruktora DeviceMethod, aby dodać podstawową parametry połączenia usługi i połączyć się z usługą IoT Hub.

Aby wywołać metodę bezpośrednią na urządzeniu za pośrednictwem usługi IoT Hub, usługa wymaga uprawnień połączenia z usługą. 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 dostępu współdzielonego 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 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.

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 polecenia , 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 wywołania zwrotnego metody bezpośredniej 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 ZESTAWU 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 usługi urządzenia i zaplecza dla metod bezpośrednich urządzeń.

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

W tej sekcji opisano sposób używania kodu aplikacji urządzenia do tworzenia odbiornika wywołania zwrotnego 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 elementu 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 Zabezpieczenia najlepszych rozwiązań > zabezpieczeń Zabezpieczenia zabezpieczeń Zabezpieczenia zabezpieczeń.

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

Tworzenie wywołania zwrotnego metody bezpośredniej

Użyj on_method_request_received , aby utworzyć funkcję obsługi lub coroutine wywoływaną po odebraniu metody bezpośredniej. Odbiornik jest skojarzony ze słowem kluczowym nazwy metody, takim jak "reboot". Nazwa metody może być używana w usłudze IoT Hub lub aplikacji zaplecza w celu wyzwolenia metody wywołania zwrotnego 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 procedurę obsługi metody bezpośredniej 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 method_request_handler metoda wywołania zwrotnego implementuje metodę bezpośrednią na urządzeniu. Kod jest wykonywany, gdy metoda bezpośrednia "rebootDevice" jest wywoływana z aplikacji usługi. Metoda wywołuje send_method_response metodę w celu wysłania potwierdzenia odpowiedzi metody bezpośredniej 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 Odbieranie metody bezpośredniej.

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 importowania usługi

Dodaj te instrukcje importowania, aby nawiązać połączenie z usługą Iot Hub, wysyłać metody bezpośrednie z chmury do urządzenia i odbierać odpowiedzi metody bezpośredniej 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 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.

Aby wywołać metodę bezpośrednią na urządzeniu za pośrednictwem usługi IoT Hub, usługa wymaga uprawnień połączenia z usługą. 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 parametru from_connection_stringpodaj zasady dostępu współdzielonego 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 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 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:

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 programu DefaultAzureCredential, zobacz Łańcuchy poświadczeń w bibliotece klienta tożsamości platformy Azure dla języka Python.

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 importu i odpowiedniej import instrukcji:

pip install azure-identity

from azure.identity import DefaultAzureCredential

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.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

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

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

from_token_credential wymaga dwóch parametrów:

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

W tym przykładzie poświadczenia platformy Azure są uzyskiwane przy użyciu polecenia DefaultAzureCredential. Adres URL i poświadczenia usługi platformy Azure są następnie dostarczane w celu IoTHubRegistryManager.from_token_credential 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

Metodę bezpośrednią można wywołać według nazwy na urządzeniu. Nazwa metody identyfikuje metodę. W poniższym i poprzednim przykładzie urządzenia pokazanym w sekcji Tworzenie wywołania zwrotnego metody bezpośredniej nazwa metody bezpośredniej 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 wywołanie CloudToDeviceMethod metody bezpośredniej o nazwie "rebootDevice" na urządzeniu. Po pomyślnym wywołaniu metody bezpośredniej zostanie wyświetlony ładunek odpowiedzi metody bezpośredniej.

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 ZESTAWU 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ć zestawu SDK usługi Azure IoT dla Node.js do tworzenia kodu aplikacji usługi urządzenia i zaplecza dla metod bezpośrednich urządzeń.

Tworzenie aplikacji urządzenia

W tej sekcji opisano sposób używania kodu aplikacji urządzenia do tworzenia wywołania zwrotnego metody bezpośredniej.

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 Zabezpieczenia najlepszych rozwiązań > zabezpieczeń Zabezpieczenia zabezpieczeń Zabezpieczenia zabezpieczeń.

Uwierzytelnianie przy użyciu certyfikatu X.509

Certyfikat X.509 jest dołączony do transportu połączeń device-to-IoT Hub.

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

Wywołaj metodę fromConnectionString, aby dodać parametry połączenia modułu urządzenia lub tożsamości oraz typ transportu do Client obiektu. 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
Skonfiguruj zmienną JSON ze szczegółami certyfikatu i przekaż ją do elementu DeviceClientOptions.
Wywołaj metodę setOptions , aby dodać certyfikat I klucz X.509 (i opcjonalnie hasło) do transportu klienta.
Wywołaj połączenie otwarte , aby otworzyć połączenie z urządzenia do usługi IoT Hub.

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

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

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

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

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

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.

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

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

Tworzenie wywołania zwrotnego metody bezpośredniej

Wywołaj metodę onDeviceMethod , aby utworzyć funkcję obsługi wywołania zwrotnego lub coroutine wywoływaną po odebraniu metody bezpośredniej. Odbiornik jest skojarzony ze słowem kluczowym nazwy metody, takim jak "reboot". Nazwa metody może być używana w usłudze IoT Hub lub aplikacji zaplecza w celu wyzwolenia metody wywołania zwrotnego na urządzeniu.

Funkcja obsługi wywołania zwrotnego powinna wywołać response.send metodę w celu wysłania komunikatu potwierdzenia odpowiedzi do aplikacji wywołującej.

W tym przykładzie skonfigurowano procedurę obsługi metody bezpośredniej o nazwie onReboot , która jest wywoływana, gdy jest używana nazwa metody bezpośredniej "reboot".

client.onDeviceMethod('reboot', onReboot);

W tym przykładzie onReboot metoda wywołania zwrotnego 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 funkcję w celu wysłania komunikatu potwierdzenia odpowiedzi 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 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.

Aby wywołać metodę bezpośrednią na urządzeniu za pośrednictwem usługi IoT Hub, usługa wymaga uprawnień połączenia z usługą. 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 CreateFromConnectionStringparametru podaj parametry połączenia zasad dostępu współdzielonego 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 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.

Wywoływanie metody na urządzeniu

Użyj metody 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 zgodnie z opisem w sekcji Tworzenie wywołania zwrotnego metody bezpośredniej w tym artykule.

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 ZESTAWU 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 NuGet 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

Tworzenie odbiornika wywołania zwrotnego metody bezpośredniej

Przykłady urządzeń z zestawem SDK

Tworzenie aplikacji zaplecza

Wymagany pakiet NuGet usługi

Nawiązywanie połączenia z centrum IoT

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

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

Konfigurowanie aplikacji Microsoft Entra

Uwierzytelnianie przy użyciu wartości DefaultAzureCredential

Przykład kodu

Wywoływanie metody na urządzeniu

Przykłady usługi ZESTAWU 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

Tworzenie odbiornika wywołania zwrotnego metody bezpośredniej

Przykłady urządzeń z zestawem SDK

Tworzenie aplikacji zaplecza

Instrukcje importowania usługi

Nawiązywanie połączenia z centrum IoT

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

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

Konfigurowanie aplikacji Microsoft Entra

Uwierzytelnianie przy użyciu wartości DefaultAzureCredential

Uwierzytelnianie przy użyciu elementu ClientSecretCredentialBuilder

Inne klasy uwierzytelniania

Przykłady kodu

Wywoływanie metody na urządzeniu

Przykłady usługi ZESTAWU 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

Tworzenie wywołania zwrotnego metody bezpośredniej

Przykłady urządzeń z zestawem SDK

Tworzenie aplikacji zaplecza

Instrukcje importowania usługi

Nawiązywanie połączenia z centrum IoT

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

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

Konfigurowanie aplikacji Microsoft Entra

Uwierzytelnianie przy użyciu wartości DefaultAzureCredential

Przykłady kodu

Wywoływanie metody na urządzeniu

Przykłady usługi ZESTAWU 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

Dodawanie protokołu parametry połączenia urządzenia i transportu

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

Tworzenie wywołania zwrotnego metody bezpośredniej

Przykłady urządzeń z zestawem SDK

Tworzenie aplikacji zaplecza

Instalowanie pakietu zestawu SDK usługi

Nawiązywanie połączenia z centrum IoT