Senden von C2D-Nachrichten mit IoT Hub (.NET)

  • Artikel

Azure IoT Hub ist ein vollständig verwalteter Dienst, der eine zuverlässige und sichere bidirektionale Kommunikation zwischen Millionen von Geräten und einem Lösungs-Back-End ermöglicht.

In diesem Artikel lernen Sie Folgendes:

  • Senden von Cloud-zu-Gerät-Nachrichten (C2D) von Ihrem Lösungs-Back-End an ein einzelnes Gerät über IoT Hub

  • Empfangen von Cloud-zu-Gerät-Nachrichten auf einem Gerät

  • Anfordern einer Übermittlungsbestätigung (Feedback) bei Ihrem Lösungs-Back-End für Nachrichten, die von IoT Hub an ein Gerät gesendet wurden

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.

Am Ende dieses Artikels führen Sie zwei .NET-Konsolen-Apps aus:

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

  • SendCloudToDevice: Eine Dienst-App, die über IoT Hub eine Cloud-zu-Gerät-Nachricht an die Geräte-App sendet und die zugehörige Übermittlungsbestätigung empfängt.

Hinweis

IoT Hub bietet durch die Azure IoT-Geräte-SDKs Unterstützung für zahlreiche Geräteplattformen und Sprachen (C, Java, Python und JavaScript).

Weitere Informationen zu C2D-Nachrichten finden Sie unter D2C- und C2D-Messaging IoT Hub.

Voraussetzungen

  • Ein Azure-Abonnement. Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.

  • Ein IoT Hub in Ihrem Azure-Abonnement. Wenn Sie noch keinen Hub haben, können Sie die Schritte unter Erstellen eines IoT-Hubs ausführen.

  • Ein in Ihrem IoT-Hub registriertes Gerät. Wenn Sie noch kein Gerät registriert haben, registrieren Sie eins im Azure-Portal.

  • In diesem Tutorial wird Beispielcode aus dem Azure IoT-SDK für C# verwendet.

    • Sie können das SDK-Repository auf Ihren Entwicklungscomputer herunterladen oder klonen.
    • Stellen Sie sicher, dass .NET Core 3.0.0 oder höher auf Ihrem Entwicklungscomputer installiert ist. Überprüfen Sie Ihre Version, indem Sie dotnet --version ausführen und, falls erforderlich, .NET herunterladen.

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

  • Visual Studio.

Abrufen der Geräte-Verbindungszeichenfolge

In diesem Artikel führen Sie eine Beispiel-App aus, die ein Gerät simuliert, das Cloud-zu-Gerät-Nachrichten empfängt, die über Ihren IoT Hub gesendet werden. Die Beispiel-App MessageReceiveSample, die im Microsoft Azure IoT SDK für .NET enthalten ist, stellt eine Verbindung mit Ihrem IoT Hub her und fungiert als simuliertes Gerät. Im Beispiel wird die primäre Verbindungszeichenfolge des registrierten Geräts in Ihrem IoT Hub verwendet.

Führen Sie die folgenden Schritte aus, um die primäre Verbindungszeichenfolge für ein Gerät abzurufen, das bei Ihrem IoT Hub registriert ist:

  1. Wählen Sie im Azure-Portal die Option Ressourcengruppen aus. Wählen Sie die Ressourcengruppe aus, in der sich der Hub befindet, und wählen Sie dann in der Liste der Ressourcen Ihren Hub aus.

  2. Wählen Sie im linken Bereich Ihres IoT Hubs unter Geräteverwaltung die Option Geräte aus.

  3. Wählen Sie in der Liste das entsprechende Gerät aus.

  4. Kopieren Sie die primäre Verbindungszeichenfolge und speichern Sie den Wert.

    Screenshot, der zeigt, wie Sie den primären Verbindungsstring für ein bei Ihrem IoT Hub registriertes Gerät im Azure-Portal abrufen können.

Empfangen von Nachrichten in der Geräte-App

Führen Sie in diesem Abschnitt die Beispiel-Geräte-App MessageReceiveSample aus, um C2D-Nachrichten zu empfangen, die über Ihren IoT Hub gesendet werden. Öffnen Sie eine neue Eingabeaufforderung und navigieren Sie zum Ordner azure-iot-sdk-csharp\iothub\device\samples\getting started\MessageReceiveSample in dem Ordner, in dem Sie das Azure IoT C# SDK extrahiert haben. Führen Sie die folgenden Befehle aus und ersetzen Sie den Platzhalterwert {Your device connection string} durch die Geräteverbindungszeichenfolge, die Sie vom registrierten Gerät in Ihrem IoT Hub kopiert haben.

dotnet restore
dotnet run --c "{Your device connection string}"

Die folgende Ausgabe stammt aus der Beispiel-Geräte-App, nachdem sie erfolgreich gestartet wurde und eine Verbindung mit Ihrem IoT Hub hergestellt hat:

5/22/2023 11:13:18 AM> Press Control+C at any time to quit the sample.
     
5/22/2023 11:13:18 AM> Device waiting for C2D messages from the hub...
5/22/2023 11:13:18 AM> Use the Azure Portal IoT hub blade or Azure IoT Explorer to send a message to this device.
5/22/2023 11:13:18 AM> Trying to receive C2D messages by polling using the ReceiveAsync() method. Press 'n' to move to the next phase.

Die Beispiel-Geräte-App fragt Nachrichten mithilfe der Methoden ReceiveAsync und CompleteAsync ab. Die ReceiveC2dMessagesPollingAndCompleteAsync-Methode verwendet die ReceiveAsync-Methode, die die empfangene Nachricht asynchron zurückgibt, wenn das Gerät die Nachricht empfängt. ReceiveAsync gibt nach einem festgelegten Zeitlimit NULL zurück. In diesem Beispiel wird der Standardwert von einer Minute verwendet. Wenn das Gerät NULL empfängt, sollte es weiter auf neue Nachrichten warten. Diese Anforderung ist der Grund, warum die Beispiel-App den folgenden Codeblock in der ReceiveC2dMessagesPollingAndCompleteAsync-Methode enthält:

   if (receivedMessage == null)
   {
      continue;
   }

Durch den Aufruf der CompleteAsync-Methode wird IoT Hub darüber informiert, dass die Nachricht erfolgreich verarbeitet wurde und sicher aus der Gerätewarteschlange entfernt werden kann. Das Gerät sollte diese Methode unabhängig vom verwendeten Protokoll aufrufen, wenn seine Verarbeitung erfolgreich abgeschlossen wurde.

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

  • Eine Nachricht vorübergehend verwerfen, sodass IoT Hub sie für zukünftige Nutzung in der Gerätewarteschlange beibehält.
  • Eine Nachricht ablehnen, wodurch sie dauerhaft aus der Gerätewarteschlange entfernt wird.

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

Wird HTTPS anstelle von MQTT oder AMQP als Transport verwendet, erfolgt von der ReceiveAsync-Methode sofort eine Rückgabe. Das unterstützte Muster für Cloud-zu-Gerät-Nachrichten mit HTTPS ist zeitweilig mit Geräten verbunden, die selten Nachrichten abrufen (mindestens alle 25 Minuten). Die Ausgabe von mehr HTTPS-Empfangsvorgängen führt dazu, dass die Anforderungen von IoT Hub gedrosselt werden. 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.

Abrufen der IoT-Hub-Verbindungszeichenfolge

In diesem Artikel erstellen Sie einen Back-End-Dienst zum Senden von Cloud-zu-Gerät-Nachrichten über Ihren IoT Hub. Damit Ihr Dienst Cloud-zu-Gerät-Nachrichten senden kann, muss er über die Berechtigung Dienstverbindung verfügen. Standardmäßig wird jeder IoT-Hub mit einer SAS-Richtlinie namens service erstellt, die diese Berechtigung erteilt.

Führen Sie zum Abrufen der IoT-Hub-Verbindungszeichenfolge für die Richtlinie service die folgenden Schritte aus:

  1. Wählen Sie im Azure-Portal die Option Ressourcengruppen aus. Wählen Sie die Ressourcengruppe aus, in der sich der Hub befindet, und wählen Sie dann in der Liste der Ressourcen Ihren Hub aus.

  2. Wählen Sie im linken Bereich Ihres IoT-Hubs Freigegebene Zugriffsrichtlinien aus.

  3. Wählen Sie in der Liste der Richtlinien die Richtlinie service aus.

  4. Kopieren Sie die primäre Verbindungszeichenfolge und speichern Sie den Wert.

Screenshot, der das Abrufen der Verbindungszeichenfolge von Ihrem IoT Hub im Azure-Portal zeigt.

Weitere Informationen zu SAS-Richtlinien und Berechtigungen für IoT-Hubs finden Sie unter Access Control und Berechtigungen.

Senden einer C2D-Nachricht

In diesem Abschnitt erstellen Sie eine .NET-Konsolen-App, die Cloud-zu-Gerät-Nachrichten an die simulierte Geräte-App sendet. Sie benötigen die Geräte-ID Ihres Geräts und die Verbindungszeichenfolge Ihres IoT Hubs.

  1. Klicken Sie in Visual Studio auf Datei>Neu>Projekt. Wählen Sie in Neues Projekt erstellen die Option Konsolen-App (.NET Framework) und dann Weiter aus.

  2. Benennen Sie das Projekt SendCloudToDevice, und wählen Sie dann Weiter aus.

    Screenshot des Popups „Neues Projekt konfigurieren“ in Visual Studio.

  3. Akzeptieren Sie die neueste Version von .NET Framework. Wählen Sie Create (Erstellen), um das Projekt zu erstellen.

  4. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf die neue Projektmappe, und klicken Sie dann auf NuGet-Pakete verwalten.

  5. Wählen Sie in NuGet-Pakete verwalten die Option Durchsuchen, anschließend „Suchen nach“ und dann Microsoft.Azure.Devices aus. Wählen Sie Installieren aus.

    In diesem Schritt wird das NuGet-Paket mit dem Dienst-SDK für Azure IoT heruntergeladen, installiert und mit einem Verweis versehen.

  6. Fügen Sie am Anfang der Datei Program.cs die folgende using-Anweisung hinzu.

    using Microsoft.Azure.Devices;

  7. Fügen Sie der Program -Klasse die folgenden Felder hinzu. Ersetzen Sie den Platzhalterwert {iot hub connection string} durch die IoT-Hub-Verbindungszeichenfolge, die Sie zuvor unter Abrufen der IoT-Hub-Verbindungszeichenfolge notiert haben. Ersetzen Sie den Platzhalterwert {device id} durch die Geräte-ID des in Ihrem IoT Hub registrierten Geräts.

    static ServiceClient serviceClient;
static string connectionString = "{iot hub connection string}";
static string targetDevice = "{device id}";

  8. Fügen Sie der Program-Klasse die folgende Methode hinzu, um eine Nachricht an Ihr Gerät zu senden.

    private async static Task SendCloudToDeviceMessageAsync()
{
     var commandMessage = new
      Message(Encoding.ASCII.GetBytes("Cloud to device message."));
     await serviceClient.SendAsync(targetDevice, commandMessage);
}

  9. Fügen Sie abschließend der Main -Methode die folgenden Zeilen hinzu.

    Console.WriteLine("Send Cloud-to-Device message\n");
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

Console.WriteLine("Press any key to send a C2D message.");
Console.ReadLine();
SendCloudToDeviceMessageAsync().Wait();
Console.ReadLine();

  10. Drücken Sie F5, um Ihre Beispiel-Dienst-App zu starten. Wählen Sie das Fenster SendCloudToDevice aus, und drücken Sie die EINGABETASTE. Sie sollten die Nachricht sehen, die von der Beispiel-Geräte-App empfangen wird, wie im folgenden Ausgabebeispiel gezeigt.

    5/22/2023 11:13:18 AM> Press Control+C at any time to quit the sample.

5/22/2023 11:13:18 AM> Device waiting for C2D messages from the hub...
5/22/2023 11:13:18 AM> Use the Azure Portal IoT hub blade or Azure IoT Explorer to send a message to this device.
5/22/2023 11:13:18 AM> Trying to receive C2D messages by polling using the ReceiveAsync() method. Press 'n' to move to the next phase.
5/22/2023 11:15:18 AM> Polling using ReceiveAsync() - received message with Id=
5/22/2023 11:15:18 AM> Received message: [Cloud to device message.]
        Content type:

5/22/2023 11:15:18 AM> Completed C2D message with Id=.

Empfangen von Übermittlungsfeedback

Es ist möglich, für jede Cloud-zu-Gerät-Nachricht Übermittlungsbestätigungen (oder Ablaufbestätigungen) von IoT Hub anzufordern. Mit dieser Option kann die Wiederholungs- oder Kompensierungslogik vom Lösungs-Back-End problemlos informiert werden. Weitere Informationen zu C2D-Feedback finden Sie unter D2C- und C2D-Messaging mit IoT Hub.

In diesem Abschnitt ändern Sie die Beispiel-Dienst-App SendCloudToDevice so, dass sie Feedback vom IoT Hub anfordert und empfängt.

  1. Fügen Sie in Visual Studio im SendCloudToDevice-Projekt der Program-Klasse folgende Methode hinzu.

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

     Console.WriteLine("\nReceiving c2d feedback from service");
     while (true)
     {
         var feedbackBatch = await feedbackReceiver.ReceiveAsync();
         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 das Empfangsmuster mit dem Muster zum Empfangen von Cloud-zu-Gerät-Nachrichten von der Geräte-App identisch ist.

  2. Fügen Sie in der Methode Main die folgende Zeile direkt nach serviceClient = ServiceClient.CreateFromConnectionString(connectionString) hinzu.

    ReceiveFeedbackAsync();

  3. Um für die Übermittlung der C2D-Nachricht Feedback anzufordern, müssen Sie in der SendCloudToDeviceMessageAsync -Methode eine Eigenschaft angeben. Fügen Sie direkt nach der Zeile var commandMessage = new Message(...); die folgende Zeile hinzu.

    commandMessage.Ack = DeliveryAcknowledgement.Full;

  4. Stellen Sie sicher, dass die Beispiel-Geräte-App ausgeführt wird, und führen Sie dann die Beispiel-Dienst-App aus, indem Sie F5 drücken. Wählen Sie das Konsolenfenster SendCloudToDevice aus und drücken Sie die EINGABETASTE. Sie sollten die Nachricht sehen, die die Geräte-App empfangen hat, und einige Sekunden später die Feedbacknachricht, die die SendCloudToDevice-Anwendung empfangen hat. Die folgende Ausgabe zeigt die Feedbacknachricht, die von der Beispiel-Dienst-App empfangen wurde:

    Send Cloud-to-Device message


Receiving c2d feedback from service
Press any key to send a C2D message.

Received feedback: Success

Hinweis

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

Nächste Schritte

In diesem Artikel haben Sie gelernt, wie C2D-Nachrichten gesendet und empfangen werden.