Senden von C2D-Nachrichten mit IoT Hub (Java)
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 Java-Konsolen-Apps aus:
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.
SendCloudToDevice sendet eine Cloud-zu-Gerät-Nachricht über IoT Hub an die Geräte-App und empfängt die zugehörige Übermittlungsbestätigung.
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 Cloud-zu-Gerät-Nachrichten finden Sie unter Senden von Cloud-zu-Gerät-Nachrichten von einem 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 Java verwendet.
- Sie können das SDK-Repository von GitHub auf Ihren Entwicklungscomputer herunterladen oder klonen.
- Stellen Sie sicher, dass das Java SE Development Kit 8 auf Ihrem Entwicklungscomputer installiert ist. Wählen Sie unter Langfristiger Support unbedingt Java 8 aus, um zu den Downloads für JDK 8 zu gelangen.
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).
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 HandleMessages, die im Microsoft Azure IoT SDK für Java 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:
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.
Wählen Sie im linken Bereich Ihres IoT Hubs unter Geräteverwaltung die Option Geräte aus.
Wählen Sie in der Liste das entsprechende Gerät aus.
Kopieren Sie die primäre Verbindungszeichenfolge und speichern Sie den Wert.
Empfangen von Nachrichten in der Geräte-App
Führen Sie in diesem Abschnitt die Beispiel-Geräte-App HandleMessage 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-java\iothub\device\iot-device-samples\handle-messages unter dem Ordner, in dem Sie das Azure IoT Java SDK erweitert 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.
mvn clean package -DskipTests
java -jar ./target/handle-messages-1.0.0-with-deps.jar "{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.
Starting...
Beginning setup.
Successfully read input parameters.
Using communication protocol MQTT.
2023-05-23 09:51:06,062 INFO (main) [com.microsoft.azure.sdk.iot.device.transport.ExponentialBackoffWithJitter] - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
2023-05-23 09:51:06,187 DEBUG (main) [com.microsoft.azure.sdk.iot.device.ClientConfiguration] - Device configured to use software based SAS authentication provider
2023-05-23 09:51:06,187 INFO (main) [com.microsoft.azure.sdk.iot.device.transport.ExponentialBackoffWithJitter] - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
2023-05-23 09:51:06,202 DEBUG (main) [com.microsoft.azure.sdk.iot.device.DeviceClient] - Initialized a DeviceClient instance using SDK version 2.1.5
Successfully created an IoT Hub client.
Successfully set message callback.
2023-05-23 09:51:06,205 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.MqttIotHubConnection] - Opening MQTT connection...
2023-05-23 09:51:06,218 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sending MQTT CONNECT packet...
2023-05-23 09:51:07,308 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sent MQTT CONNECT packet was acknowledged
2023-05-23 09:51:07,308 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sending MQTT SUBSCRIBE packet for topic devices/US60536-device/messages/devicebound/#
2023-05-23 09:51:07,388 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sent MQTT SUBSCRIBE packet for topic devices/US60536-device/messages/devicebound/# was acknowledged
2023-05-23 09:51:07,388 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.MqttIotHubConnection] - MQTT connection opened successfully
2023-05-23 09:51:07,388 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - The connection to the IoT Hub has been established
2023-05-23 09:51:07,404 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Updating transport status to new status CONNECTED with reason CONNECTION_OK
2023-05-23 09:51:07,404 DEBUG (main) [com.microsoft.azure.sdk.iot.device.DeviceIO] - Starting worker threads
2023-05-23 09:51:07,408 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Invoking connection status callbacks with new status details
CONNECTION STATUS UPDATE: CONNECTED
CONNECTION STATUS REASON: CONNECTION_OK
CONNECTION STATUS THROWABLE: null
The connection was successfully established. Can send messages.
2023-05-23 09:51:07,408 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Client connection opened successfully
2023-05-23 09:51:07,408 INFO (main) [com.microsoft.azure.sdk.iot.device.DeviceClient] - Device client opened successfully
Opened connection to IoT Hub. Messages sent to this device will now be received.
Press any key to exit...
Die Methode execute in der Klasse AppMessageCallback gibt IotHubMessageResult.COMPLETE zurück. Dieser Status informiert IoT Hub, dass die Nachricht erfolgreich verarbeitet wurde und sicher aus der Gerätewarteschlange entfernt werden kann. Das Gerät sollte diesen Wert zurückgeben, wenn seine Verarbeitung – unabhängig vom verwendeten Protokoll – erfolgreich abgeschlossen wurde.
Mit AMQP und HTTPS, aber nicht MQTT, kann das Gerät auch folgende Aktionen ausführen:
- 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
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.
Abrufen der IoT-Hub-Verbindungszeichenfolge
In diesem Artikel erstellen Sie einen Back-End-Dienst, um Cloud-zu-Gerät-Nachrichten über Ihren IoT Hub zu senden. 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:
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.
Wählen Sie im linken Bereich Ihres IoT-Hubs Freigegebene Zugriffsrichtlinien aus.
Wählen Sie in der Liste der Richtlinien die Richtlinie service aus.
Kopieren Sie die primäre Verbindungszeichenfolge und speichern Sie den Wert.
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 Java-Konsolen-App, die C2D-Nachrichten an die simulierte Geräte-App sendet. Sie benötigen die Geräte-ID Ihres Geräts und die Verbindungszeichenfolge Ihres IoT Hubs.
Erstellen Sie mithilfe des folgenden Befehls über die Eingabeaufforderung ein Maven-Projekt namens send-c2d-messages. Beachten Sie, dass es sich hierbei um einen einzelnen langen Befehl handelt:
mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=send-c2d-messages -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=falseNavigieren Sie an der Eingabeaufforderung zu dem neuen Ordner „send-c2d-messages“.
Öffnen Sie die Datei „pom.xml“ aus dem Ordner „send-c2d-messages“ in einem Text-Editor, und fügen Sie dem Knoten dependencies die folgende Abhängigkeit hinzu. Durch Hinzufügen der Abhängigkeit können Sie in Ihrer Anwendung das Paket iothub-java-service-client verwenden, um mit Ihrem IoT Hub-Dienst zu kommunizieren:
<dependency> <groupId>com.microsoft.azure.sdk.iot</groupId> <artifactId>iot-service-client</artifactId> <version>1.7.23</version> </dependency>Hinweis
Sie finden die aktuelle Version von iot-service-client mithilfe der Maven-Suche.
Speichern und schließen Sie die Datei „pom.xml“.
Öffnen Sie die Datei „send-c2d-messages\src\main\java\com\mycompany\app\App.java“ in einem Text-Editor.
Fügen Sie der Datei die folgenden import -Anweisungen hinzu:
import com.microsoft.azure.sdk.iot.service.*; import java.io.IOException; import java.net.URISyntaxException;Fügen Sie der Klasse App die folgenden Klassenebenenvariablen hinzu, und ersetzen Sie dabei {yourhubconnectionstring} und {yourdeviceid} durch die zuvor notierten Werte:
private static final String connectionString = "{yourhubconnectionstring}"; private static final String deviceId = "{yourdeviceid}"; private static final IotHubServiceClientProtocol protocol = IotHubServiceClientProtocol.AMQPS;Ersetzen Sie die main-Methode durch den folgenden Code. Dieser Code stellt die Verbindung mit Ihrer IoT Hub-Instanz her, sendet eine Nachricht an Ihr Gerät und wartet dann auf eine Empfangs- und Verarbeitungsbestätigung des Geräts:
public static void main(String[] args) throws IOException, URISyntaxException, Exception { ServiceClient serviceClient = ServiceClient.createFromConnectionString( connectionString, protocol); if (serviceClient != null) { serviceClient.open(); FeedbackReceiver feedbackReceiver = serviceClient .getFeedbackReceiver(); if (feedbackReceiver != null) feedbackReceiver.open(); Message messageToSend = new Message("Cloud to device message."); messageToSend.setDeliveryAcknowledgement(DeliveryAcknowledgement.Full); serviceClient.send(deviceId, messageToSend); System.out.println("Message sent to device"); FeedbackBatch feedbackBatch = feedbackReceiver.receive(10000); if (feedbackBatch != null) { System.out.println("Message feedback received, feedback time: " + feedbackBatch.getEnqueuedTimeUtc().toString()); } if (feedbackReceiver != null) feedbackReceiver.close(); serviceClient.close(); } }Hinweis
Der Einfachheit halber wird in diesem Artikel keine Wiederholungsrichtlinie implementiert. Im Produktionscode sollten Sie Wiederholungsrichtlinien (z. B. exponentielles Backoff) implementieren, wie es im Artikel Behandeln vorübergehender Fehler vorgeschlagen wird.
Führen Sie zum Erstellen der App send-c2d-messages mit Maven den folgenden Befehl an der Eingabeaufforderung im Ordner „simulated-device“ aus:
mvn clean package -DskipTests
Ausführen der Anwendungen
Sie können nun die Anwendungen ausführen.
Führen Sie an einer Eingabeaufforderung im Ordner azure-iot-sdk-java\iothub\device\iot-device-samples\handle-messages die folgenden Befehle aus, und ersetzen Sie den
{Your device connection string}Platzhalterwert durch die Geräteverbindungszeichenfolge, die Sie vom registrierten Gerät in Ihrem IoT Hub kopiert haben. Mit diesem Schritt wird die Beispielgeräte-App gestartet, die Telemetriedaten an Ihren IoT Hub sendet und auf Cloud-zu-Gerät-Nachrichten lauscht:java -jar ./target/handle-messages-1.0.0-with-deps.jar "{Your device connection string}"
Führen Sie an einer Befehlszeile im Ordnersend-c2d-messages den folgenden Befehl aus, um eine C2D-Nachricht zu senden, und warten Sie auf eine Feedbackbestätigung:
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
Nächste Schritte
In diesem Artikel haben Sie gelernt, wie C2D-Nachrichten gesendet und empfangen werden.
Weitere Informationen zu Cloud-zu-Gerät-Nachrichten finden Sie unter Senden von Cloud-zu-Gerät-Nachrichten von einem IoT-Hub.
Weitere Informationen zu IoT Hub-Nachrichtenformaten finden Sie unter Erstellen und Lesen von IoT Hub-Nachrichten.