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

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.

Empfangen von Cloud-zu-Gerät-Nachrichten

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

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

• 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.
• Rückruf: Die Geräteanwendung richtet eine asynchrone Nachrichtenhandlermethode ein, die sofort aufgerufen wird, wenn eine Nachricht eingeht.

Deklarieren eines DeviceClient-Objekts

DeviceClient enthält Methoden und Eigenschaften, die zum Empfangen von Nachrichten von IoT Hub erforderlich sind.

Zum Beispiel:

static DeviceClient deviceClient;

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 CreateFromConnectionString aufgerufen, um die Einstellungen für IoT Hub und die Geräte-ID für die DeviceClient-Verbindung zu definieren.

static string connectionString = "{your IoT hub connection string}";
static string deviceID = "{your device ID}";
deviceClient = DeviceClient.CreateFromConnectionString(connectionString,deviceID);

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.

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.

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

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

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.

Senden von C2D-Nachrichten.

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.

Deklarieren eines ServiceClient-Objekts

ServiceClient enthält Methoden und Eigenschaften, die zum Senden von Nachrichten von einer Anwendung über IoT Hub an ein Gerät erforderlich sind.

static ServiceClient serviceClient;

Bereitstellen der Verbindungszeichenfolge

Stellen Sie die primäre IoT Hub-Verbindungszeichenfolge mithilfe der CreateFromConnectionString-Methode für ServiceClient 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 - 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 erstellt.

static string connectionString = "{your iot hub connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

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.

Empfangen von Cloud-zu-Gerät-Nachrichten

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

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;

Deklarieren eines DeviceClient-Objekts

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 = "{a device connection string}";
static protocol = IotHubClientProtocol.AMQPS;
DeviceClient client = new DeviceClient(connectionString, protocol);

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.

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.

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.

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.

Senden von C2D-Nachrichten.

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.

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

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.

private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;

Erstellen des ServiceClient-Objekts

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

private static final String connectionString = "{yourhubconnectionstring}";
private static final 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();

Ö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

• Dienstclientbeispiel: Beispiel 1 für gesendete Nachrichten

• Dienstclientbeispiel: Beispiel 2 für gesendete Nachrichten

Installieren der Azure IoT SDK-Bibliothek

Installieren Sie die azure-iot-device-SDK-Bibliothek auf Ihrem Entwicklungscomputer, bevor Sie zugehörigen Code aufrufen:

pip install azure-iot-device

Es gibt zwei Python-SDK-Klassen, die zum Senden von Nachrichten an und von IoT-Geräten verwendet werden. Nachrichtenverarbeitungsmethoden aus diesen Klassen werden in Abschnitten auf dieser Seite beschrieben.

• 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 Klasse IoTHubRegistryManager umfasst APIs für IoT Hub Registry Manager-Vorgänge. In diesem Artikel wird gezeigt, wie Sie mit Methoden aus dieser Klasse eine Verbindung mit IoT Hub herstellen und eine Nachricht an ein Gerät senden.

Empfangen von Cloud-zu-Gerät-Nachrichten

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

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.

Importieren des IoTHubDeviceClient-Objekts

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

from azure.iot.device import IoTHubDeviceClient

Herstellen einer Verbindung mit dem Geräteclient

Instanziieren Sie den IoTHubDeviceClient, und geben Sie eine IoT Hub-Verbindungszeichenfolge an create_from_connection_string weiter. Hierdurch wird eine Verbindung zwischen dem Gerät und IoT Hub hergestellt.

Alternativ können Sie mithilfe einer der folgenden Methoden eine Verbindung zwischen IoTHubDeviceClient und einem Gerät herstellen:

• SAS-Tokenzeichenfolge
• Authentifizierung mit symmetrischem Schlüssel
• Authentifizierung mit X.509-Zertifikat

deviceConnectionString = "{your IoT hub connection string}";
client = IoTHubDeviceClient.create_from_connection_string ({deviceConnectionString})

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 die Nachrichtenhandlerfunktion, um eingehende Nachrichten an das Gerät zu verarbeiten.

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 dem IoTHubDeviceClient-Objekt 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.

Senden von C2D-Nachrichten.

In diesem Abschnitt wird beschrieben, wie Sie Cloud-zu-Gerät-Nachrichten mithilfe der Klasse IoTHubRegistryManager aus dem Azure IoT SDK für Python 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.

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 IoT Hub Registry Manager

Instanziieren Sie das IoTHubRegistryManager-Objekt, das eine Verbindung mit IoT Hub herstellt, und geben Sie eine IoT Hub-Verbindungszeichenfolge an from_connection_string weiter.

IoTHubConnectionString = "{Primary connection string to an IoT hub}"
registry_manager = IoTHubRegistryManager.from_connection_string(IoTHubConnectionString)

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

send_message.py: Veranschaulicht, wie eine Cloud-zu-Gerät-Nachricht gesendet wird

Installieren der Node.js-Messagingpakete

Führen Sie die folgenden Befehle aus, um die Pakete azure-iot-device und das azure-iothub auf Ihrem Entwicklungscomputer zu installieren:

npm install azure-iot-device --save
npm install azure-iothub --save

Das Paket azure-iot-device enthält Objekte, die über eine Schnittstelle mit IoT-Geräten verfügen. In diesem Artikel wird Client-Klassencode beschrieben, mit dem Nachrichten von IoT Hub empfangen werden.

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.

Empfangen von Nachrichten in der 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.

Erstellen eines Clientmoduls

Erstellen Sie über das Paket azure-iot-device mithilfe der Klasse Client einen Client. Die Klasse Client umfasst Methoden, mit denen ein Gerät Nachrichten von IoT Hub empfangen und an IoT Hub senden kann.

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

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

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

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.

Hinzufügen der IoT Hub-Zeichenfolge und des Transportprotokolls

Rufen Sie fromConnectionString mit den folgenden Parametern auf, um eine Verbindung zwischen dem Gerät und IoT Hub herzustellen:

• connStr: Eine Verbindungszeichenfolge, die „device connect“-Berechtigungen für einen IoT-Hub kapselt. Die Verbindungszeichenfolge enthält den Hostnamen, die Geräte-ID und den Schlüssel für den gemeinsamen Zugriff im folgenden Format: „HostName=<iothub_host_name>;DeviceId=<device_id>;SharedAccessKey=<device_key>“.
• transportCtor: Das Transportprotokoll

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

SDK-Beispiel für empfangene Nachrichten

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

Senden von C2D-Nachrichten.

In diesem Abschnitt wird beschrieben, wie Sie Cloud-zu-Gerät-Nachrichten mithilfe des Pakets azure-iothub aus dem Azure IoT SDK für Node.js senden. 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.

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;

Erstellen des Client-Objekts

Erstellen Sie den Client mithilfe von fromConnectionString mit den folgenden Parametern:

• IoT Hub-Verbindungszeichenfolge
• Transportart

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

var connectionString = '{IoT Hub 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);

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

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.

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

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