Freigeben über

Erste Schritte mit der Geräteverwaltung

  • Artikel

Back-End-Apps können Azure IoT Hub-Primitive wie Gerätezwillinge und direkte Methoden verwenden, um Aktionen zur Geräteverwaltung auf Geräten remote zu starten und zu überwachen.

Verwenden Sie eine direkte Methode von einer Back-End-App, um Geräteverwaltungsaktionen wie Neustarts, Zurücksetzen auf Werkseinstellungen und Firmwareupdates, zu initiieren.

Das Gerät ist für Folgendes verantwortlich:

  • Verarbeiten der von IoT Hub gesendeten Anforderung der direkten Methode
  • Initiieren der entsprechenden gerätespezifischen Aktion auf dem Gerät
  • Senden von Statusupdates über die gemeldeten Eigenschaften an IoT Hub

In diesem Artikel wird veranschaulicht, wie eine Back-End-App und eine Geräte-App zusammen verwendet werden können, um einen Remote-Geräteaktion über die direkte Methode zu initiieren und zu überwachen.

  • Eine Dienst-App ruft eine direkte Methode zum Neustart in einer Geräte-App über einen IoT-Hub auf.
  • Eine Geräte-App verarbeitet eine direkte Methode zum Neustarten eines Geräts.

Hinweis

Die in diesem Artikel beschriebenen Features stehen nur im Standard-Tarif von IoT Hub zur Verfügung. Weitere Informationen zu den IoT Hub-Tarifen „Basic“ und „Standard/Free“ finden Sie unter Wählen des richtigen IoT Hub-Tarifs für Ihre Lösung.

Hinweis

Dieser Artikel soll die Beispiele der Azure IoT-SDKs ergänzen, auf die in diesem Artikel verwiesen wird. Sie können SDK Tools verwenden, um Geräte- und Back-End-Anwendungen zu erstellen.

Voraussetzungen

  • Ein IoT-Hub

  • Ein registriertes Gerät

  • Wenn Ihre Anwendung das MQTT-Protokoll verwendet, stellen Sie sicher, dass der Port 8883 in Ihrer Firewall geöffnet ist. Das MQTT-Protokoll kommuniziert über den Port 8883. In einigen Netzwerkumgebungen von Unternehmen oder Bildungseinrichtungen ist dieser Port unter Umständen blockiert. Weitere Informationen und Problemumgehungen finden Sie unter Herstellen einer Verbindung mit IoT Hub (MQTT).

  • Erfordert Visual Studio

Übersicht

Dieser Artikel beschreibt, wie Sie Azure IoT-SDK für .NET verwenden, um Geräte- und Back-End-Dienstanwendungscode für direkte Nachrichten eines Geräts zu erstellen.

Erstellen einer Geräteanwendung

In diesem Abschnitt wird beschrieben, wie Geräteanwendungscode zum Erstellen eines Rückruflisteners direkter Methode verwendet wird.

Erforderliche NuGet-Gerätepakete

Geräteclientanwendungen, die in C# geschrieben wurden, erfordern das NuGet-Paket Microsoft.Azure.Devices.Client.

Fügen Sie diese using-Anweisungen hinzu, um die Gerätebibliothek zu verwenden.

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

Verbinden eines Geräts mit IoT Hub

Eine Geräte-App kann sich mit den folgenden Methoden bei IoT Hub authentifizieren:

  • Schlüssel für den gemeinsamen Zugriff
  • X.509-Zertifikat

Wichtig

Dieser Artikel enthält Schritte zum Verbinden eines Geräts mithilfe einer Shared Access Signature, was auch als symmetrische Schlüsselauthentifizierung bezeichnet wird. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung eines Geräts mit X.509-Zertifikaten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Verbindungssicherheit.

Authentifizieren mithilfe eines Schlüssels für den gemeinsamen Zugriff

Die Klasse DeviceClient macht alle Methoden verfügbar, die für die Interaktion mit Gerätenachrichten des Geräts erforderlich sind.

Stellen Sie eine Verbindung zu dem Gerät mithilfe der Methode CreateFromConnectionString sowie der Geräteverbindungszeichenfolge und dem Verbindungstransportprotokoll her.

Der Transportprotokollparameter CreateFromConnectionString TransportType unterstützt die folgenden Transportprotokolle:

  • Mqtt
  • Mqtt_WebSocket_Only
  • Mqtt_Tcp_Only
  • Amqp
  • Amqp_WebSocket_Only
  • Amqp_Tcp_Only
  • Http1

In diesem Beispiel wird mithilfe des Mqtt-Transportprotokolls eine Verbindung mit einem Gerät hergestellt.

static string DeviceConnectionString = "{IoT hub device connection string}";
static deviceClient = null;
deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
   TransportType.Mqtt);

Authentifizierung mit einem X.509-Zertifikat

So verbinden Sie ein Gerät mithilfe eines X.509-Zertifikats mit IoT Hub

  1. Verwenden Sie DeviceAuthenticationWithX509Certificate, um ein Objekt zu erstellen, das Geräte- und Zertifikatinformationen enthält. DeviceAuthenticationWithX509Certificate wird als zweiter Parameter an DeviceClient.Create übergeben (Schritt 2).

  2. Verwenden Sie DeviceClient.Create, um das Gerät mithilfe eines X.509-Zertifikats mit IoT Hub zu verbinden.

In diesem Beispiel werden die Geräte- und Zertifikatinformationen im auth DeviceAuthenticationWithX509Certificate-Objekt ausgefüllt, das an DeviceClient.Create übergeben wird.

In diesem Beispiel werden Eingabeparameterwerte für das Zertifikat zum besseren Verständnis als lokale Variablen dargestellt. Speichern Sie in einem Produktionssystem vertrauliche Eingabeparameter in Umgebungsvariablen oder an einem anderen sichereren Speicherort. Verwenden Sie z. B. Environment.GetEnvironmentVariable("HOSTNAME") zum Lesen der Umgebungsvariable mit dem Hostnamen.

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

Weitere Informationen zur Zertifikatauthentifizierung finden Sie unter:

Codebeispiele

Funktionierende Beispiele der Authentifizierung mit X.509-Zertifikaten für Geräte finden Sie unter:

Erstellen eines Rückruflisteners direkter Methode

Verwenden Sie SetMethodHandlerAsync, um einen Rückruflistener direkter Methode zu initialisieren. Der Listener ist einem Methodennamen-Schlüsselwort zugeordnet, z. B. „reboot“. Der Methodenname kann in einer IoT Hub- oder Back-End-Anwendung verwendet werden, um die Rückrufmethode auf dem Gerät auszulösen.

In diesem Beispiel wird ein Rückruflistener mit dem Namen onReboot eingerichtet, der ausgelöst wird, wenn der Name der direkten Methoden „reboot“ aufgerufen wird.

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

Anschließend implementiert die Rückrufmethode onReboot in diesem Beispiel die direkte Methode auf dem Gerät.

Die Handlerfunktion ruft MethodResponse auf, um eine Antwortbestätigung an die aufrufende Anwendung zu senden.

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

Hinweis

Der Einfachheit halber wird in diesem Artikel keine Wiederholungsrichtlinie implementiert. Im Produktionscode sollten Sie Wiederholungsrichtlinien implementieren (z.B. exponentielles Backoff), wie es in Behandeln vorübergehender Fehler vorgeschlagen wird.

Beispiele für SDK-Geräte

Das Azure IoT SDK für .NET bietet Arbeitsbeispiele von Geräte-Apps, die Aufgaben der direkten Methode verarbeiten. Weitere Informationen finden Sie unter:

Erstellen einer Back-End-Anwendung

In diesem Abschnitt wird beschrieben, wie eine direkte Methode auf einem Gerät ausgelöst wird.

Die Klasse ServiceClient macht alle Methoden verfügbar, die zum Erstellen einer Back-End-Anwendung erforderlich sind, um Anrufe der direkten Methoden an Geräte zu senden.

Erforderliches NuGet-Dienstpaket

Back-End-Dienstanwendungen erfordern das NuGet-Paket Microsoft.Azure.Devices.

Fügen Sie diese using-Anweisungen hinzu, um die Dienstbibliothek zu verwenden.

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

Herstellen einer Verbindung mit dem IoT-Hub

Sie können einen Back-End-Dienst mit IoT Hub mithilfe der folgenden Methoden verbinden:

  • SAS-Richtlinie
  • Microsoft Entra

Wichtig

Dieser Artikel enthält Schritte zum Herstellen einer Verbindung mit einem Dienst mithilfe einer Shared Access Signature. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung bei einem Dienst mit Microsoft Entra ID oder verwalteten Identitäten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Cloudsicherheit.

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

Verbinden Sie eine Back-End-Anwendung mithilfe von CreateFromConnectionString.

Ihr Dienst muss über die Berechtigung Dienstverbindung verfügen, um über IoT Hub eine direkte Methode auf einem Gerät aufrufen zu können. Standardmäßig wird jeder IoT-Hub mit einer SAS-Richtlinie namens service erstellt, die diese Berechtigung erteilt.

Geben Sie als Parameter für CreateFromConnectionString die SAS-Richtlinie für den Dienst an. Weitere Informationen zu SAS-Richtlinien finden Sie unter Steuer des Zugriffs auf IoT Hub mithilfe von Shared Access Signatures.

ServiceClient serviceClient;
string connectionString = "{IoT hub service shared access policy connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

Verbinden mit Microsoft Entra

Eine Back-End-App, die Microsoft Entra verwendet, muss erfolgreich authentifiziert werden und Anmeldeinformationen für Sicherheitstoken erhalten, bevor Sie eine Verbindung mit IoT Hub herstellen. Dieses Token wird an eine IoT Hub-Verbindungsmethode übergeben. Allgemeine Informationen zum Einrichten und Verwenden von Microsoft Entra für IoT Hub finden Sie unter Steuern des Zugriffs auf IoT Hub mithilfe von Microsoft Entra ID.

Konfigurieren der Microsoft Entra-App

Sie müssen eine Microsoft Entra-App einrichten, die für Ihre bevorzugten Authentifizierungsanmeldeinformationen konfiguriert ist. Die App enthält Parameter wie den geheimen Clientschlüssel, der von der Back-End-Anwendung zur Authentifizierung verwendet wird. Die verfügbaren Konfigurationen für die App-Authentifizierung sind:

  • Geheimer Clientschlüssel
  • Zertifikat
  • Anmeldeinformationen für Verbundidentität

Microsoft Entra-Apps erfordern je nach ausgeführten Vorgängen möglicherweise bestimmte Rollenberechtigungen. Beispielsweise ist IoT Hub Twin Contributor erforderlich, um Lese- und Schreibzugriff auf ein IoT Hub-Gerät und Modulzwilling zu ermöglichen. Weitere Informationen finden Sie unter Verwalten des Zugriffs auf IoT Hub mithilfe der Azure RBAC-Rollenzuweisung.

Weitere Informationen zum Einrichten einer Microsoft Entra-App finden Sie in der Schnellstartanleitung: Registrieren einer Anwendung bei der Microsoft Identitäts-Plattform.

Authentifizieren mithilfe von DefaultAzureCredential

Die einfachste Möglichkeit, Microsoft Entra zum Authentifizieren einer Back-End-Anwendung zu verwenden, besteht darin, DefaultAzureCredential zu verwenden. Es wird jedoch empfohlen, eine andere Methode in einer Produktionsumgebung zu verwenden, einschließlich einer bestimmten TokenCredential oder analysierten ChainedTokenCredential. Der Einfachheit halber beschreibt dieser Abschnitt die Authentifizierung mit DefaultAzureCredential und den geheimen Clientschlüssel. Weitere Informationen zu den Vor- und Nachteilen der Verwendung von DefaultAzureCredential finden Sie unter Verwendungsleitfaden für DefaultAzureCredential.

DefaultAzureCredential unterstützt verschiedene Authentifizierungsmechanismen und bestimmt den entsprechenden Anmeldeinformationstyp basierend auf der Umgebung, in der er ausgeführt wird. Es versucht, mehrere Anmeldeinformationstypen in einer Reihenfolge zu verwenden, bis sie eine funktionierende Anmeldeinformation findet.

Microsoft Entra erfordert diese NuGet-Pakete und entsprechende using Anweisungen:

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

In diesem Beispiel werden Clientschlüssel, Client-ID und Mandanten-ID der Microsoft Entra-App zu Umgebungsvariablen hinzugefügt. Diese Umgebungsvariablen werden von DefaultAzureCredential verwendet, um die Anwendung zu authentifizieren. Das Ergebnis einer erfolgreichen Microsoft Entra-Authentifizierung ist eine Sicherheitstoken-Anmeldeinformation, die an eine IoT Hub-Verbindungsmethode übergeben wird.

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

Das resultierende TokenCredential kann dann an eine Verbindung mit der IoT Hub-Methode für jeden SDK-Client übergeben werden, der Microsoft Entra-Anmeldeinformationen akzeptiert:

In diesem Beispiel wird TokenCredential an ServiceClient.Create übergeben, um ein ServiceClient-Verbindungsobjekt zu erstellen.

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

In diesem Beispiel wird TokenCredential an RegistryManager.Create übergeben, um ein RegistryManager-Objekt zu erstellen.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);
Codebeispiel

Ein funktionierendes Beispiel für die Microsoft Entra-Dienstauthentifizierung finden Sie im Beispiel für die rollenbasierte Authentifizierung.

Aufrufen einer Methode auf einem Gerät

Um einer Methode auf einem Gerät aufzurufen:

  1. Erstellen Sie ein CloudToDeviceMethod-Objekt. Geben Sie den Namen der direkten Methode des Geräts als Parameter weiter.
  2. Rufen Sie InvokeDeviceMethodAsync auf, um die Methode auf dem Gerät aufzurufen.

In diesem Beispiel wird die Methode „reboot“ aufgerufen, um einen Neustart auf dem Gerät zu initiieren. Die Methode „reboot“ wird einem Listener auf dem Gerät zugeordnet, wie im Abschnitt Erstellen eines Rückruflisteners direkter Methode in diesem Artikel beschrieben.

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

SDK-Dienstbeispiele

Das Azure IoT SDK für .NET bietet Arbeitsbeispiele von Dienst-Apps, die Nachrichtenaufgaben verarbeiten. Weitere Informationen finden Sie unter:

  • Erfordert das Java SE Development Kit 8. Wählen Sie unter Langfristiger Support unbedingt Java 8 aus, um zu den Downloads für JDK 8 zu gelangen.

Übersicht

Dieser Artikel beschreibt, wie Sie Azure IoT-SDK für Java verwenden, um Geräte- und Back-End-Dienstanwendungscode für direkte Methoden des Geräts zu erstellen.

Erstellen einer Geräteanwendung

In diesem Abschnitt wird beschrieben, wie Geräteanwendungscode zum Erstellen eines Rückruflisteners direkter Methode verwendet wird.

Die Klasse DeviceClient macht alle Methoden verfügbar, die für die Interaktion mit direkten Methoden am Gerät erforderlich sind.

Wichtig

Dieser Artikel enthält Schritte zum Verbinden eines Geräts mithilfe einer Shared Access Signature, was auch als symmetrische Schlüsselauthentifizierung bezeichnet wird. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung eines Geräts mit X.509-Zertifikaten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Verbindungssicherheit.

Geräte-Importanweisungen

Verwenden Sie die folgenden Geräte-Importanweisungen, um auf das Azure IoT SDK für Java zuzugreifen.

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;

Verbinden eines Geräts mit IoT Hub

Eine Geräte-App kann sich mit den folgenden Methoden bei IoT Hub authentifizieren:

  • Schlüssel für den gemeinsamen Zugriff
  • X.509-Zertifikat

Wichtig

Dieser Artikel enthält Schritte zum Verbinden eines Geräts mithilfe einer Shared Access Signature, was auch als symmetrische Schlüsselauthentifizierung bezeichnet wird. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung eines Geräts mit X.509-Zertifikaten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Verbindungssicherheit.

Authentifizieren mithilfe eines Schlüssels für den gemeinsamen Zugriff

So stellen Sie eine Verbindung zu einem Gerät her:

  1. Verwenden Sie IotHubClientProtocol, um ein Transportprotokoll auszuwählen. Zum Beispiel:

    IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

  2. Verwenden Sie den DeviceClient-Konstruktor, um die primäre Verbindungszeichenfolge und das Protokoll des Geräts hinzuzufügen.

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

  3. Stellen Sie für das Gerät mithilfe von open eine Verbindung mit dem IoT-Hub her. Wenn der Client bereits geöffnet ist, tut die Methode nichts.

    client.open(true);

Authentifizierung mit einem X.509-Zertifikat

So verbinden Sie ein Gerät mithilfe eines X.509-Zertifikats mit IoT Hub

  1. Erstellen Sie das SSLContext-Objekt mit buildSSLContext.
  2. Fügen Sie die SSLContext-Informationen einem ClientOptions-Objekt hinzu.
  3. Rufen Sie DeviceClient mithilfe der ClientOptions-Informationen auf, um die Verbindung zwischen Gerät und IoT Hub zu erstellen.

In diesem Beispiel werden Eingabeparameterwerte für das Zertifikat zum besseren Verständnis als lokale Variablen dargestellt. Speichern Sie in einem Produktionssystem vertrauliche Eingabeparameter in Umgebungsvariablen oder an einem anderen sichereren Speicherort. Verwenden Sie z. B. Environment.GetEnvironmentVariable("PUBLICKEY") zum Lesen der Umgebungsvariable mit der Zeichenfolge für das Zertifikat mit öffentlichem Schlüssel.

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

Weitere Informationen zur Zertifikatauthentifizierung finden Sie unter:

Codebeispiele

Funktionierende Beispiele der Authentifizierung mit X.509-Zertifikaten für Geräte finden Sie unter:

Erstellen eines Rückruflisteners direkter Methode

Verwenden Sie subscribeToMethods, um einen Rückruflistener direkter Methode zu initialisieren. subscribeToMethods lauscht auf eingehende direkte Methoden, bis die Verbindung beendet wird. Der Methodenname und die Nutzdaten werden für jeden Anruf direkter Methode empfangen.

Der Listener sollte DirectMethodResponse aufrufen, um eine Methodenantwortbestätigung an die aufrufende Anwendung zu senden.

Beispiel:

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

Hinweis

Der Einfachheit halber wird in diesem Artikel keine Wiederholungsrichtlinie implementiert. Im Produktionscode sollten Sie Wiederholungsrichtlinien implementieren (z.B. exponentielles Backoff), wie es in Behandeln vorübergehender Fehler vorgeschlagen wird.

Beispiele für SDK-Geräte

Das Azure IoT SDK für Java enthält ein praktisches Beispiel zum Testen der in diesem Artikel beschriebenen Konzepte für Geräte-Apps. Weitere Informationen finden Sie im Beispiel für die direkte Methode.

Erstellen einer Back-End-Anwendung

In diesem Abschnitt wird beschrieben, wie Sie einen Remoteneustart auf einem Gerät mithilfe einer direkten Methode initiieren.

Die Klasse ServiceClient DeviceMethod enthält Methoden, mit denen Dienste auf direkte Methoden zugreifen können.

Dienst-Importanweisungen

Verwenden Sie die folgenden Dienst-Importanweisungen, um auf das Azure IoT SDK für Java zuzugreifen.

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;

Herstellen einer Verbindung mit dem IoT-Hub

Sie können einen Back-End-Dienst mit IoT Hub mithilfe der folgenden Methoden verbinden:

  • SAS-Richtlinie
  • Microsoft Entra

Wichtig

Dieser Artikel enthält Schritte zum Herstellen einer Verbindung mit einem Dienst mithilfe einer Shared Access Signature. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung bei einem Dienst mit Microsoft Entra ID oder verwalteten Identitäten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Cloudsicherheit.

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

Verwenden Sie den Konstruktor DeviceMethod, um die primäre Verbindungszeichenfolge des Diensts hinzuzufügen und eine Verbindung mit IoT Hub herzustellen.

Ihr Dienst muss über die Berechtigung Dienstverbindung verfügen, um über IoT Hub eine direkte Methode auf einem Gerät aufrufen zu können. Standardmäßig wird jeder IoT-Hub mit einer SAS-Richtlinie namens service erstellt, die diese Berechtigung erteilt.

Geben Sie als Parameter für den Konstruktor DeviceMethod die SAS-Richtlinie für den Dienst an. Weitere Informationen zu SAS-Richtlinien finden Sie unter Steuer des Zugriffs auf IoT Hub mithilfe von Shared Access Signatures.

Zum Beispiel:

String iotHubConnectionString = "HostName=xxxxx.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey=xxxxxxxxxxxxxxxxxxxxxxxx";
DeviceMethod methodClient = new DeviceMethod(iotHubConnectionString);

Verbinden mit Microsoft Entra

Eine Back-End-App, die Microsoft Entra verwendet, muss erfolgreich authentifiziert werden und Anmeldeinformationen für Sicherheitstoken erhalten, bevor Sie eine Verbindung mit IoT Hub herstellen. Dieses Token wird an eine IoT Hub-Verbindungsmethode übergeben. Allgemeine Informationen zum Einrichten und Verwenden von Microsoft Entra für IoT Hub finden Sie unter Steuern des Zugriffs auf IoT Hub mithilfe von Microsoft Entra ID.

Eine Übersicht über die Java SDK-Authentifizierung finden Sie unter Azure-Authentifizierung mit Java und Azure Identität.

Der Einfachheit halber konzentriert sich dieser Abschnitt auf die Beschreibung der Authentifizierung mithilfe des geheimen Clientschlüssels.

Konfigurieren der Microsoft Entra-App

Sie müssen eine Microsoft Entra-App einrichten, die für Ihre bevorzugten Authentifizierungsanmeldeinformationen konfiguriert ist. Die App enthält Parameter wie den geheimen Clientschlüssel, der von der Back-End-Anwendung zur Authentifizierung verwendet wird. Die verfügbaren Konfigurationen für die App-Authentifizierung sind:

  • Geheimer Clientschlüssel
  • Zertifikat
  • Anmeldeinformationen für Verbundidentität

Microsoft Entra-Apps erfordern je nach ausgeführten Vorgängen möglicherweise bestimmte Rollenberechtigungen. Beispielsweise ist IoT Hub Twin Contributor erforderlich, um Lese- und Schreibzugriff auf ein IoT Hub-Gerät und Modulzwilling zu ermöglichen. Weitere Informationen finden Sie unter Verwalten des Zugriffs auf IoT Hub mithilfe der Azure RBAC-Rollenzuweisung.

Weitere Informationen zum Einrichten einer Microsoft Entra-App finden Sie in der Schnellstartanleitung: Registrieren einer Anwendung bei der Microsoft Identitäts-Plattform.

Authentifizieren mithilfe von DefaultAzureCredential

Die einfachste Möglichkeit, Microsoft Entra zum Authentifizieren einer Back-End-Anwendung zu verwenden, besteht darin, DefaultAzureCredential zu verwenden. Es wird jedoch empfohlen, eine andere Methode in einer Produktionsumgebung zu verwenden, einschließlich einer bestimmten TokenCredential oder analysierten ChainedTokenCredential. Weitere Informationen zu den Vor- und Nachteilen der Verwendung DefaultAzureCredentialfinden Sie unter Anmeldeinformationsketten in der Azure Identity-Clientbibliothek für Java.

DefaultAzureCredential unterstützt verschiedene Authentifizierungsmechanismen und bestimmt den entsprechenden Anmeldeinformationstyp basierend auf der Umgebung, in der er ausgeführt wird. Er versucht, mehrere Anmeldeinformationstypen in einer Reihenfolge zu verwenden, bis er eine funktionierende Anmeldeinformation findet.

Sie können Microsoft Entra-App-Anmeldeinformationen mithilfe von DefaultAzureCredentialBuilderauthentifizieren. Speichern Sie Verbindungsparameter wie geheime Clientschlüssel-Mandanten-ID, Client-ID und geheime Clientschlüsselwerte als Umgebungsvariablen. Nachdem die TokenCredential Datei erstellt wurde, übergeben Sie sie an ServiceClient oder einen anderen Generator als Parameter Anmeldeinformationen.

In diesem Beispiel versucht DefaultAzureCredentialBuilder eine Verbindung aus der in DefaultAzureCredential beschriebenen Liste zu authentifizieren. Das Ergebnis einer erfolgreichen Microsoft Entra-Authentifizierung ist eine Sicherheitstokenanmeldeinformation, die an einen Konstruktor wie ServiceClientübergeben wird.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();
Authentifizieren mit ClientSecretCredentialBuilder

Sie können ClientSecretCredentialBuilder verwenden, um eine Anmeldeinformation mithilfe von geheimen Clientinformationen zu erstellen. Bei erfolgreicher Ausführung gibt die Methode eine TokenCredential zurück, die als Parameter "Anmeldeinformationen" an ServiceClient oder einen anderen Generator übergeben werden kann.

In diesem Beispiel wurden Clientschlüssel, Client-ID und Mandanten-ID-Werte der Microsoft Entra-App zu Umgebungsvariablen hinzugefügt. Diese Umgebungsvariablen werden von ClientSecretCredentialBuilderverwendet, um die Anmeldeinformationen zu erstellen.

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();
Andere Authentifizierungsklassen

Das Java SDK enthält auch diese Klassen, die eine Back-End-App mit Microsoft Entra authentifizieren:

Codebeispiele

Arbeitsbeispiele für die Microsoft Entra-Dienstauthentifizierung finden Sie im Beispielfür die rollenbasierte Authentifizierung.

Aufrufen einer Methode auf einem Gerät

Rufen Sie DeviceMethod.invoke auf, um eine Methode auf einem Gerät aufzurufen und den Ergebnisstatus zurückzugeben.

Der Nutzdatenparameter invoke ist optional. Verwenden Sie null, wenn keine Nutzdaten bereitgestellt werden. Der Nutzdatenparameter kann verschiedene Datenformen annehmen, einschließlich Zeichenfolge, Bytearray und HashMap. Beispiele finden Sie unter Tests für die direkte Methode.

In diesem Beispiel wird die Methode „reboot“ aufgerufen, um einen Neustart auf dem Gerät zu initiieren. Die Methode „reboot“ wird einem Listener auf dem Gerät zugeordnet, wie im Abschnitt Erstellen eines Rückruflisteners direkter Methode in diesem Artikel beschrieben.

Zum Beispiel:

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

SDK-Dienstbeispiele

Das Azure IoT SDK für Java stellt ein funktionierendes Beispiel für Dienst-Apps bereit, die Aufgaben der direkten Methode verarbeiten. Weitere Informationen finden Sie unter:

  • Python SDK – Python-Version 3.7 oder höher wird empfohlen. Stellen Sie je nach Einrichtung sicher, dass die 32-Bit- bzw. die 64-Bit-Installation verwendet wird. Fügen Sie Python Ihrer plattformspezifischen Umgebungsvariablen hinzu, wenn Sie während der Installation dazu aufgefordert werden.

Übersicht

Dieser Artikel beschreibt, wie Sie Azure IoT-SDK für Python verwenden, um Geräte- und Back-End-Dienstanwendungscode für direkte Methoden des Geräts zu erstellen.

Installieren von Paketen

Die Azure-iot-Device-Bibliothek muss installiert werden, um Geräteanwendungen zu erstellen.

pip install azure-iot-device

Die Azure-iot-hub-Bibliothek muss installiert werden, um Back-End-Dienstanwendungen zu erstellen.

pip install azure-iot-hub

Erstellen einer Geräteanwendung

In diesem Abschnitt wird beschrieben, wie Geräteanwendungscode zum Erstellen eines Rückruflisteners direkter Methode verwendet wird.

Die Klasse IoTHubDeviceClient enthält Methoden, die für die Arbeit mit direkten Methoden verwendet werden können.

Geräte-Importanweisung

Fügen Sie diese Importanweisung hinzu, um auf IoTHubDeviceClient und MethodResponse zuzugreifen.

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

Mit einem Gerät verbinden

Eine Geräte-App kann sich mit den folgenden Methoden bei IoT Hub authentifizieren:

  • Schlüssel für den gemeinsamen Zugriff
  • X.509-Zertifikat

Wichtig

Dieser Artikel enthält Schritte zum Verbinden eines Geräts mithilfe einer Shared Access Signature, was auch als symmetrische Schlüsselauthentifizierung bezeichnet wird. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung eines Geräts mit X.509-Zertifikaten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Verbindungssicherheit.

Authentifizieren mithilfe eines Schlüssels für den gemeinsamen Zugriff

Verwenden Sie create_from_connection_string, um eine Anwendung mithilfe einer Geräteverbindungszeichenfolge mit einem Gerät zu verbinden.

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

Authentifizierung mit einem X.509-Zertifikat

So verbinden Sie ein Gerät mithilfe eines X.509-Zertifikats mit IoT Hub

  1. Verwenden von create_from_x509_certificate zum Hinzufügen der X.509-Zertifikatparameter
  2. Aufrufen von connect zum Herstellen einer Verbindung mit dem Geräteclient

In diesem Beispiel werden Eingabeparameterwerte für das Zertifikat zum besseren Verständnis als lokale Variablen dargestellt. Speichern Sie in einem Produktionssystem vertrauliche Eingabeparameter in Umgebungsvariablen oder an einem anderen sichereren Speicherort. Verwenden Sie z. B. os.getenv("HOSTNAME") zum Lesen der Umgebungsvariable mit dem Hostnamen.

# 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()

Weitere Informationen zur Zertifikatauthentifizierung finden Sie unter:

Codebeispiele

Beispiele für die X.509-Zertifikatauthentifizierung von Geräten finden Sie in den asynchronen Hubszenarien in den Beispielen, deren Dateinamen auf „x509“ enden.

Erstellen eines Rückrufs direkter Methode

Verwenden Sie on_method_request_received, um eine Handlerfunktion oder Coroutine zu erstellen, die aufgerufen wird, wenn eine direkte Methode empfangen wird. Der Listener ist einem Methodennamen-Schlüsselwort zugeordnet, z. B. „reboot“. Der Methodenname kann in einer IoT Hub- oder Back-End-Anwendung verwendet werden, um die Rückrufmethode auf dem Gerät auszulösen.

Die Handlerfunktion sollte eine MethodResponse erstellen und an send_method_response weitergeben, um eine Antwortbestätigung direkter Methode an die aufrufende Anwendung zu senden.

In diesem Beispiel wird ein Handler für die direkter Methode mit dem Namen method_request_handler eingerichtet.

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

In diesem Beispiel implementiert die Rückrufmethode method_request_handler die direkte Methode auf dem Gerät. Der Code wird ausgeführt, wenn die direkte Methode „rebootDevice“ von einer Dienstanwendung aufgerufen wird. Die Methode ruft send_method_response auf, um eine Antwortbestätigung direkter Methode an die aufrufende Anwendung zu senden.

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

Beispiele für SDK-Geräte

Das Azure IoT SDK für Python bietet ein praktisches Beispiel für eine Geräte-App, die Aufgaben von direkten Methoden verarbeitet. Weitere Informationen finden Sie unter Empfangen der direkten Methoden.

Erstellen einer Back-End-Anwendung

In diesem Abschnitt wird beschrieben, wie Sie eine Back-End-Dienstanwendung verwenden, um eine direkte Methode auf einem Gerät aufzurufen.

Die Klasse IoTHubRegistryManager macht alle Methoden verfügbar, die zum Erstellen einer Back-End-Anwendung zum Senden von Nachrichten an ein Gerät erforderlich sind.

Dienst-Importanweisungen

Fügen Sie diese Importanweisungen hinzu, um eine Verbindung mit Iot Hub herzustellen, direkte Methoden für Cloud-zu-Gerät zu senden und Antworten direkter Methode für Geräte zu empfangen.

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

Herstellen einer Verbindung mit dem IoT-Hub

Sie können einen Back-End-Dienst mit IoT Hub mithilfe der folgenden Methoden verbinden:

  • SAS-Richtlinie
  • Microsoft Entra

Wichtig

Dieser Artikel enthält Schritte zum Herstellen einer Verbindung mit einem Dienst mithilfe einer Shared Access Signature. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung bei einem Dienst mit Microsoft Entra ID oder verwalteten Identitäten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Cloudsicherheit.

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

Stellen Sie mithilfe von from_connection_string eine Verbindung mit dem IoT-Hub her.

Ihr Dienst muss über die Berechtigung Dienstverbindung verfügen, um über IoT Hub eine direkte Methode auf einem Gerät aufrufen zu können. Standardmäßig wird jeder IoT-Hub mit einer SAS-Richtlinie namens service erstellt, die diese Berechtigung erteilt.

Geben Sie als Parameter für from_connection_string die SAS-Richtlinie für den Dienst an. Weitere Informationen zu SAS-Richtlinien finden Sie unter Steuer des Zugriffs auf IoT Hub mithilfe von Shared Access Signatures.

Zum Beispiel:

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

Verbinden mit Microsoft Entra

Eine Back-End-App, die Microsoft Entra verwendet, muss erfolgreich authentifiziert werden und Anmeldeinformationen für Sicherheitstoken erhalten, bevor Sie eine Verbindung mit IoT Hub herstellen. Dieses Token wird an eine IoT Hub-Verbindungsmethode übergeben. Allgemeine Informationen zum Einrichten und Verwenden von Microsoft Entra für IoT Hub finden Sie unter Steuern des Zugriffs auf IoT Hub mithilfe von Microsoft Entra ID.

Eine Übersicht über die Python SDK-Authentifizierung finden Sie unter Authentifizieren von Python-Apps für Azure-Dienste mithilfe des Azure SDK für Python

Konfigurieren der Microsoft Entra-App

Sie müssen eine Microsoft Entra-App einrichten, die für Ihre bevorzugten Authentifizierungsanmeldeinformationen konfiguriert ist. Die App enthält Parameter wie den geheimen Clientschlüssel, der von der Back-End-Anwendung zur Authentifizierung verwendet wird. Die verfügbaren Konfigurationen für die App-Authentifizierung sind:

  • Geheimer Clientschlüssel
  • Zertifikat
  • Anmeldeinformationen für Verbundidentität

Microsoft Entra-Apps erfordern je nach ausgeführten Vorgängen möglicherweise bestimmte Rollenberechtigungen. Beispielsweise ist IoT Hub Twin Contributor erforderlich, um Lese- und Schreibzugriff auf ein IoT Hub-Gerät und Modulzwilling zu ermöglichen. Weitere Informationen finden Sie unter Verwalten des Zugriffs auf IoT Hub mithilfe der Azure RBAC-Rollenzuweisung.

Weitere Informationen zum Einrichten einer Microsoft Entra-App finden Sie in der Schnellstartanleitung: Registrieren einer Anwendung bei der Microsoft Identitäts-Plattform.

Authentifizieren mithilfe von DefaultAzureCredential

Die einfachste Möglichkeit, Microsoft Entra zum Authentifizieren einer Back-End-Anwendung zu verwenden, besteht darin, DefaultAzureCredential zu verwenden. Es wird jedoch empfohlen, eine andere Methode in einer Produktionsumgebung zu verwenden, einschließlich einer bestimmten TokenCredential oder analysierten ChainedTokenCredential. Der Einfachheit halber beschreibt dieser Abschnitt die Authentifizierung mit DefaultAzureCredential und den geheimen Clientschlüssel. Weitere Informationen zu den Vor- und Nachteilen der Verwendung von DefaultAzureCredential finden Sie unter Anmeldeinformationsketten in der Azure Identity-Clientbibliothek für Python.

DefaultAzureCredential unterstützt verschiedene Authentifizierungsmechanismen und bestimmt den entsprechenden Anmeldeinformationstyp basierend auf der Umgebung, in der er ausgeführt wird. Er versucht, mehrere Anmeldeinformationstypen in einer Reihenfolge zu verwenden, bis er eine funktionierende Anmeldeinformation findet.

Microsoft Entra erfordert dieses Importpaket und die entsprechende import-Anweisung:

pip install azure-identity

from azure.identity import DefaultAzureCredential

In diesem Beispiel wurden Clientschlüssel, Client-ID und Mandanten-ID der Microsoft Entra-App zu Umgebungsvariablen hinzugefügt. Diese Umgebungsvariablen werden von DefaultAzureCredential verwendet, um die Anwendung zu authentifizieren. Das Ergebnis einer erfolgreichen Microsoft Entra-Authentifizierung ist eine Sicherheitstoken-Anmeldeinformation, die an eine IoT Hub-Verbindungsmethode übergeben wird.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

Das resultierende AccessToken kann dann an from_token_credential zur Verbindung mit IoT Hub für jeden SDK-Client übergeben werden, der Microsoft Entra-Anmeldeinformationen akzeptiert:

from_token_credential erfordert zwei Parameter:

  • Die Azure-Dienst-URL – Die Azure-Dienst-URL sollte im Format {Your Entra domain URL}.azure-devices.net ohne ein https://-Präfix vorliegen. Beispiel: MyAzureDomain.azure-devices.net.
  • Das Azure-Anmeldeinformationstoken

In diesem Beispiel werden die Azure-Anmeldeinformationen mithilfe von DefaultAzureCredential erlangt. Die Azure-Dienst-URL und die Anmeldeinformationen werden dann an IoTHubRegistryManager.from_token_credential bereitgestellt, um die Verbindung mit IoT Hub zu erstellen.

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

Arbeitsbeispiele für die Microsoft Entra-Dienstauthentifizierung finden Sie unter Microsoft Authentication Library (MSAL) für Python.

Aufrufen einer Methode auf einem Gerät

Sie können eine direkte Methode anhand des Namens auf einem Gerät aufrufen. Der Methodenname identifiziert die Methode. Im folgenden und vorherigen Gerätebeispiel, das im Erstellen eines Rückrufs direkter Methode gezeigt wird, lautet der Name der direkten Methode „rebootDevice“.

So rufen Sie eine direkte Methode auf einem Gerät auf:

  1. Erstellen Sie ein CloudToDeviceMethod-Objekt. Geben Sie den Methodennamen und die Nutzdaten als Parameter an.
  2. Rufen Sie invoke_device_method auf, um eine direkte Methode auf einem Gerät aufzurufen. Geben Sie die Geräte-ID und das Nutzdatenobjekt CloudToDeviceMethod als Parameter an.

In diesem Beispiel wird CloudToDeviceMethod aufgerufen, um eine direkte Methode mit dem Namen „rebootDevice“ auf einem Gerät aufzurufen. Nachdem die direkte Methode erfolgreich aufgerufen wurde, werden die Antwortnutzdaten der direkten Methode angezeigt.

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

SDK-Dienstbeispiele

Das Azure IoT SDK für Python bietet Arbeitsbeispiele von Dienst-Apps, die Aufgaben der direkten Methode verarbeiten. Weitere Informationen finden Sie unter:

  • Erfordert die Node.js-Version 10.0.x oder höher

Übersicht

Dieser Artikel beschreibt, wie Sie Azure IoT-SDK für Node.js verwenden, um Geräte- und Back-End-Dienstanwendungscode für direkte Methoden des Geräts zu erstellen.

Erstellen einer Geräteanwendung

In diesem Abschnitt wird beschrieben, wie Geräteanwendungscode zum Erstellen eines Rückrufs direkter Methode verwendet wird.

Installieren des SDK-Pakets

Das Paket azure-iot-device enthält Objekte, die über eine Schnittstelle mit IoT-Geräten verfügen. Führen Sie diesen Befehl aus, um das Geräte-SDK azure-iot-device auf Ihrem Computer zu installieren:

npm install azure-iot-device --save

Verbinden eines Geräts mit IoT Hub

Eine Geräte-App kann sich mit den folgenden Methoden bei IoT Hub authentifizieren:

  • X.509-Zertifikat
  • Schlüssel für den gemeinsamen Zugriff

Wichtig

Dieser Artikel enthält Schritte zum Verbinden eines Geräts mithilfe einer Shared Access Signature, was auch als symmetrische Schlüsselauthentifizierung bezeichnet wird. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung eines Geräts mit X.509-Zertifikaten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Verbindungssicherheit.

Authentifizierung mit einem X.509-Zertifikat

Das X.509-Zertifikat wird an die Übertragung über die Verbindung zwischen Gerät und IoT Hub angefügt.

So konfigurieren Sie eine Verbindung zwischen einem Gerät und IoT Hub mit einem X.509-Zertifikat

  1. Rufen Sie fromConnectionString auf, um die Verbindungszeichenfolge des Gerätes oder Identitätsmoduls und den Transporttyp zum Client-Objekt hinzuzufügen. Fügen Sie der Verbindungszeichenfolge x509=true hinzu, um anzugeben, dass ein Zertifikat zu DeviceClientOptions hinzugefügt wird. Zum Beispiel:

    • Eine Geräte-Verbindungszeichenfolge:

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

    • Ein Identitätsmodul-Verbindungszeichenfolge:

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

  2. Konfigurieren Sie eine JSON-Variable mit Zertifikatdetails, und übergeben Sie sie an DeviceClientOptions.

  3. Rufen Sie setOptions auf, um dem Clienttransport ein X.509-Zertifikat und einen Schlüssel (und optional eine Passphrase) hinzuzufügen.

  4. Rufen Sie open auf, um die Verbindung vom Gerät zu IoT Hub zu öffnen.

Das folgende Beispiel zeigt Zertifikatkonfigurationsinformationen in einer JSON-Variable. Die Zertifizierungskonfiguration clientOptions wird an setOptions übergeben und die Verbindung wird mit open geöffnet.

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

Weitere Informationen zur Zertifikatauthentifizierung finden Sie unter:

Codebeispiel

Ein funktionierendes Beispiel für die Authentifizierung mit X.509-Zertifikaten finden Sie unter Einfaches Gerätebeispiel (X.509).

Authentifizieren mithilfe eines Schlüssels für den gemeinsamen Zugriff

Auswählen eines Transportprotokolls

Das Client-Objekt unterstützt die folgenden Protokolle:

  • Amqp
  • Http: Bei Verwendung von Http führt die Client-Instanz selten eine Überprüfung auf Nachrichten von IoT Hub durch (mindestens alle 25 Minuten).
  • Mqtt
  • MqttWs
  • AmqpWs

Installieren Sie die erforderlichen Transportprotokolle auf Ihrem Computer.

Mit diesem Befehl wird beispielsweise das Amqp-Protokoll installiert:

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

Weitere Informationen zu den Unterschieden zwischen der Unterstützung für MQTT, AMQP und HTTPS finden Sie unter Leitfaden zur C2D-Kommunikation und Auswählen eines Kommunikationsprotokolls.

Erstellen eines Clientobjekts

Erstellen Sie ein Client-Objekt mithilfe des installierten Pakets.

Zum Beispiel:

const Client = require('azure-iot-device').Client;
Erstellen eines Protokollobjekts

Erstellen Sie ein Protocol-Objekt mithilfe eines installierten Transportpakets.

In diesem Beispiel wird das AMQP-Protokoll zugewiesen:

const Protocol = require('azure-iot-device-amqp').Amqp;
Fügen Sie die Verbindungszeichenfolge des Geräts und das Transportprotokoll hinzu

Rufen Sie fromConnectionString auf, um Verbindungsparameter für das Gerät zu liefern:

  • connStr – Abrufen der Verbindungszeichenfolge für das Gerät.
  • transportCtor: Das Transportprotokoll

In diesem Beispiel wird das Amqp-Transportprotokoll verwendet:

const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);
Öffnen der Verbindung mit IoT Hub

Verwenden Sie die Methode open, um eine Verbindung zwischen einem IoT-Gerät und IoT Hub zu öffnen.

Zum Beispiel:

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

Erstellen eines Rückrufs direkter Methode

Rufen Sie onDeviceMethod auf, um eine Rückrufhandlerfunktion oder Coroutine zu erstellen, die aufgerufen wird, wenn eine direkte Methode empfangen wird. Der Listener ist einem Methodennamen-Schlüsselwort zugeordnet, z. B. „reboot“. Der Methodenname kann in einer IoT Hub- oder Back-End-Anwendung verwendet werden, um die Rückrufmethode auf dem Gerät auszulösen.

Die Rückrufhandlerfunktion sollte response.send aufrufen, um eine Antwortbestätigungsnachricht an die aufrufende Anwendung zu senden.

In diesem Beispiel wird ein Handler für die direkte Methode mit dem Namen onReboot eingerichtet, der aufgerufen wird, wenn der Name der direkten Methode „reboot“ verwendet wird.

client.onDeviceMethod('reboot', onReboot);

In diesem Beispiel implementiert die Rückrufmethode onReboot die direkte Methode auf dem Gerät. Der Code wird ausgeführt, wenn die direkte Methode „reboot“ von einer Dienstanwendung aufgerufen wird. Die Funktion ruft response.send auf, um eine Antwortbestätigungsnachricht an die aufrufende Anwendung zu senden.

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

Beispiele für SDK-Geräte

Das Azure IoT SDK für Node.js bietet Arbeitsbeispiele von Geräte-Apps, die Geräteverwaltungsaufgaben verarbeiten. Weitere Informationen finden Sie unter:

Erstellen einer Back-End-Anwendung

In diesem Abschnitt wird beschrieben, wie Sie eine direkte Methode auf einem Gerät aufrufen.

Dienst-SDK-Paket installieren

Führen Sie diesen Befehl aus, um azure-iothub auf Ihrem Computer zu installieren:

npm install azure-iothub --save

Herstellen einer Verbindung mit dem IoT-Hub

Sie können einen Back-End-Dienst mit IoT Hub mithilfe der folgenden Methoden verbinden:

  • SAS-Richtlinie
  • Microsoft Entra

Wichtig

Dieser Artikel enthält Schritte zum Herstellen einer Verbindung mit einem Dienst mithilfe einer Shared Access Signature. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung bei einem Dienst mit Microsoft Entra ID oder verwalteten Identitäten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Cloudsicherheit.

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

Verwenden Sie fromConnectionString, um eine Verbindung mit dem IoT-Hub herzustellen.

Ihr Dienst muss über die Berechtigung Dienstverbindung verfügen, um über IoT Hub eine direkte Methode auf einem Gerät aufrufen zu können. Standardmäßig wird jeder IoT-Hub mit einer SAS-Richtlinie namens service erstellt, die diese Berechtigung erteilt.

Geben Sie als Parameter für CreateFromConnectionString die Verbindungszeichenfolge der SAS-Richtlinie für den Dienst an. Weitere Informationen zu SAS-Richtlinien finden Sie unter Steuer des Zugriffs auf IoT Hub mithilfe von Shared Access Signatures.

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

Verbinden mit Microsoft Entra

Eine Back-End-App, die Microsoft Entra verwendet, muss erfolgreich authentifiziert werden und Anmeldeinformationen für Sicherheitstoken erhalten, bevor Sie eine Verbindung mit IoT Hub herstellen. Dieses Token wird an eine IoT Hub-Verbindungsmethode übergeben. Allgemeine Informationen zum Einrichten und Verwenden von Microsoft Entra für IoT Hub finden Sie unter Steuern des Zugriffs auf IoT Hub mithilfe von Microsoft Entra ID.

Eine Übersicht über Node.js SDK-Authentifizierung finden Sie unter:

Konfigurieren der Microsoft Entra-App

Sie müssen eine Microsoft Entra-App einrichten, die für Ihre bevorzugten Authentifizierungsanmeldeinformationen konfiguriert ist. Die App enthält Parameter wie den geheimen Clientschlüssel, der von der Back-End-Anwendung zur Authentifizierung verwendet wird. Die verfügbaren Konfigurationen für die App-Authentifizierung sind:

  • Geheimer Clientschlüssel
  • Zertifikat
  • Anmeldeinformationen für Verbundidentität

Microsoft Entra-Apps erfordern je nach ausgeführten Vorgängen möglicherweise bestimmte Rollenberechtigungen. Beispielsweise ist IoT Hub Twin Contributor erforderlich, um Lese- und Schreibzugriff auf ein IoT Hub-Gerät und Modulzwilling zu ermöglichen. Weitere Informationen finden Sie unter Verwalten des Zugriffs auf IoT Hub mithilfe der Azure RBAC-Rollenzuweisung.

Weitere Informationen zum Einrichten einer Microsoft Entra-App finden Sie in der Schnellstartanleitung: Registrieren einer Anwendung bei der Microsoft Identitäts-Plattform.

Authentifizieren mithilfe von DefaultAzureCredential

Die einfachste Möglichkeit, Microsoft Entra zum Authentifizieren einer Back-End-Anwendung zu verwenden, besteht darin, DefaultAzureCredential zu verwenden. Es wird jedoch empfohlen, eine andere Methode in einer Produktionsumgebung zu verwenden, einschließlich einer bestimmten TokenCredential oder analysierten ChainedTokenCredential. Der Einfachheit halber beschreibt dieser Abschnitt die Authentifizierung mit DefaultAzureCredential und den geheimen Clientschlüssel. Weitere Informationen zu den Vor- und Nachteilen der Verwendung von DefaultAzureCredential finden Sie unter Anmeldeinformationsketten in der Azure Identity-Clientbibliothek für JavaScript

DefaultAzureCredential unterstützt verschiedene Authentifizierungsmechanismen und bestimmt den entsprechenden Anmeldeinformationstyp basierend auf der Umgebung, in der er ausgeführt wird. Er versucht, mehrere Anmeldeinformationstypen in einer Reihenfolge zu verwenden, bis er eine funktionierende Anmeldeinformation findet.

Microsoft Entra erfordert dieses Paket:

npm install --save @azure/identity

In diesem Beispiel wurden Clientschlüssel, Client-ID und Mandanten-ID der Microsoft Entra-App zu Umgebungsvariablen hinzugefügt. Diese Umgebungsvariablen werden von DefaultAzureCredential verwendet, um die Anwendung zu authentifizieren. Das Ergebnis einer erfolgreichen Microsoft Entra-Authentifizierung ist eine Sicherheitstoken-Anmeldeinformation, die an eine IoT Hub-Verbindungsmethode übergeben wird.

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

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

Das resultierende Anmeldeinformationstoken kann dann an fromTokenCredential übergeben werden, um eine Verbindung mit IoT Hub für jeden SDK-Client herzustellen, der Microsoft Entra-Anmeldeinformationen akzeptiert:

fromTokenCredential erfordert zwei Parameter:

  • Die Azure-Dienst-URL – Die Azure-Dienst-URL sollte im Format {Your Entra domain URL}.azure-devices.net ohne ein https://-Präfix vorliegen. Beispiel: MyAzureDomain.azure-devices.net.
  • Das Azure-Anmeldeinformationstoken

In diesem Beispiel werden die Azure-Anmeldeinformationen mithilfe von DefaultAzureCredential erlangt. Die Azure-Domänen-URL und Anmeldeinformationen werden dann an Registry.fromTokenCredential bereitgestellt, um die Verbindung mit IoT Hub zu erstellen.

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

Arbeitsbeispiele für die Microsoft Entra-Dienstauthentifizierung finden Sie in Azure-Identitätsbeispielen.

Aufrufen einer Methode auf einem Gerät

Verwenden Sie invokeDeviceMethod, um eine direkte Methode anhand des Namens auf einem Gerät aufzurufen. Der Methodennamenparameter identifiziert die direkte Methode.

In diesem Beispiel wird die Methode „reboot“ aufgerufen, um einen Neustart auf dem Gerät zu initiieren. Die Methode „reboot“ wird einer Rückrufhandlerfunktion auf dem Gerät zugeordnet, wie im Abschnitt Erstellen eines Rückrufs direkter Methode in diesem Artikel beschrieben.

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

SDK-Dienstbeispiele

Das Azure IoT SDK für Node.js bietet Arbeitsbeispiele von Dienst-Apps, die Geräteverwaltungsaufgaben verarbeiten. Weitere Informationen finden Sie unter: