Senden und Empfangen von Cloud-zu-Gerät-Nachrichten

Artikel
01/02/2025

Azure IoT Hub ist ein vollständig verwalteter Dienst, der eine bidirektionale Kommunikation ermöglicht, einschließlich Cloud-zu-Gerät-Nachrichten von Lösungs-Back-Ends an Millionen von Geräten.

In diesem Artikel wird beschrieben, wie Sie die Azure IoT SDKs verwenden, um die folgenden Arten von Anwendungen zu erstellen:

Geräteanwendungen, die Cloud-zu-Gerät-Nachrichten von einer IoT Hub-Nachrichtenwarteschlange empfangen und verarbeiten
Back-End-Anwendungen, die Cloud-zu-Gerät-Nachrichten über eine IoT Hub-Nachrichtenwarteschlange an ein einzelnes Gerät senden

Dieser Artikel soll die ausführbaren SDK-Beispiele ergänzen, auf die in diesem Artikel verwiesen wird.

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.

Übersicht

Damit eine Geräteanwendung Cloud-zu-Gerät-Nachrichten empfangen kann, muss eine Verbindung mit IoT Hub hergestellt und ein Nachrichtenhandler eingerichtet werden, um eingehende Nachrichten zu verarbeiten. Die Azure IoT Hub-Geräte-SDKs stellen Klassen und Methoden bereit, mit denen ein Gerät Nachrichten vom Dienst empfangen und verarbeiten kann. In diesem Artikel werden wichtige Aspekte für jede Geräteanwendung behandelt, die Nachrichten empfängt, einschließlich:

Deklarieren eines Geräteclientobjekts
Herstellen einer Verbindung mit IoT Hub
Abrufen von Nachrichten aus der IoT Hub-Nachrichtenwarteschlange
Verarbeiten der Nachricht und Senden einer Bestätigung zurück an IoT Hub
Konfigurieren einer Wiederholungsrichtlinie für das Empfangen von Nachrichten

Damit eine Back-End-Anwendung Cloud-zu-Gerät-Nachrichten senden kann, muss eine Verbindung mit IoT Hub hergestellt werden, und Nachrichten müssen über eine IoT Hub-Nachrichtenwarteschlange gesendet werden. Die Azure IoT Hub-Dienst-SDKs stellen Klassen und Methoden bereit, die eine Anwendung zum Senden von Nachrichten an Geräte verwenden kann. In diesem Artikel werden wichtige Aspekte für jede Anwendung behandelt, die Nachrichten an Geräte sendet, einschließlich:

Deklarieren eines Dienstclientobjekts
Herstellen einer Verbindung mit IoT Hub
Erstellen und Senden der Nachricht
Empfangen von Übermittlungsfeedback
Konfigurieren einer Wiederholungsrichtlinie für das Senden von Nachrichten

Grundlegendes zur Nachrichtenwarteschlange

Um Cloud-zu-Gerät-Messaging zu verstehen, ist es wichtig, einige grundlegende Informationen über die Funktionsweise von IoT Hub-Gerätenachrichtenwarteschlangen zu kennen.

Cloud-zu-Gerät-Nachrichten, die von einer Lösungs-Back-End-Anwendung an ein IoT-Gerät gesendet werden, werden über IoT Hub weitergeleitet. Es gibt keine direkte Kommunikation mit Peer-zu-Peer-Messaging zwischen der Back-End-Anwendung der Lösung und dem Zielgerät. IoT Hub reiht eingehende Nachrichten in die Nachrichtenwarteschlange ein, wo sie von IoT-Zielgeräten heruntergeladen werden können.

Um die Nachrichtenübermittlung mindestens einmal zu gewährleisten, werden Cloud-zu-Gerät-Nachrichten in IoT Hub in gerätespezifischen Warteschlangen persistent gespeichert. Geräte müssen den Abschluss einer Nachricht explizit bestätigen, bevor IoT Hub die Nachricht aus der Warteschlange entfernt. Auf diese Weise wird Resilienz bei Verbindungs- und Gerätefehlern gewährleistet.

Wenn IoT Hub eine Nachricht in eine Gerätenachrichtenwarteschlange einreiht, wird der Nachrichtenstatus auf Enqueued (In Warteschlange eingereiht) festgelegt. Wenn ein Gerätethread eine Nachricht aus der Warteschlange abruft, sperrt IoT Hub die Nachricht, indem ihr Status auf Nicht sichtbar gesetzt wird. Dieser Status verhindert, dass andere Threads auf dem Gerät dieselbe Nachricht verarbeiten. Wenn ein Gerätethread die Verarbeitung einer Nachricht erfolgreich abgeschlossen hat, benachrichtigt er IoT Hub, und IoT Hub legt dann den Nachrichtenstatus auf Abgeschlossen fest.

Wenn eine Geräteanwendung eine Nachricht erfolgreich empfängt und verarbeitet, wird dies als Abschließen der Nachricht bezeichnet. Bei Bedarf kann ein Gerät jedoch auch folgende Aktionen ausführen:

Ablehnen der Nachricht: Dies führt dazu, dass IoT Hub die Nachricht in den Status „Dead lettered“ (Unzustellbar) versetzt. Geräte, die über das MQTT-Protokoll (Message Queuing Telemetry Transport) eine Verbindung herstellen, können C2D-Nachrichten nicht ablehnen.
Abbrechen der Nachricht: Dies führt dazu, dass IoT Hub die Nachricht wieder in die Warteschlange einreiht und den Status der Nachricht in Enqueued (In Warteschlange eingereiht) ändert. Geräte, die über das MQTT-Protokoll eine Verbindung herstellen, können C2D-Nachrichten nicht ablehnen.

Ausführlichere Informationen zum Lebenszyklus von Cloud-zu-Gerät-Nachrichten und zur Weise, in der IoT Hub Cloud-zu-Gerät-Nachrichten verarbeitet, finden Sie unter Senden von C2D-Nachrichten von einem IoT Hub.

Erstellen einer Geräteanwendung

In diesem Abschnitt wird beschrieben, wie Cloud-zu-Gerät-Nachrichten empfangen werden.

Es gibt zwei Optionen, die eine Geräteclientanwendung verwenden kann, um Nachrichten zu empfangen:

Rückruf: Die Geräteanwendung richtet eine asynchrone Nachrichtenhandlermethode ein, die sofort aufgerufen wird, wenn eine Nachricht eingeht.
Abruf: Die Geräteanwendung führt mithilfe einer Codeschleife (z. B. mit einer while- oder for-Schleife) Überprüfungen auf neue IoT Hub-Nachrichten durch. Die Schleife wird kontinuierlich ausgeführt und überprüft, ob Nachrichten vorhanden sind.

Erforderliches NuGet-Gerätepaket

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 das Empfangen von Nachrichten auf dem Gerät erforderlich sind.

Bereitstellen der Verbindungsparameter

Stellen Sie die primäre IoT Hub-Verbindungszeichenfolge und die Geräte-ID mithilfe der CreateFromConnectionString-Methode für DeviceClient bereit. Zusätzlich zur erforderlichen primären IoT Hub-Verbindungszeichenfolge kann die CreateFromConnectionString-Methode so überladen werden, dass sie die folgenden optionalen Parameter enthält:

transportType: Das Transportprotokoll – Variationen von HTTP Version 1, AMQP oder MQTT. AMQP ist die Standardoption. Alle verfügbaren Werte finden Sie unter TransportType-Enumeration.
transportSettings: Schnittstelle, die zum Definieren verschiedener transportspezifischer Einstellungen für DeviceClient und ModuleClient verwendet wird. Weitere Informationen finden Sie unter ITransportSettings Interface.
ClientOptions: Optionen, die das Konfigurieren der Geräte- oder Modulclientinstanz während der Initialisierung ermöglichen.

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

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

Rückruf

Um Cloud-zu-Gerät-Rückrufnachrichten in der Geräteanwendung zu empfangen, muss eine Verbindung zwischen der Geräteanwendung und IoT Hub hergestellt und ein Rückruflistener eingerichtet werden, um eingehende Nachrichten zu verarbeiten. Eingehende Nachrichten an das Gerät werden von der IoT Hub-Nachrichtenwarteschlange empfangen.

Bei Verwendung eines Rückrufs richtet die Geräteanwendung mithilfe von SetReceiveMessageHandlerAsync eine Nachrichtenhandlermethode ein. Der Nachrichtenhandler wird aufgerufen, und anschließend wird eine Nachricht empfangen. Durch das Erstellen einer Rückrufmethode zum Empfangen von Nachrichten ist kein kontinuierlicher Abruf für empfangene Nachrichten mehr erforderlich.

Rückrufe sind nur bei Verwendung der folgenden Protokolle verfügbar:

Mqtt
Mqtt_WebSocket_Only
Mqtt_Tcp_Only
Amqp
Amqp_WebSocket_Only
Amqp_Tcp_only

Die Http1-Protokolloption unterstützt keine Rückrufe, da die SDK-Methoden dennoch einen Abruf für empfangene Nachrichten durchführen müssten, was dem Rückrufprinzip widerspricht.

In diesem Beispiel richtet SetReceiveMessageHandlerAsync eine Rückrufhandlermethode namens OnC2dMessageReceivedAsync ein, die jedes Mal aufgerufen wird, wenn eine Nachricht empfangen wird.

// Subscribe to receive C2D messages through a callback (which isn't supported over HTTP).
await deviceClient.SetReceiveMessageHandlerAsync(OnC2dMessageReceivedAsync, deviceClient);
Console.WriteLine($"\n{DateTime.Now}> Subscribed to receive C2D messages over callback.");

Abruf

Beim Abruf wird ReceiveAsync verwendet, um eine Überprüfung auf Nachrichten durchzuführen.

Das Aufrufen von ReceiveAsync kann wie folgt aussehen:

ReceiveAsync(): Warten mit dem Fortfahren, bis der Standardtimeoutzeitraum für eine Nachricht vergangen ist
ReceiveAsync (Timespan): Empfangen einer Nachricht aus der Gerätewarteschlange mit einem bestimmten Timeout
ReceiveAsync (CancellationToken): Empfangen einer Nachricht aus der Gerätewarteschlange mit einem Abbruchtoken. Bei Verwendung eines Abbruchtokens wird der Standardtimeoutzeitraum nicht verwendet.

Wenn anstelle von MQTT oder AMQP HTTP 1 als Transporttyp verwendet wird, erfolgt von der ReceiveAsync-Methode sofort eine Rückgabe. Das unterstützte Muster für Cloud-zu-Gerät-Nachrichten mit HTTP 1 ist zeitweilig mit Geräten verbunden, die selten eine Überprüfung auf Nachrichten durchführen (mindestens alle 25 Minuten). Die Ausgabe von mehr HTTP 1-Empfangsvorgängen führt dazu, dass die Anforderungen von IoT Hub gedrosselt werden. Weitere Informationen zu den Unterschieden bei der Unterstützung von MQTT, AMQP und HTTP 1 finden Sie unter Leitfaden zur C2D-Kommunikation und Auswählen eines Kommunikationsprotokolls.

CompleteAsync-Methode

Nachdem das Gerät eine Nachricht empfangen hat, ruft die Geräteanwendung die CompleteAsync-Methode auf, um IoT Hub darüber zu benachrichtigen, dass die Nachricht erfolgreich verarbeitet wurde und sicher aus der IoT Hub-Gerätewarteschlange entfernt werden kann. Das Gerät sollte diese Methode unabhängig vom verwendeten Transportprotokoll aufrufen, wenn seine Verarbeitung erfolgreich abgeschlossen wurde.

Abbrechen, Ablehnen oder Timeout einer Nachricht

Mit den Protokollen AMQP und HTTP Version 1, aber nicht mit dem MQTT-Protokoll, kann das Gerät auch Folgendes:

Abbrechen einer Nachricht durch Aufrufen von AbandonAsync. Dies führt dazu, dass IoT Hub die Nachricht für eine zukünftige Nutzung in der Gerätewarteschlange beibehält.
Ablehnen einer Nachricht durch Aufrufen von RejectAsync. Hierdurch wird die Nachricht dauerhaft aus der Gerätewarteschlange entfernt.

Wenn etwas passiert, wodurch verhindert wird, dass das Gerät die Nachricht abschließt, vorübergehend verwirft oder ablehnt, stellt IoT Hub sie nach einem festgelegten Zeitlimit zur erneuten Übermittlung in die Warteschlange. Aus diesem Grund muss die Nachrichtenverarbeitungslogik in der Geräte-App idempotent sein, sodass der mehrmalige Empfang derselben Nachricht dasselbe Ergebnis erzeugt.

Abrufschleife

Beim Abrufen verwendet eine Anwendung eine Codeschleife, die die ReceiveAsync-Methode wiederholt aufruft, um eine Überprüfung auf neue Nachrichten durchzuführen, bis sie angehalten wird.

Wenn ReceiveAsync mit einem Timeoutwert oder dem Standardtimeout verwendet wird, wird in der Schleife bei jedem Aufruf von ReceiveAsync bis zum Ende des angegebenen Timeoutzeitraums gewartet. Wenn bei ReceiveAsync ein Timeout auftritt, wird ein null-Wert zurückgegeben, und die Schleife wird weiter ausgeführt.

Wenn eine Nachricht empfangen wird, wird von ReceiveAsync ein Task-Objekt zurückgegeben, das an CompleteAsync weitergegeben werden sollte. Wenn CompleteAsync aufgerufen wird, wird IoT Hub darüber benachrichtigt, dass die angegebene Nachricht basierend auf dem Parameter Task aus der Nachrichtenwarteschlange gelöscht werden soll.

In diesem Beispiel ruft die Schleife ReceiveAsync auf, bis eine Nachricht empfangen oder die Abrufschleife angehalten wird.

static bool stopPolling = false;

while (!stopPolling)
{
   // Check for a message. Wait for the default DeviceClient timeout period.
   using Message receivedMessage = await _deviceClient.ReceiveAsync();

   // Continue if no message was received
   if (receivedMessage == null)
   {
      continue;
   }
   else  // A message was received
   {
      // Print the message received
      Console.WriteLine($"{DateTime.Now}> Polling using ReceiveAsync() - received message with Id={receivedMessage.MessageId}");
      PrintMessage(receivedMessage);

      // Notify IoT Hub that the message was received. IoT Hub will delete the message from the message queue.
      await _deviceClient.CompleteAsync(receivedMessage);
      Console.WriteLine($"{DateTime.Now}> Completed C2D message with Id={receivedMessage.MessageId}.");
   }

   // Check to see if polling loop should end
   stopPolling = ShouldPollingstop ();
}

Wiederholungsrichtlinie für das Empfangen von Nachrichten

Die Nachrichtenwiederholungsrichtlinie für Geräteclients kann mithilfe von DeviceClient.SetRetryPolicy definiert werden.

Der Wert für das Wiederholungstimeout für Nachrichten wird in der Eigenschaft DeviceClient.OperationTimeoutInMilliseconds gespeichert.

SDK-Beispiel für empfangene Nachrichten

Das SDK für .NET bzw. C# enthält ein Beispiel für empfangene Nachrichten, das die in diesem Abschnitt beschriebenen Methoden zum Empfangen von Nachrichten umfasst.

Erstellen einer Back-End-Anwendung

In diesem Abschnitt wird der grundlegende Code zum Senden einer Nachricht von einer Lösungs-Back-End-Anwendung an ein IoT-Gerät mithilfe der Klasse ServiceClient im Azure IoT SDK für .NET beschrieben. Wie bereits erwähnt, wird eine Verbindung zwischen einer Lösungs-Back-End-Anwendung und IoT Hub hergestellt, und es werden mit einem Zielgerät codierte Nachrichten an IoT Hub gesendet. IoT Hub speichert eingehende Nachrichten in der Nachrichtenwarteschlange, und Nachrichten werden von der IoT Hub-Nachrichtenwarteschlange an das Zielgerät übermittelt.

Eine Lösungs-Back-End-Anwendung kann auch Übermittlungsfeedback für eine an IoT Hub gesendete Nachricht anfordern und empfangen, die für die Übermittlung an das Gerät über die Nachrichtenwarteschlange bestimmt ist.

Hinzufügen des NuGet-Dienstpakets

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

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

Bereitstellen der Verbindungszeichenfolge

Verbinden Sie eine Back-End-Anwendung mit einem Gerät mithilfe von CreateFromConnectionString. Zusätzlich zur erforderlichen primären IoT Hub-Verbindungszeichenfolge kann die CreateFromConnectionString-Methode so überladen werden, dass sie die folgenden optionalen Parameter enthält:

transportType - Amqp oder Amqp_WebSocket_Only
transportSettings: Die AMQP- und HTTP-Proxyeinstellungen für den Dienstclient
ServiceClientOptions: Optionen, die das Konfigurieren der Dienstclientinstanz während der Initialisierung ermöglichen. Weitere Informationen finden Sie unter ServiceClientOptions.

In diesem Beispiel wird das ServiceClient-Objekt mithilfe der IoT Hub-Verbindungszeichenfolge und dem Standardtransport Amqp erstellt.

static string connectionString = "{your IoT hub 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.

Senden einer asynchronen Cloud-zu-Gerät-Nachricht

Verwenden Sie sendAsync, um eine asynchrone Nachricht von einer Anwendung über die Cloud (IoT Hub) an das Gerät zu senden. Als Protokoll für den Aufruf wird AMQP verwendet.

sendAsync verwendet die folgenden Parameter:

deviceID: Zeichenfolgenbezeichner des Zielgeräts
message: Cloud-zu-Gerät-Nachricht. Die Nachricht ist vom Typ Message und kann entsprechend formatiert werden.
timeout: Optionaler Timeoutwert. Wenn nichts angegeben wird, beträgt der Standardwert eine Minute.

In diesem Beispiel wird eine Testnachricht an das Zielgerät mit einem Timeoutwert von 10 Sekunden gesendet.

string targetDevice = "Device-1";
static readonly TimeSpan operationTimeout = TimeSpan.FromSeconds(10);
var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
await serviceClient.SendAsync(targetDevice, commandMessage, operationTimeout);

Empfangen von Übermittlungsfeedback

Ein sendendes Programm kann für alle Cloud-zu-Gerät-Nachrichten Übermittlungsbestätigungen (oder Ablaufbestätigungen) von IoT Hub anfordern. Mit dieser Option kann das sendende Programm Informations-, Wiederholungs- oder Kompensierungslogik verwenden. Eine vollständige Beschreibung der Nachrichtenfeedbackvorgänge und -eigenschaften ist unter Nachrichtenfeedback zu finden.

So empfangen Sie Feedback zur Nachrichtenübermittlung:

Erstellen Sie das Objekt feedbackReceiver
Senden Sie Nachrichten mithilfe des Parameters Ack.
Warten Sie darauf, Feedback zu empfangen.

Erstellen des feedbackReceiver-Objekts

Rufen Sie GetFeedbackReceiver auf, um ein FeedbackReceiver-Objekt zu erstellen. FeedbackReceiver enthält Methoden, die Dienste zum Ausführen von Feedbackempfangsvorgängen verwenden können.

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

Senden von Nachrichten mithilfe des Parameters Ack

Damit Übermittlungsfeedback empfangen wird, muss jede Nachricht einen Wert für die Übermittlungsbestätigungseigenschaft Ack enthalten. Die Eigenschaft Ack kann einen der folgenden Werte aufweisen:

Keinen (Standard): Es wird keine Feedbacknachricht generiert.
Positive: Sie erhalten eine Feedbacknachricht, wenn die Nachricht abgeschlossen wurde.
Negative: Sie erhalten eine Feedbacknachricht, wenn die Nachricht abgelaufen ist (oder die maximale Übermittlungsanzahl erreicht wurde), ohne dass sie vom Gerät abgeschlossen wurde.
Full: Feedback für Ergebnisse sowohl für Positive als auch für Negative

In diesem Beispiel wird die Eigenschaft Ack auf Full festgelegt, wodurch für eine Nachricht sowohl positives als auch negatives Feedback zur Nachrichtenübermittlung angefordert wird.

var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
commandMessage.Ack = DeliveryAcknowledgement.Full;
await serviceClient.SendAsync(targetDevice, commandMessage);

Warten auf das Empfangen von Feedback

Definieren Sie ein CancellationToken. Rufen Sie dann in einer Schleife wiederholt ReceiveAsync auf, um eine Überprüfung auf Übermittlungsfeedbacknachrichten durchzuführen. Bei jedem Aufruf von ReceiveAsync wird bis zum Ende des für das ServiceClient-Objekt definierten Timeoutzeitraums gewartet.

Wenn ein ReceiveAsync-Timeoutzeitraum endet, ohne dass eine Nachricht empfangen wird, gibt ReceiveAsync null zurück, und die Schleife wird weiter ausgeführt.
Wenn eine Feedbacknachricht empfangen wird, wird von ReceiveAsync ein Task-Objekt zurückgegeben, das zusammen mit dem Abbruchtoken an CompleteAsync weitergegeben werden sollte. Wenn CompleteAsync aufgerufen wird, wird die angegebene gesendete Nachricht basierend auf dem Parameter Task aus der Nachrichtenwarteschlange gelöscht.
Bei Bedarf kann der Empfangscode AbandonAsync aufrufen, um eine gesendete Nachricht wieder in die Warteschlange einzureihen.

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

// Define the cancellation token.
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;
// Call ReceiveAsync, passing the token. Wait for the timout period.
var feedbackBatch = await feedbackReceiver.ReceiveAsync(token);
if (feedbackBatch == null) continue;

In diesem Beispiel wird eine Methode gezeigt, die diese Schritte enthält.

private async static void ReceiveFeedbackAsync()
{
      var feedbackReceiver = serviceClient.GetFeedbackReceiver();

      Console.WriteLine("\nReceiving c2d feedback from service");
      while (true)
      {
         // Check for messages, wait for the timeout period.
         var feedbackBatch = await feedbackReceiver.ReceiveAsync();
         // Continue the loop if null is received after a timeout.
         if (feedbackBatch == null) continue;

         Console.ForegroundColor = ConsoleColor.Yellow;
         Console.WriteLine("Received feedback: {0}",
            string.Join(", ", feedbackBatch.Records.Select(f => f.StatusCode)));
         Console.ResetColor();

         await feedbackReceiver.CompleteAsync(feedbackBatch);
      }
   }

Beachten Sie, dass dieses Feedbackempfangsmuster dem Muster ähnelt, das zum Empfangen von Cloud-zu-Gerät-Nachrichten in der Geräteanwendung verwendet wird.

Erneutes Herstellen einer Verbindung mit dem Dienstclient

Wenn eine Ausnahme auftritt, leitet der Dienstclient diese Informationen an die aufrufende Anwendung weiter. Es wird empfohlen, dass Sie in diesem Fall die Ausnahmedetails prüfen und erforderliche Maßnahmen ergreifen.

Zum Beispiel:

Wenn es sich um eine Netzwerkausnahme handelt, können Sie den Vorgang wiederholen.
Wenn es sich um eine Sicherheitsausnahme handelt (Ausnahme wegen fehlender Autorisierung), überprüfen Sie Ihre Anmeldeinformationen, und stellen Sie sicher, dass diese auf dem neuesten Stand sind.
Wenn es sich um eine Ausnahme aufgrund einer Drosselung bzw. Kontingentüberschreitung handelt, überwachen und/oder ändern Sie die Sendehäufigkeit der Anforderungen, oder aktualisieren Sie die Skalierungseinheit Ihrer Hubinstanz. Weitere Informationen finden Sie unter Referenz: IoT Hub-Kontingente und Drosselung.

Wiederholungsrichtlinie für das Senden von Nachrichten

Die Nachrichtenwiederholungsrichtlinie für ServiceClient kann mithilfe von ServiceClient.SetRetryPolicy definiert werden.

SDK-Beispiel für gesendete Nachrichten

Das SDK für .NET bzw. C# enthält ein Dienstclientbeispiel, das die in diesem Abschnitt beschriebenen Methoden zum Senden von Nachrichten umfasst.

Erstellen einer Geräteanwendung

In diesem Abschnitt wird beschrieben, wie Sie Cloud-zu-Gerät-Nachrichten mithilfe der Klasse DeviceClient aus dem Azure IoT SDK für Java empfangen.

Damit eine Java-basierte Geräteanwendung Cloud-zu-Gerät-Nachrichten empfangen kann, müssen eine Verbindung mit IoT Hub hergestellt und anschließend ein Rückruflistener und ein Nachrichtenhandler eingerichtet werden, um eingehende Nachrichten von IoT Hub zu verarbeiten.

Importieren von Azure IoT Java SDK-Bibliotheken

Für den Code in diesem Artikel werden die folgenden SDK-Bibliotheken verwendet.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;

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

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

Die DeviceClient-Objektinstanziierung erfordert folgende Parameter:

connString: Verbindungszeichenfolge für das IoT-Gerät. Die Verbindungszeichenfolge ist eine Gruppe von durch „;“ getrennten Schlüssel-Wert-Paaren, bei denen die Schlüssel und Werte jeweils durch „=“ getrennt sind. Sie sollte Werte für folgende Schlüssel enthalten: HostName, DeviceId, and SharedAccessKey.
Transportprotokoll-: Für die DeviceClient-Verbindung kann eines der folgenden IoTHubClientProtocol-Transportprotokolle verwendet werden. AMQP ist am vielseitigsten und ermöglicht ein häufiges Überprüfen auf Nachrichten sowie das Ablehnen und Abbrechen von Nachrichten. MQTT unterstützt keine Ablehnungs- und Abbruchmethoden für Nachrichten.
- AMQPS
- AMQPS_WS
- HTTPS
- MQTT
- MQTT_WS

Zum Beispiel:

static string connectionString = "{IOT hub device connection string}";
static protocol = IotHubClientProtocol.AMQPS;
DeviceClient client = new DeviceClient(connectionString, protocol);

Authentifizierung mit einem X.509-Zertifikat

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

Erstellen Sie das SSLContext-Objekt mit buildSSLContext.
Fügen Sie die SSLContext-Informationen einem ClientOptions-Objekt hinzu.
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:

Festlegen der Nachrichtenrückrufmethode

Verwenden Sie die setMessageCallback-Methode, um eine Nachrichtenhandlermethode zu definieren, die benachrichtigt wird, wenn eine Nachricht von IoT Hub empfangen wird.

setMessageCallback enthält die folgenden Parameter:

callback: Name der Rückrufmethode. Kann null sein.
context: Optionaler Kontext vom Typ object. Wenn nichts angegeben wird, wird null verwendet.

In diesem Beispiel wird eine callback-Methode mit dem Namen MessageCallback ohne Kontextparameter an setMessageCallback weitergegeben.

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

Erstellen eines Rückrufnachrichtenhandlers

Ein Rückrufnachrichtenhandler empfängt und verarbeitet eine eingehende Nachricht, die von der IoT Hub-Nachrichtenwarteschlange weitergegeben wird.

In diesem Beispiel verarbeitet der Nachrichtenhandler eine eingehende Nachricht und gibt dann IotHubMessageResult.COMPLETE zurück. Mit dem Rückgabewert IotHubMessageResult.COMPLETE wird IoT Hub darüber benachrichtigt, dass die Nachricht erfolgreich verarbeitet wurde und sicher aus der Gerätewarteschlange entfernt werden kann. Das Gerät sollte unabhängig vom verwendeten Protokoll IotHubMessageResult.COMPLETE zurückgeben, wenn die Verarbeitung erfolgreich abgeschlossen wurde, um IoT Hub darüber zu benachrichtigen, dass die Nachricht aus der Nachrichtenwarteschlange entfernt werden soll.

  protected static class MessageCallback implements com.microsoft.azure.sdk.iot.device.MessageCallback
  {
      public IotHubMessageResult onCloudToDeviceMessageReceived(Message msg, Object context)
      {
          System.out.println(
                  "Received message with content: " + new String(msg.getBytes(), Message.DEFAULT_IOTHUB_MESSAGE_CHARSET));
          // Notify IoT Hub that the message
          return IotHubMessageResult.COMPLETE;
      }
  }

Abbruch- und Ablehnungsoptionen für Nachrichten

Auch wenn der Großteil der eingehenden Nachrichten für ein Gerät erfolgreich empfangen werden und zu IotHubMessageResult.COMPLETE führen sollte, kann es sein, dass eine Nachricht abgebrochen oder abgelehnt werden muss.

Mit AMQP und HTTPS, aber nicht MQTT, kann eine Anwendung Folgendes:
- IotHubMessageResult.ABANDON für die Nachricht ausführen. IoT Hub setzt die Nachricht erneut in die Warteschlange und sendet sie später noch mal.
- IotHubMessageResult.REJECT für die Nachricht ausführen. IoT Hub setzt die Nachricht nicht erneut in die Warteschlange und löscht sie endgültig aus der Nachrichtenwarteschlange.
Clients, die MQTT oder MQTT_WS verwenden, können für Nachrichten nicht ABANDON oder REJECT ausführen.

Hinweis

Wenn Sie statt MQTT oder AMQP den HTTPS-Transport verwenden, prüft die DeviceClient-Instanz nur selten (mindestens alle 25 Minuten), ob Nachrichten von IoT Hub vorliegen. 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 der Rückrufmethode für den Nachrichtenstatus

Eine Anwendung kann registerConnectionStatusChangeCallback verwenden, um eine Rückrufmethode zu registrieren, die ausgeführt werden soll, wenn sich der Verbindungsstatus des Geräts ändert. Auf diese Weise kann die Anwendung eine unterbrochene Nachrichtenverbindung erkennen und versuchen, die Verbindung wiederherzustellen.

In diesem Beispiel wird IotHubConnectionStatusChangeCallbackLogger als Rückrufmethode für Änderungen des Verbindungsstatus registriert.

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

Der Rückruf wird ausgelöst, und es wird ein ConnectionStatusChangeContext-Objekt weitergegeben.

Rufen Sie connectionStatusChangeContext.getNewStatus() auf, um den aktuellen Verbindungsstatus abzurufen.

IotHubConnectionStatus status = connectionStatusChangeContext.getNewStatus();

Als Verbindungsstatus kann einer der folgenden Werte zurückgegeben werden:

IotHubConnectionStatus.DISCONNECTED
IotHubConnectionStatus.DISCONNECTED_RETRYING
IotHubConnectionStatus.CONNECTED

Rufen Sie connectionStatusChangeContext.getNewStatusReason() auf, um den Grund für die Änderung des Verbindungsstatus abzurufen.

IotHubConnectionStatusChangeReason statusChangeReason = connectionStatusChangeContext.getNewStatusReason();

Rufen Sie connectionStatusChangeContext.getCause() auf, um nach dem Grund für die Änderung des Verbindungsstatus zu suchen. getCause() kann null zurückgeben, wenn keine Informationen verfügbar sind.

Throwable throwable = connectionStatusChangeContext.getCause();
if (throwable != null)
    throwable.printStackTrace();

In dem HandleMessages-Beispiel im Abschnitt SDK-Beispiel für empfangene Nachrichten dieses Artikels finden Sie ein vollständiges Beispiel, in dem gezeigt wird, wie Sie den Änderungsstatus für den Verbindungsstatus der Rückrufmethode für Statusänderungen, den Grund für die Änderung des Gerätestatus und den Kontext extrahieren.

Öffnen der Verbindung zwischen Gerät und IoT Hub

Verwenden Sie open, um eine Verbindung zwischen dem Gerät und IoT Hub herzustellen. Das Gerät kann jetzt asynchron Nachrichten an IoT Hub senden und von IoT Hub empfangen. Wenn der Client bereits geöffnet ist, tut die Methode nichts.

client.open(true);

SDK-Beispiel für empfangene Nachrichten

HandleMessages: Eine im Microsoft Azure IoT SDK für Java enthaltene Beispiel-Geräte-App, die eine Verbindung mit Ihrem IoT Hub herstellt und Cloud-zu-Gerät-Nachrichten empfängt.

Erstellen einer Back-End-Anwendung

In diesem Abschnitt wird beschrieben, wie Sie Cloud-zu-Gerät-Nachrichten mithilfe der Klasse ServiceClient aus dem Azure IoT SDK für Java senden. Es wird eine Verbindung zwischen einer Lösungs-Back-End-Anwendung und IoT Hub hergestellt, und es werden mit einem Zielgerät codierte Nachrichten an IoT Hub gesendet. IoT Hub speichert eingehende Nachrichten in der Nachrichtenwarteschlange, und Nachrichten werden von der IoT Hub-Nachrichtenwarteschlange an das Zielgerät übermittelt.

Hinzufügen der Abhängigkeitsanweisung

Fügen Sie die Abhängigkeit hinzu, um in Ihrer Anwendung das Paket iothub-java-service-client für die Kommunikation mit Ihrem IoT Hub-Dienst zu verwenden:

<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.7.23</version>
</dependency>

Hinzufügen von Importanweisungen

Fügen Sie diese import-Anweisungen hinzu, um das Azure IoT Java SDK und den Ausnahmehandler zu verwenden.

import com.microsoft.azure.sdk.iot.service.*;
import java.io.IOException;
import java.net.URISyntaxException;

Herstellen der 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

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

Definieren des Verbindungsprotokolls

Verwenden Sie IotHubServiceClientProtocol, um das vom Dienstclient für die Kommunikation mit IoT Hub verwendete Anwendungsschichtprotokoll zu definieren.

IotHubServiceClientProtocol akzeptiert nur die AMQPS- oder AMQPS_WS-Enumeration.

IotHubServiceClientProtocol protocol = IotHubServiceClientProtocol.AMQPS;

Erstellen des ServiceClient-Objekts

Erstellen Sie das ServiceClient-Objekt, und stellen Sie die IoT Hub-Verbindungszeichenfolge und das Protokoll bereit.

String connectionString = "{yourhubconnectionstring}";
ServiceClient serviceClient (connectionString, protocol);

Öffnen der Verbindung zwischen Anwendung und IoT Hub

Verwenden Sie open, um die AMQP-Absenderverbindung zu öffnen. Mit dieser Methode wird die Verbindung zwischen der Anwendung und IoT Hub hergestellt.

serviceClient.open();

Verbinden mit Microsoft Entra

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

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

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.

Öffnen eines Feedbackempfängers für Feedback zur Nachrichtenübermittlung

Sie können FeedbackReceiver verwenden, um Feedback zur Übermittlung von Nachrichten an IoT Hub zu erhalten. FeedbackReceiver ist ein spezieller Empfänger, dessen Receive-Methode anstelle eines Message-Objekts ein FeedbackBatch-Objekt zurückgibt.

In diesem Beispiel wird das FeedbackReceiver-Objekt erstellt, und die open()-Anweisung wird aufgerufen, um auf Feedback zu warten.

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

Hinzufügen von Nachrichteneigenschaften

Optional können Sie setProperties verwenden, um Nachrichteneigenschaften hinzuzufügen. Diese Eigenschaften sind in der Nachricht enthalten, die an das Gerät gesendet wird, und können bei Erhalt von der Geräteanwendung extrahiert werden.

Map<String, String> propertiesToSend = new HashMap<String, String>();
propertiesToSend.put(messagePropertyKey,messagePropertyKey);
messageToSend.setProperties(propertiesToSend);

Erstellen und Senden einer asynchronen Nachricht

Das Message-Objekt speichert die zu sendende Nachricht. In diesem Beispiel wird eine Cloud-zu-Gerät-Nachricht übermittelt.

Verwenden Sie setDeliveryAcknowledgement, um eine Bestätigung anzufordern, dass die Nachricht an die IoT Hub-Nachrichtenwarteschlange übermittelt oder nicht übermittelt wurde. In diesem Beispiel wird die Bestätigung mit Full angefordert, sodass sowohl bestätigt wird, wenn die Nachricht übermittelt wurde als auch wenn sie nicht übermittelt wurde.

Verwenden Sie SendAsync, um eine asynchrone Nachricht vom Client an das Gerät zu senden. Alternativ können Sie die (nicht asynchrone) Send-Methode verwenden. Diese Funktion wird jedoch intern synchronisiert, was dazu führt, dass mehrere Sendevorgänge gleichzeitig nicht möglich sind. Die Nachricht wird von der Anwendung an IoT Hub übermittelt. IoT Hub reiht die Nachricht in die Nachrichtenwarteschlange ein, von wo aus sie an das Zielgerät übermittelt werden kann.

Message messageToSend = new Message("Cloud to device message.");
messageToSend.setDeliveryAcknowledgementFinal(DeliveryAcknowledgement.Full);
serviceClient.sendAsync(deviceId, messageToSend);

Empfangen von Feedback zur Nachrichtenübermittlung

Nachdem eine Nachricht von der Anwendung gesendet wurde, kann die Anwendung receive mit oder ohne Timeoutwert aufrufen. Wenn kein Timeoutwert angegeben wird, wird der Standardtimeoutzeitraum verwendet. Es wird ein FeedbackBatch-Objekt zurückgegeben, das Feedbackeigenschaften für die Nachrichtenübermittlung enthält, die untersucht werden können.

In diesem Beispiel werden der FeedbackBatch-Empfänger erstellt und die getEnqueuedTimeUtc-Methode aufgerufen, die den Zeitpunkt des Einreihens der Nachricht in die Warteschlange zurückgibt.

FeedbackBatch feedbackBatch = feedbackReceiver.receive(10000);
if (feedbackBatch != null) {
  System.out.println("Message feedback received, feedback time: "
    + feedbackBatch.getEnqueuedTimeUtc().toString());
}

SDK-Beispiele für gesendete Nachrichten

Es gibt zwei Beispiele für das Senden von Nachrichten:

Dienstclientbeispiel: Beispiel 1 für gesendete Nachrichten
Dienstclientbeispiel: Beispiel 2 für gesendete Nachrichten

Erstellen einer Geräteanwendung

In diesem Abschnitt wird beschrieben, wie Cloud-zu-Gerät-Nachrichten empfangen werden.

Die Klasse IoTHubDeviceClient umfasst Methoden zum Erstellen einer synchronen Verbindung zwischen einem Gerät und Azure IoT Hub und zum Empfangen von Nachrichten von IoT Hub.

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

pip install azure-iot-device

Damit eine Python-basierte Geräteanwendung Cloud-zu-Gerät-Nachrichten empfangen kann, muss eine Verbindung mit IoT Hub hergestellt und anschließend ein Rückrufnachrichtenhandler eingerichtet werden, um eingehende Nachrichten von IoT Hub zu verarbeiten.

Geräte-Importanweisung

Fügen Sie diesen Code hinzu, um die IoTHubDeviceClient-Funktionen aus dem azure.iot.device-SDK zu importieren.

from azure.iot.device import IoTHubDeviceClient

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

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

So verbinden Sie ein Gerät mit IoT Hub

Rufen Sie create_from_connection_string auf, um die primäre Verbindungszeichenfolge des Geräts hinzuzufügen.
Rufen Sie connect auf, um eine Verbindung mit dem Geräteclient herzustellen.

Zum Beispiel:

# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

# Connect the client
device_client.connect()

Authentifizierung mit einem X.509-Zertifikat

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

Verwenden von create_from_x509_certificate zum Hinzufügen der X.509-Zertifikatparameter
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.

Verhalten beim Wiederherstellen einer Verbindung

IoTHubDeviceClient versucht standardmäßig, eine getrennte Verbindung wiederherzustellen. Das Verhalten beim Wiederherstellen von Verbindungen wird über die IoTHubDeviceClient-Parameter connection_retry und connection_retry_interval gesteuert.

Erstellen eines Nachrichtenhandlers

Erstellen Sie eine Nachrichtenhandlerfunktion, um eingehende Nachrichten an das Gerät zu verarbeiten. Diese wird von on_message_received (nächster Schritt) als Rückrufnachrichtenhandler zugewiesen.

In diesem Beispiel wird message_handler aufgerufen, wenn eine Nachricht empfangen wird. Die Nachrichteneigenschaften (.items) werden mithilfe einer Schleife in der Konsole ausgegeben.

def message_handler(message):
    global RECEIVED_MESSAGES
    RECEIVED_MESSAGES += 1
    print("")
    print("Message received:")

    # print data from both system and application (custom) properties
    for property in vars(message).items():
        print ("    {}".format(property))

    print("Total calls received: {}".format(RECEIVED_MESSAGES))

Zuweisen des Nachrichtenhandlers

Verwenden Sie die on_message_received-Methode, um die Nachrichtenhandlermethode zuzuweisen.

In diesem Beispiel wird eine Nachrichtenhandlermethode mit dem Namen message_handler mit dem client-Objekt von IoTHubDeviceClient verknüpft. Das client-Objekt wartet auf den Empfang einer Cloud-zu-Gerät-Nachricht von IoT Hub. Bei diesem Code wird bis zu 300 Sekunden (5 Minuten) auf eine Nachricht gewartet oder das Warten beendet, wenn eine Taste auf der Tastatur gedrückt wird.

try:
    # Attach the handler to the client
    client.on_message_received = message_handler

    while True:
        time.sleep(300)
except KeyboardInterrupt:
    print("IoT Hub C2D Messaging device sample stopped")
finally:
    # Graceful exit
    print("Shutting down IoT Hub Client")
    client.shutdown()

SDK-Beispiel für empfangene Nachrichten

Empfangen von Nachrichten: Empfangen von Cloud-zu-Gerät-Nachrichten (Cloud-to-Device, C2D), die von Azure IoT Hub an ein Gerät gesendet werden.

Erstellen einer Back-End-Anwendung

In diesem Abschnitt wird beschrieben, wie eine Cloud-zu-Gerät-Nachricht gesendet wird. Es wird eine Verbindung zwischen einer Lösungs-Back-End-Anwendung und IoT Hub hergestellt, und es werden mit einem Zielgerät codierte Nachrichten an IoT Hub gesendet. IoT Hub speichert eingehende Nachrichten in der Nachrichtenwarteschlange, und Nachrichten werden von der IoT Hub-Nachrichtenwarteschlange an das Zielgerät übermittelt.

Die Klasse IoTHubRegistryManager macht alle Methoden verfügbar, die für die Erstellung einer Back-End-Anwendung zur Interaktion mit Cloud-zu-Gerät-Nachrichten des Diensts erforderlich sind. Die Azure-iot-hub-Bibliothek muss installiert werden, um Back-End-Dienstanwendungen zu erstellen.

pip install azure-iot-hub

Importieren des IoTHubRegistryManager-Objekts

Fügen Sie die folgende import -Anweisung hinzu. IoTHubRegistryManager umfasst APIs für IoT Hub Registry Manager-Vorgänge.

from azure.iot.hub import IoTHubRegistryManager

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

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

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

Zum Beispiel:

IoTHubConnectionString = "{IoT hub service connection string}"
registry_manager = IoTHubRegistryManager.from_connection_string(IoTHubConnectionString)

Verbinden mit Microsoft Entra

Konfigurieren der Microsoft Entra-App

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

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

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

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

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

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

TokenCredential tokenCredential = new DefaultAzureCredential();

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.

Erstellen und Senden einer Nachricht

Verwenden Sie send_c2d_message, um eine Nachricht über die Cloud (IoT Hub) an das Gerät zu senden.

send_c2d_message verwendet die folgenden Parameter:

deviceID: Zeichenfolgenbezeichner des Zielgeräts
message: Cloud-zu-Gerät-Nachricht. Die Nachricht ist vom Typ str (Zeichenfolge).
properties: Optionale Sammlung von Eigenschaften vom Typ dict. Eigenschaften können Anwendungseigenschaften und Systemeigenschaften enthalten. Der Standardwert ist {}.

In diesem Beispiel wird eine Testnachricht an das Zielgerät gesendet.

# define the device ID
deviceID = "Device-1"

# define the message
message = "{\"c2d test message\"}"

# include optional properties
props={}
props.update(messageId = "message1")
props.update(prop1 = "test property-1")
props.update(prop1 = "test property-2")
prop_text = "Test message"
props.update(testProperty = prop_text)

# send the message through the cloud (IoT Hub) to the device
registry_manager.send_c2d_message(deviceID, message, properties=props)

SDK-Beispiel für gesendete Nachrichten

Das Azure IoT SDK für Python bietet ein praktisches Beispiel für eine Dienst-App, die das Senden einer Cloud-zu-Gerät-Nachricht veranschaulicht. Weitere Informationen finden Sie unter send_message.py. Dort wird veranschaulicht, wie eine Cloud-zu-Gerät-Nachricht gesendet wird.

Erstellen einer Geräteanwendung

In diesem Abschnitt wird beschrieben, wie Sie Cloud-zu-Gerät-Nachrichten mithilfe des Pakets azure-iot-device im Azure IoT SDK für Node.js empfangen.

Damit eine Node.js-basierte Geräteanwendung Cloud-zu-Gerät-Nachrichten empfangen kann, müssen eine Verbindung mit IoT Hub hergestellt und anschließend ein Rückruflistener und ein Nachrichtenhandler eingerichtet werden, um eingehende Nachrichten von IoT Hub zu verarbeiten. Für den Fall, dass die Nachrichtenverbindung zwischen Gerät und IoT Hub unterbrochen wird, sollte die Geräteanwendung auch die Trennung von Verbindungen erkennen und verarbeiten können.

Installieren der SDK-Pakete

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

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

Rufen Sie fromConnectionString auf, um die Geräteverbindungszeichenfolge und den Transporttyp hinzuzufügen. Fügen Sie der Geräteverbindungszeichenfolge x509=true hinzu, um anzugeben, dass DeviceClientOptions ein Zertifikat hinzugefügt wird. Beispiel: HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
Konfigurieren Sie eine JSON-Variable mit Zertifikatdetails, und übergeben Sie sie an DeviceClientOptions.
Rufen Sie setOptions auf, um dem Clienttransport ein X.509-Zertifikat und einen Schlüssel (und optional eine Passphrase) hinzuzufügen.
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 options wird an setOptions übergeben und die Verbindung wird mit open geöffnet.

var options = {
   cert: myX509Certificate,
   key: myX509Key,
   passphrase: passphrase,
   http: {
     receivePolicy: {
       interval: 10
     }
   }
 }
 client.setOptions(options, callback);
 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.

In diesem Beispiel wird dem AMQP-Protokoll eine Protocol-Variable zugewiesen. Diese Protocol-Variable wird an die Client.fromConnectionString-Methode im Abschnitt Hinzufügen der Verbindungszeichenfolge dieses Artikels weitergegeben.

const Protocol = require('azure-iot-device-mqtt').Amqp;

Funktionen zum Abschließen, Ablehnen und Abbrechen von Nachrichten

Je nach ausgewähltem Protokoll können Methoden zum Abschließen, Ablehnen und Abbrechen von Nachrichten verwendet werden.

AMQP und HTTP

Bei AMQP- und HTTP-Transporten können Nachrichten abgeschlossen, abgelehnt oder abgebrochen werden:

Abschließen: Beim Abschließen einer Nachricht wird der Dienst, der die Cloud-zu-Gerät-Nachricht gesendet hat, darüber benachrichtigt, dass die Nachricht empfangen wurde. IoT Hub entfernt die Nachricht aus der Nachrichtenwarteschlange. Die Methode hat das Format client.complete(message, callback function).
Ablehnen: Beim Ablehnen einer Nachricht wird der Dienst, der die Cloud-zu-Gerät-Nachricht gesendet hat, darüber benachrichtigt, dass die Nachricht nicht vom Gerät verarbeitet wurde. IoT Hub entfernt die Nachricht dauerhaft aus der Gerätewarteschlange. Die Methode hat das Format client.reject(message, callback function).
Abbrechen: Beim Abbrechen einer Nachricht versucht IoT Hub sofort, die Nachricht erneut zu senden. IoT Hub behält die Nachricht für eine zukünftige Nutzung in der Gerätewarteschlange bei. Die Methode hat das Format client.abandon(message, callback function).

MQTT

MQTT unterstützt keine Funktionen zum Abschließen, Ablehnen oder Abbrechen von Nachrichten. Stattdessen akzeptiert MQTT Nachrichten standardmäßig, und die betreffende Nachricht wird aus der IoT Hub-Nachrichtenwarteschlange entfernt.

Versuchte erneute Übermittlungen

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

Erstellen eines Handlers für eingehende Nachrichten

Der Nachrichtenhandler wird für jede eingehende Nachricht aufgerufen.

Nachdem eine Nachricht erfolgreich empfangen wurde, wird bei Verwendung von AMQP- oder HTTP-Transport die client.complete-Methode aufgerufen, um IoT Hub darüber zu benachrichtigen, dass die Nachricht aus der Nachrichtenwarteschlange entfernt werden kann.

Dieser Nachrichtenhandler gibt beispielsweise die Nachrichten-ID und den Nachrichtentext in der Konsole zurück und ruft dann client.complete auf, um IoT Hub darüber zu benachrichtigen, dass er die Nachricht verarbeitet hat und diese sicher aus der Gerätewarteschlange entfernt werden kann. Der Aufruf von complete ist nicht erforderlich, wenn Sie MQTT-Transport verwenden. Er kann weggelassen werden. Beim AMQP- oder HTTPS-Transport ist ein Aufruf von complete erforderlich.

function messageHandler(msg) {
  console.log('Id: ' + msg.messageId + ' Body: ' + msg.data);
  client.complete(msg, printResultFor('completed'));
}

Erstellen eines Verbindungstrennungshandlers

Der Trennungshandler wird aufgerufen, wenn die Verbindung getrennt wurde. Ein Trennungshandler ist nützlich für die Implementierung von Code zum Wiederherstellen der Verbindung.

In diesem Beispiel wird die Fehlermeldung zur Verbindungstrennung abgerufen und in der Konsole angezeigt.

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

Hinzufügen von Ereignislistenern

Sie können folgende Ereignislistener mithilfe der .on-Methode angeben.

Verbindungshandler
Fehlerhandler
Trennungshandler
Nachrichtenhandler

Dieses Beispiel enthält die zuvor definierten Nachrichten- und Trennungshandler.

client.on('connect', connectHandler);
client.on('error', errorHandler);
client.on('disconnect', disconnectHandler);
client.on('message', messageHandler);

Öffnen der Verbindung mit IoT Hub

Verwenden Sie die open-Methode, um eine Verbindung zwischen einem IoT-Gerät und IoT Hub zu öffnen. Verwenden Sie .catch(err) um einen Fehler- und Aufrufhandlercode abzurufen.

Zum Beispiel:

client.open()
.catch((err) => {
  console.error('Could not connect: ' + err.message);
});

Beispiele für SDK-Geräte

Das Azure IoT SDK für Node.js bietet ein praktisches Beispiel für eine Geräte-App, die das Empfangen von Nachrichten verarbeitet. Weitere Informationen finden Sie unter:

simple_sample_device: Eine Geräte-App, die eine Verbindung mit Ihrem IoT-Hub herstellt und Cloud-zu-Gerät-Nachrichten empfängt

Erstellen einer Back-End-Anwendung

In diesem Abschnitt wird beschrieben, wie eine Cloud-zu-Gerät-Nachricht gesendet wird. Wie bereits erwähnt, wird eine Verbindung zwischen einer Lösungs-Back-End-Anwendung und IoT Hub hergestellt, und es werden mit einem Zielgerät codierte Nachrichten an IoT Hub gesendet. IoT Hub speichert eingehende Nachrichten in der Nachrichtenwarteschlange, und Nachrichten werden von der IoT Hub-Nachrichtenwarteschlange an das Zielgerät übermittelt.

Dienst-SDK-Paket installieren

Das Paket azure-iothub enthält Objekte, die über eine Schnittstelle mit IoT Hub verfügen. In diesem Artikel wird Client-Klassencode beschrieben, mit dem eine Nachricht von einer Anwendung über IoT Hub an ein Gerät gesendet wird.

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

npm install azure-iothub --save

Laden der Client- und Nachrichtenmodule

Deklarieren Sie ein Client-Objekt mithilfe der Klasse Client aus dem Paket azure-iothub.

Deklarieren Sie ein Message-Objekt mithilfe der Klasse Message aus dem Paket azure-iot-common.

'use strict';
var Client = require('azure-iothub').Client;
var Message = require('azure-iot-common').Message;

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

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

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

In diesem Beispiel wird das serviceClient-Objekt mit dem Transporttyp Amqp erstellt.

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

Öffnen der Clientverbindung

Rufen Sie die open-Methode für Client auf, um eine Verbindung zwischen einer Anwendung und IoT Hub zu öffnen.

open kann mit oder ohne Angabe einer Rückruffunktion aufgerufen werden, die aufgerufen wird, wenn der open-Vorgang abgeschlossen ist.

In diesem Beispiel enthält die open-Methode eine optionale err-Rückruffunktion für das Öffnen von Verbindungen. Wenn beim Öffnen ein Fehler auftritt, wird ein Fehlerobjekt zurückgegeben. Wenn die Verbindung erfolgreich geöffnet wird, wird der Rückrufwert null zurückgegeben.

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

Verbinden mit Microsoft Entra

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

Konfigurieren der Microsoft Entra-App

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

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

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.

Eine Nachricht erstellen

Das message-Objekt enthält die asynchrone Cloud-zu-Gerät-Nachricht. Die Funktionsweise der Nachrichtenfunktionalität ist bei AMQP, MQTT und HTTP identisch.

Das message-Objekt unterstützt verschiedene Eigenschaften, einschließlich der folgenden. Eine vollständige Liste finden Sie in den Eigenschaften unter message.

ack: Übermittlungsfeedback. Dies wird im nächsten Abschnitt beschrieben.
properties: Eine Zuordnung mit Zeichenfolgenschlüsseln und -werten zum Speichern benutzerdefinierter Nachrichteneigenschaften.
messageId: Wird verwendet, um dafür zu sorgen, dass bidirektionale Kommunikation korreliert

Fügen Sie den Nachrichtentext hinzu, wenn das message-Objekt instanziiert wird. In diesem Beispiel wird die Nachricht 'Cloud to device message.' hinzugefügt.

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

Übermittlungsbestätigung

Jede Nachricht, für die Nachrichtenfeedback empfangen werden soll, muss einen Wert für die Übermittlungsbestätigungseigenschaft ack enthalten. Die Eigenschaft ack kann einen der folgenden Werte aufweisen:

Keinen (Standard): Es wird keine Feedbacknachricht generiert.
sent: Sie erhalten eine Feedbacknachricht, wenn die Nachricht abgeschlossen wurde.
Sie erhalten eine Feedbacknachricht, wenn die Nachricht abgelaufen ist (oder die maximale Übermittlungsanzahl erreicht wurde), ohne dass sie vom Gerät abgeschlossen wurde.
full: Feedback für Ergebnisse sowohl für gesendete als auch für nicht gesendete Nachrichten

In diesem Beispiel wird die Eigenschaft ack auf full festgelegt, wodurch für eine Nachricht Feedback zur Nachrichtenübermittlung sowohl für gesendete als auch für nicht gesendete Nachrichten angefordert wird.

message.ack = 'full';

Verknüpfen des Nachrichtenfeedbackempfängers

Die Rückruffunktion des Nachrichtenfeedbackempfängers wird mithilfe von getFeedbackReceiver mit dem Client verknüpft.

Der Nachrichtenfeedbackempfänger empfängt zwei Argumente:

Error-Objekt (kann den Wert NULL aufweisen)
AmqpReceiver-Objekt: Gibt Ereignisse aus, wenn der Client neue Feedbacknachrichten empfängt.

Diese Beispielfunktion empfängt Übermittlungsfeedbacknachrichten und gibt sie in der Konsole aus.

function receiveFeedback(err, receiver){
  receiver.on('message', function (msg) {
    console.log('Feedback message:')
    console.log(msg.getData().toString('utf-8'));
  });
}

Mit diesem Code wird die Feedbackrückruffunktion receiveFeedback mithilfe von getFeedbackReceiver mit dem Client-Dienstobjekt verknüpft.

serviceClient.getFeedbackReceiver(receiveFeedback);

Definieren eines Ergebnishandlers für das Abschließen von Nachrichten

Die Rückruffunktion für den Abschluss des Sendens von Nachrichten wird nach dem Senden jeder Nachricht aufgerufen.

Mit dieser Beispielfunktion werden die Ergebnisse für den Nachrichtenvorgang send in der Konsole ausgegeben. In diesem Beispiel wird die printResultFor-Funktion als Parameter für die im nächsten Abschnitt beschriebene send-Funktion bereitgestellt.

function printResultFor(op) {
  return function printResult(err, res) {
    if (err) console.log(op + ' error: ' + err.toString());
    if (res) console.log(op + ' status: ' + res.constructor.name);
  };
}

Senden einer Nachricht

Verwenden Sie die send-Funktion, um eine asynchrone Cloud-zu-Gerät-Nachricht über IoT Hub an die Geräte-App zu senden.

send unterstützt folgende Parameter:

deviceID: Die Geräte-ID des Zielgeräts
message: Der Text der Nachricht, die an das Gerät gesendet werden soll
done: Die optionale Funktion, die aufgerufen werden soll, wenn der Vorgang abgeschlossen ist. „done“ wird mit zwei Argumenten aufgerufen:
- Error-Objekt (kann den Wert NULL aufweisen)
- Transportspezifisches Antwortobjekt, das hilfreich für die Protokollierung oder das Debuggen ist

Mit diesem Code wird send aufgerufen, um eine Cloud-zu-Gerät-Nachricht über IoT Hub an die Geräte-App zu senden. Die im vorherigen Abschnitt definierte Rückruffunktion printResultFor empfängt die Übermittlungsbestätigungsinformationen.

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

Im folgenden Beispiel wird gezeigt, wie Sie eine Nachricht an Ihr Gerät senden und die Feedbacknachricht verarbeiten, wenn das Gerät die Cloud-zu-Gerät-Nachricht bestätigt:

serviceClient.open(function (err) {
  if (err) {
    console.error('Could not connect: ' + err.message);
  } else {
    console.log('Service client connected');
    serviceClient.getFeedbackReceiver(receiveFeedback);
    var message = new Message('Cloud to device message.');
    message.ack = 'full';
    message.messageId = "My Message ID";
    console.log('Sending message: ' + message.getData());
    serviceClient.send(targetDevice, message, printResultFor('send'));
  }
});

SDK-Beispiel für gesendete Nachrichten

Das Azure IoT SDK für Node.js bietet praktische Beispiele für eine Dienst-App, die Aufgaben zum Senden von Nachrichten verarbeitet. Weitere Informationen finden Sie unter:

send_c2d_message.js: Senden von Cloud-zu-Gerät-Nachrichten an ein Gerät über IoT Hub

Richtlinie für die erneute Verbindungsherstellung

In diesem Artikel wird keine Wiederholungsrichtlinie für Nachrichten für die Verbindung zwischen Gerät und IoT Hub oder zwischen einer externen Anwendung und IoT Hub gezeigt. Im Produktionscode sollten Sie Wiederholungsrichtlinien für Verbindungen implementieren wie unter Verwalten von Geräteverbindungen zum Erstellen resilienter Anwendungen beschrieben.

Aufbewahrungszeitraum für Nachrichten, Wiederholungsversuche und maximale Übermittlungsanzahl

Wie unter Senden von C2D-Nachrichten von IoT Hub beschrieben, können Sie Standardwerte für die folgenden Nachrichtenwerte mithilfe von IoT Hub-Konfigurationsoptionen im Portal oder der Azure CLI anzeigen und konfigurieren. Folgende Konfigurationsoptionen können sich auf Nachrichtenübermittlung und -feedback auswirken.

Standardgültigkeitsdauer (TTL): Der Zeitraum, für den eine Nachricht dem Gerät zur Nutzung zur Verfügung steht, bevor sie von IoT Hub als abgelaufen gekennzeichnet wird
Aufbewahrungsdauer für Feedback: Der Zeitraum, für den IoT Hub das Feedback zum Ablauf oder zur Übermittlung von Cloud-zu-Gerät-Nachrichten aufbewahrt.
Die Anzahl der Übermittlungsversuche an ein Gerät durch IoT Hub für eine Cloud-zu-Gerät-Nachricht

Freigeben über

Senden und Empfangen von Cloud-zu-Gerät-Nachrichten

Übersicht

Grundlegendes zur Nachrichtenwarteschlange

Erstellen einer Geräteanwendung

Erforderliches NuGet-Gerätepaket

Verbinden eines Geräts mit IoT Hub

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

Bereitstellen der Verbindungsparameter

Authentifizierung mit einem X.509-Zertifikat

Codebeispiele

Rückruf

Abruf

CompleteAsync-Methode

Abbrechen, Ablehnen oder Timeout einer Nachricht

Abrufschleife

Wiederholungsrichtlinie für das Empfangen von Nachrichten

SDK-Beispiel für empfangene Nachrichten

Erstellen einer Back-End-Anwendung

Hinzufügen des NuGet-Dienstpakets

Herstellen einer Verbindung mit dem IoT-Hub

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

Bereitstellen der Verbindungszeichenfolge

Verbinden mit Microsoft Entra

Konfigurieren der Microsoft Entra-App

Authentifizieren mithilfe von DefaultAzureCredential

Codebeispiel

Senden einer asynchronen Cloud-zu-Gerät-Nachricht

Empfangen von Übermittlungsfeedback

Erstellen des feedbackReceiver-Objekts

Senden von Nachrichten mithilfe des Parameters Ack

Warten auf das Empfangen von Feedback

Erneutes Herstellen einer Verbindung mit dem Dienstclient

Wiederholungsrichtlinie für das Senden von Nachrichten

SDK-Beispiel für gesendete Nachrichten

Erstellen einer Geräteanwendung

Importieren von Azure IoT Java SDK-Bibliotheken

Verbinden eines Geräts mit IoT Hub

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

Authentifizierung mit einem X.509-Zertifikat

Codebeispiele

Festlegen der Nachrichtenrückrufmethode

Erstellen eines Rückrufnachrichtenhandlers

Abbruch- und Ablehnungsoptionen für Nachrichten

Erstellen der Rückrufmethode für den Nachrichtenstatus

Öffnen der Verbindung zwischen Gerät und IoT Hub

SDK-Beispiel für empfangene Nachrichten

Erstellen einer Back-End-Anwendung

Hinzufügen der Abhängigkeitsanweisung

Hinzufügen von Importanweisungen

Herstellen der Verbindung mit dem IoT Hub

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

Definieren des Verbindungsprotokolls

Erstellen des ServiceClient-Objekts

Öffnen der Verbindung zwischen Anwendung und IoT Hub

Verbinden mit Microsoft Entra

Konfigurieren der Microsoft Entra-App

Authentifizieren mithilfe von DefaultAzureCredential

Authentifizieren mit ClientSecretCredentialBuilder

Andere Authentifizierungsklassen

Codebeispiele

Öffnen eines Feedbackempfängers für Feedback zur Nachrichtenübermittlung

Hinzufügen von Nachrichteneigenschaften

Erstellen und Senden einer asynchronen Nachricht

Empfangen von Feedback zur Nachrichtenübermittlung

SDK-Beispiele für gesendete Nachrichten

Erstellen einer Geräteanwendung

Geräte-Importanweisung

Verbinden eines Geräts mit IoT Hub

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

Authentifizierung mit einem X.509-Zertifikat

Codebeispiele

Verhalten beim Wiederherstellen einer Verbindung

Erstellen eines Nachrichtenhandlers

Zuweisen des Nachrichtenhandlers

SDK-Beispiel für empfangene Nachrichten

Erstellen einer Back-End-Anwendung

Importieren des IoTHubRegistryManager-Objekts

Herstellen einer Verbindung mit dem IoT-Hub

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie