Kommunizieren mit einem IoT-Hub mithilfe des MQTT-Protokolls

In diesem Artikel wird beschrieben, wie Geräte das MQTT-Protokoll für die Kommunikation mit Azure IoT Hub verwenden können. Die IoT Hub-Geräteendpunkte unterstützen die Gerätekonnektivität mithilfe von:

• MQTT v3.1.1 an Port 8883
• MQTT v3.1.1 über WebSocket auf Port 443

Hinweis

Einige der in diesem Artikel erwähnten Features (wie Cloud-zu-Gerät-Messaging, Gerätezwillinge und Geräteverwaltung) stehen nur im Standard-Tarif von IoT Hub zur Verfügung. Weitere Informationen zu den grundlegenden und standardmäßigen/kostenlosen IoT Hub-Ebenen finden Sie unter Auswählen der richtigen IoT Hub-Ebene und -Größe für Ihre Lösung.

Alle Gerätekommunikation mit IoT Hub muss mithilfe von TLS gesichert werden. Daher unterstützt IoT Hub keine unsicheren MQTT-Verbindungen über Port 1883.

Vergleichen der MQTT-Unterstützung in IoT Hub und Event Grid

IoT Hub ist kein MQTT-Broker mit vollem Funktionsumfang und unterstützt nicht alle im MQTT v3.1.1-Standard angegebenen Verhaltensweisen. Wenn Ihre Lösung einen in der Cloud gehosteten MQTT-Broker benötigt, verwenden Sie stattdessen Azure Event Grid . Event Grid ermöglicht die bidirektionale Kommunikation zwischen MQTT-Clients in flexiblen hierarchischen Themen mithilfe eines Publish-Subscribe-Messaging-Modells. Außerdem können Sie MQTT-Nachrichten zur weiteren Verarbeitung an andere Azure-Dienste oder benutzerdefinierte Endpunkte weiterleiten.

In der folgenden Tabelle sind die Unterschiede bei der MQTT-Unterstützung zwischen den beiden Diensten zusammengefasst:

IoT Hub	Event Grid
Client/Servermodell mit enger Kopplung zwischen Geräten und Cloud-Apps.	Publish/Subscribe-Modell, das Herausgeber und Abonnenten entkoppelt.
Eingeschränkte Featureunterstützung für MQTT v3.1.1. Eine weitere Featureunterstützung ist nicht geplant.	MQTT v3.1.1- und v5-Protokollunterstützung mit mehr Featureunterstützung und branchenspezifischer Compliance geplant.
Statische, vordefinierte Themen.	Benutzerdefinierte hierarchische Themen mit Platzhalterunterstützung.
Keine Unterstützung für Cloud-zu-Gerät-Übertragungen oder Geräte-zu-Gerät-Kommunikation.	Unterstützt Gerät-zu-Cloud-Kommunikation, breitgestreute Cloud-zu-Gerät-Übertragungen und Gerät-zu-Gerät-Kommunikationsmuster.
Maximale Nachrichtengröße von 256 KB.	Maximale Nachrichtengröße von 512 KB.

Herstellen einer Verbindung mit IoT Hub

Ein Gerät kann das MQTT-Protokoll zum Herstellen einer Verbindung mit einem IoT-Hub über die folgenden Optionen verwenden:

• Die Azure IoT-Geräte-SDKs.
• Das MQTT-Protokoll direkt

Viele Unternehmens- und Bildungsfirewalls blockieren den MQTT-Port (TCP-Port 8883). Wenn Sie port 8883 in Ihrer Firewall nicht öffnen können, verwenden Sie MQTT über WebSockets. MQTT over WebSockets kommuniziert über Port 443, was fast immer offen ist. Informationen zum Angeben der Protokolle für MQTT und MQTT über WebSockets bei Verwendung der Azure IoT-SDKs finden Sie unter Verwenden der Geräte-SDKs.

Verwenden der Geräte-SDKs

Azure IoT-Geräte-SDKs , die das MQTT-Protokoll unterstützen, sind für Java, Node.js, C, C# und Python verfügbar. Die Geräte-SDKs verwenden den ausgewählten Authentifizierungsmechanismus zum Herstellen einer Verbindung mit einem IoT-Hub. Um das MQTT-Protokoll verwenden zu können, muss der Clientprotokollparameter auf MQTTfestgelegt werden. Sie können MQTT über WebSockets auch im Parameter für das Clientprotokoll angeben. Standardmäßig verbinden sich die SDKs von Geräten mit einem IoT Hub, indem das CleanSession-Flag auf 0 festgelegt und QoS 1 für den Nachrichtenaustausch mit dem IoT Hub verwendet wird. Obwohl es möglich ist, QoS 0 für einen schnelleren Nachrichtenaustausch zu konfigurieren, sollten Sie beachten, dass die Zustellung nicht garantiert ist und nicht bestätigt wird. Aus diesem Grund wird QoS 0 oft als „Fire and Forget“ bezeichnet.

Wenn ein Gerät eine Verbindung mit einem IoT-Hub herstellt, stellen die Geräte-SDKs Methoden bereit, mit denen das Gerät Nachrichten mit einem IoT-Hub austauschen kann.

Die folgende Tabelle enthält Links zu Codebeispielen für jede unterstützte Sprache sowie die Parameter zum Herstellen einer Verbindung mit IoT Hub mithilfe der Protokolle für MQTT oder MQTT über WebSockets.

Sprache	Parameter für das MQTT-Protokoll	Parameter des Protokolls für MQTT über WebSockets
Node.js	azure-iot-device-mqtt.Mqtt	azure-iot-device-mqtt.MqttWs
Java	IotHubClientProtocol.MQTT	IotHubClientProtocol.MQTT_WS
C	MQTT_Protocol	MQTT_WebSocket_Protocol
C#	TransportType.Mqtt	Wenn bei MQTT ein Fehler auftritt, greift „TransportType.Mqtt“ auf MQTT über WebSockets zurück. Wenn Sie nur MQTT über WebSockets angeben möchten, verwenden Sie „TransportType.Mqtt_WebSocket_Only“.
Python	Verwendet MQTT standardmäßig	Fügen Sie websockets=True im Befehl hinzu, um den Client zu erstellen.

Das folgende Fragment zeigt, wie Sie das MQTT over WebSockets-Protokoll angeben, wenn Sie das Azure IoT Node.js SDK verwenden:

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-mqtt').MqttWs;
var client = Client.fromConnectionString(deviceConnectionString, Protocol);

Das folgende Fragment zeigt, wie Sie das MQTT over WebSockets-Protokoll angeben, wenn Sie das Azure IoT Python SDK verwenden:

from azure.iot.device.aio import IoTHubDeviceClient
device_client = IoTHubDeviceClient.create_from_connection_string(deviceConnectionString, websockets=True)

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 Sicherheit von IoT-Lösungen > für die Verbindungssicherheit".

Keep-Alive-Standardtimeout

Um sicherzustellen, dass eine Clientverbindung mit einer IoT-Hubverbindung aktiv bleibt, senden sowohl der Dienst als auch der Client regelmäßig einen Keep-Alive-Ping aneinander. Wenn Sie eines der Geräte-SDKs verwenden, sendet der Client eine Keep-Alive-Nachricht im in der folgenden Tabelle definierten Intervall:

Sprache	Keep-Alive-Standardintervall	Konfigurierbar
Node.js	180 Sekunden	Nein
Java	230 Sekunden	Nein
C	240 Sekunden	Ja
C#	300 Sekunden*	Ja
Python	60 Sekunden	Ja

*Das C#-SDK definiert den Standardwert der MQTT-Eigenschaft „KeepAliveInSeconds“ als „300 Sekunden“. Tatsächlich sendet das SDK viermal pro festgelegter Keep-Alive-Dauer eine Pinganforderung. Anders ausgedrückt: Das SDK sendet alle 75 Sekunden einen Keep-Alive-Ping.

Nach der MQTT v3.1.1-Spezifikation beträgt das Keep-Alive-Ping-Intervall von IoT Hub 1,5 Mal den Wert des Client-Keep-Alive; IoT Hub beschränkt jedoch das maximale serverseitige Timeout auf 29,45 Minuten (1.767 Sekunden).

So sendet beispielsweise ein Gerät, das das Java SDK verwendet, den Keep-Alive-Ping und verliert dann die Netzwerkkonnektivität. 230 Sekunden später verpasst das Gerät den Keep-Alive-Ping, weil es offline ist. Allerdings schließt IoT Hub die Verbindung nicht sofort, sondern wartet weitere (230 * 1.5) - 230 = 115 Sekunden, bevor es die Geräteverbindung mit der Fehlermeldung 404104 DeviceConnectionClosedRemotely trennt.

Als maximalen Keep-Alive-Wert für Clients können Sie 1767 / 1.5 = 1177 Sekunden festlegen. Keep-Alive wird durch jeglichen Datenverkehr zurückgesetzt. Beispielsweise wird Keep-Alive durch eine erfolgreiche SAS-Tokenaktualisierung (Shared Access Signature) zurückgesetzt.

Migrieren einer Geräteanwendung von AMQP zu MQTT

Wenn Sie die Geräte-SDKs verwenden, müssen Sie den Protokollparameter in der Clientinitialisierung ändern, um von der Verwendung von AMQP zu MQTT zu wechseln.

Wenn Sie von AMQP zu MQTT wechseln, überprüfen Sie die folgenden Elemente:

• Bei AMQP werden Fehler für viele Bedingungen zurückgegeben, bei MQTT wird dagegen die Verbindung beendet. Daher müssen Sie möglicherweise die Logik für die Ausnahmebehandlung ändern.

• MQTT unterstützt den Ablehnungsvorgang nicht, wenn er Cloud-zu-Gerät-Nachrichten empfängt. Wenn Ihre Back-End-Anwendung eine Antwort von der Geräteanwendung erhalten muss, sollten Sie direkte Methoden verwenden.

• AMQP wird im Python SDK nicht unterstützt.

Verwenden des MQTT-Protokolls direkt von einem Gerät

Wenn ein Gerät die IoT-Geräte-SDKs nicht verwenden kann, kann es weiterhin über das MQTT-Protokoll auf Port 8883 eine Verbindung mit den öffentlichen Geräteendpunkten herstellen.

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 Sicherheit von IoT-Lösungen > für die Verbindungssicherheit".

Das Gerät sollte im CONNECT-Paket die folgenden Werte verwenden:

• Verwenden Sie für das Feld ClientId die deviceId-Eigenschaft.

• Verwenden Sie für das Feld {iotHub-hostname}/{device-id}/?api-version=2021-04-12, wobei {iotHub-hostname} der vollständige CName für den IoT Hub ist.

  Wenn beispielsweise der Name Ihres IoT-Hubs contoso.azure-devices.net ist und der Name Ihres Geräts "MyDevice01" lautet, enthält das Feld "Benutzername " Folgendes:

  contoso.azure-devices.net/MyDevice01/?api-version=2021-04-12

  Um unerwartetes Verhalten zu vermeiden, schließen Sie die API-Version in das Feld ein.

• Verwenden Sie im Feld Kennwort ein SAS-Token. Der folgende Codeausschnitt zeigt das Format des SAS-Tokens:

  SharedAccessSignature sig={signature-string}&se={expiry}&sr={URL-encoded-resourceURI}

  Hinweis

  Wenn Sie die X.509-Zertifikatauthentifizierung verwenden, sind SAS-Token-Kennwörter nicht erforderlich. Weitere Informationen finden Sie im Lernprogramm: Erstellen und Hochladen von Zertifikaten zum Testen und Befolgen von Codeanweisungen im Abschnitt zur TLS-Konfiguration.

  Weitere Informationen zum Generieren von SAS-Token finden Sie unter Steuern des Zugriffs auf IoT Hub mithilfe von Shared Access Signatures im Abschnitt Verwenden von SAS-Token als Gerät.

  Sie können auch die Azure IoT Hub-Erweiterung für Visual Studio Code oder den CLI-Erweiterungsbefehl az iot hub generate-sas-token verwenden, um ein SAS-Token zu generieren. Anschließend können Sie das SAS-Token zu Testzwecken kopieren und in Ihren eigenen Code einfügen.

  Die Erweiterung generiert ein SAS-Token mit der folgenden Struktur:

  HostName={iotHub-hostname};DeviceId=javadevice;SharedAccessSignature=SharedAccessSignature sr={iotHub-hostname}%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

  Der folgende Teil des Tokens wird im Feld Kennwort verwendet, um über MQTT eine Verbindung herzustellen:

  SharedAccessSignature sr={iotHub-hostname}%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

Die Geräteanwendung kann eine Will-Nachricht im CONNECT-Paket angeben. Die Geräteanwendung sollte devices/{device-id}/messages/events/ oder devices/{device-id}/messages/events/{property-bag} als Will-Themennamen verwenden, um Will-Nachrichten zu definieren, die als Telemetrienachricht weitergeleitet werden sollen. Wenn die Netzwerkverbindung geschlossen ist, aber vorher kein DISCONNECT-Paket vom Gerät empfangen wurde, sendet IoT Hub in diesem Fall die im CONNECT-Paket bereitgestellte Will-Nachricht an den Telemetriekanal. Der Telemetriekanal kann entweder der Standardendpunkt Ereignisse oder ein benutzerdefinierter Endpunkt sein, der per IoT Hub-Routing definiert wird. Die Nachricht verfügt über die iothub-MessageType-Eigenschaft, der der Wert Will zugewiesen ist.

Verwenden des MQTT-Protokolls direkt aus einem Modul

Sie können auch über MQTT eine Verbindung mit IoT Hub herstellen, indem Sie eine Modulidentität verwenden. Dieser Ansatz ähnelt der Verbindung als Gerät, Sie müssen jedoch die folgenden Werte verwenden:

• Legen Sie für die Client-ID {device-id}/{module-id} fest.

• Wenn Die Authentifizierung mit Benutzername und Kennwort erfolgt, legen Sie den Benutzernamen auf <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2021-04-12. Wenn Sie SAS verwenden, verwenden Sie das SAS-Token, das der Modulidentität zugeordnet ist, als Kennwort.

• Verwenden Sie devices/{device-id}/modules/{module-id}/messages/events/ als ein Thema für die Veröffentlichung von Telemetriedaten.

• Verwenden Sie devices/{device-id}/modules/{module-id}/messages/events/ als Will-Thema.

• Verwenden Sie devices/{device-id}/modules/{module-id}/# als ein Thema zum Empfangen von Nachrichten.

• Die Themen zu GET und PATCH für Zwillinge sind bei Modulen und Geräten identisch.

• Das Thema "Zwillingsstatus" ist für Module und Geräte identisch.

Weitere Informationen zur Verwendung von MQTT mit Modulen finden Sie unter IoT Edge Hub MQTT-Endpunkt.

Beispiele zur Verwendung von MQTT ohne ein Azure IoT-Geräte-SDK

Das IoT MQTT-Beispielrepository enthält C/C++-, Python- und CLI-Beispiele, die zeigen, wie Sie Telemetrienachrichten senden, Cloud-zu-Gerät-Nachrichten empfangen und mit Gerätezwillingen arbeiten, ohne die Azure-Geräte-SDKs zu verwenden.

Für die C/C++-Beispielen wird die Eclipse Mosquitto-Bibliothek verwendet, für das Python-Beispiel wird Eclipse Paho verwendet und für die CLI-Beispiele wird mosquitto_pub verwendet.

Weitere Informationen finden Sie im Lernprogramm – Verwenden von MQTT zum Entwickeln eines IoT-Geräteclients, ohne ein Geräte-SDK zu verwenden.

TLS-Konfiguration

Um das MQTT-Protokoll direkt zu verwenden, muss Ihr Client eine Verbindung über TLS 1.2 herstellen. Alle Versuche, diesen Schritt zu überspringen, schlagen mit Verbindungsfehlern fehl.

Um eine TLS-Verbindung herzustellen, müssen Sie möglicherweise das von Azure verwendete DigiCert Global Root G2-Stammzertifikat herunterladen und referenzieren. Weitere Informationen zu diesem Zertifikat finden Sie auf Website von Digicert.

Im folgenden Beispiel wird veranschaulicht, wie diese Konfiguration mithilfe der Python-Version der Paho MQTT-Bibliothek implementiert wird.

Installieren Sie zunächst die Paho-Bibliothek aus Ihrer Befehlszeilenumgebung:

pip install paho-mqtt

Implementieren Sie anschließend den Client in einem Python-Skript. Ersetzen Sie diese Platzhalter im folgenden Codeausschnitt:

• <local path to digicert.cer> ist der Pfad zu einer lokalen Datei, die das DigiCert-Stammzertifikat enthält. Sie können diese Datei erstellen, indem Sie die Zertifikatinformationen aus certs.c in das Azure IoT SDK für C kopieren. Fügen Sie die Zeilen -----BEGIN CERTIFICATE----- und -----END CERTIFICATE----- ein, entfernen Sie die "-Markierungen am Anfang und Ende jeder Zeile, und entfernen Sie die Zeichen \r\n am Ende jeder Zeile.

• <device id from device registry> ist die ID eines Geräts, das Sie Ihrem IoT Hub hinzugefügt haben.

• <generated SAS token> ist ein SAS-Token für das Gerät, das wie zuvor in diesem Artikel beschrieben erstellt wurde.

• <iot hub name> ist der Name Ihres IoT Hubs.

from paho.mqtt import client as mqtt
import ssl

path_to_root_cert = "<local path to digicert.cer file>"
device_id = "<device id from device registry>"
sas_token = "<generated SAS token>"
iot_hub_name = "<iot hub name>"


def on_connect(client, userdata, flags, rc):
    print("Device connected with result code: " + str(rc))


def on_disconnect(client, userdata, rc):
    print("Device disconnected with result code: " + str(rc))


def on_publish(client, userdata, mid):
    print("Device sent message")


client = mqtt.Client(client_id=device_id, protocol=mqtt.MQTTv311)

client.on_connect = on_connect
client.on_disconnect = on_disconnect
client.on_publish = on_publish

client.username_pw_set(username=iot_hub_name+".azure-devices.net/" +
                       device_id + "/?api-version=2021-04-12", password=sas_token)

client.tls_set(ca_certs=path_to_root_cert, certfile=None, keyfile=None,
               cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLSv1_2, ciphers=None)
client.tls_insecure_set(False)

client.connect(iot_hub_name+".azure-devices.net", port=8883)

client.publish("devices/" + device_id + "/messages/events/", '{"id":123}', qos=1)
client.loop_forever()

Zum Authentifizieren mithilfe eines Gerätezertifikats aktualisieren Sie den vorherigen Codeausschnitt mit den im folgenden Codeausschnitt angegebenen Änderungen. Wenn Sie sich auf die zertifikatbasierte Authentifizierung vorbereiten möchten, finden Sie im Abschnitt X.509-CA-Zertifikat erhalten von Authentifizieren von Identitäten mit X.509-Zertifikaten weitere Informationen.

# Create the client as before
# ...

# Set the username but not the password on your client
client.username_pw_set(username=iot_hub_name+".azure-devices.net/" +
                       device_id + "/?api-version=2021-04-12", password=None)

# Set the certificate and key paths on your client
cert_file = "<local path to your certificate file>"
key_file = "<local path to your device key file>"
client.tls_set(ca_certs=path_to_root_cert, certfile=cert_file, keyfile=key_file,
               cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLSv1_2, ciphers=None)

# Connect as before
client.connect(iot_hub_name+".azure-devices.net", port=8883)

Senden von Gerät-zu-Cloud (D2C)-Nachrichten

Nachdem ein Gerät eine Verbindung hergestellt hat, kann es mit devices/{device-id}/messages/events/ oder devices/{device-id}/messages/events/{property-bag} als Themenbezeichnung Nachrichten an den IoT Hub senden. Das Element {property-bag} ermöglicht dem Gerät das Senden von Nachrichten mit weiteren Eigenschaften in einem URL-codierten Format. Beispiel:

RFC 2396-encoded(<PropertyName1>)=RFC 2396-encoded(<PropertyValue1>)&RFC 2396-encoded(<PropertyName2>)=RFC 2396-encoded(<PropertyValue2>)…

Dieses {property_bag}-Element verwendet die gleiche Codierung wie Abfragezeichenfolgen im HTTPS-Protokoll.

Wenn Sie D2C-Nachrichten an ein Azure Storage-Konto weiterleiten und JSON-Codierung verwenden möchten, müssen Sie die Inhaltstyp- und Inhaltscodierungsinformationen angeben, einschließlich $.ct=application%2Fjson&$.ce=utf-8, im Rahmen der {property_bag} oben erwähnten Notiz.

Hinweis

Das Format dieser Attribute ist protokollspezifisch. IoT Hub übersetzt diese Attribute in deren entsprechende Systemeigenschaften. Weitere Informationen finden Sie unter Abfragesyntax für das IoT Hub-Nachrichtenrouting im Abschnitt Systemeigenschaften.

Die folgende Liste fasst ioT Hub MQTT implementierungsspezifische Verhaltensweisen zusammen:

• IoT Hub unterstützt keine QoS 2-Nachrichten. Wenn eine Geräteanwendung eine Nachricht mit QoS 2 veröffentlicht, schließt IoT Hub die Netzwerkverbindung.

• IoT Hub speichert Retain-Nachrichten nicht dauerhaft. Wenn ein Gerät eine Nachricht mit auf 1 festgelegtem RETAIN-Flag sendet, fügt IoT Hub der Nachricht die Anwendungseigenschaft mqtt-retain hinzu. In diesem Fall übergibt IoT Hub diese an die Back-End-Anwendung, anstatt die beibehaltene Nachricht beizubehalten.

• IoT Hub unterstützt nur eine aktive MQTT-Verbindung pro Gerät. Jede neue MQTT-Verbindung im Namen derselben Geräte-ID bewirkt, dass IoT Hub die vorhandene Verbindung ablegt und 400027 ConnectionForcefullyClosedOnNewConnection in die IoT Hub-Protokolle schreibt.

• Um Nachrichten basierend auf dem Nachrichtentext weiterzuleiten, fügen Sie zuerst die Eigenschaft ct am Ende des MQTT-Themas hinzu, und legen Sie ihren Wert wie im folgenden Beispiel gezeigt fest application/json;charset=utf-8 . Weitere Informationen zum Weiterleiten von Nachrichten basierend auf den Nachrichteneigenschaften oder dem Nachrichtentext finden Sie in der Dokumentation „Abfragesyntax für das IoT Hub-Nachrichtenrouting“.

  devices/{device-id}/messages/events/$.ct=application%2Fjson%3Bcharset%3Dutf-8

Weitere Informationen finden Sie unter Senden und Empfangen von Nachrichten mit IoT Hub.

Empfangen von Cloud-zu-Gerät-Nachrichten

Zum Empfangen von Nachrichten von einem IoT Hub muss ein Gerät ein Abonnement unter Verwendung von devices/{device-id}/messages/devicebound/# als Themenfilter einrichten. Der Mehrebenen-Wildcard # im Themenfilter ermöglicht es dem Gerät, weitere Eigenschaften im Themennamen zu erhalten. IoT Hub lässt die Verwendung der Platzhalter # oder ? nicht zu, um Unterthemen zu filtern. IoT Hub ist kein Publish-Subscribe-Messaging-Broker für allgemeine Zwecke; er unterstützt nur die dokumentierten Themennamen und Themenfilter. Ein Gerät kann jeweils nur fünf Themen abonnieren.

Das Gerät empfängt keine Nachrichten von IoT Hub, bis es erfolgreich seinen gerätespezifischen Endpunkt abonniert hat, dargestellt durch den devices/{device-id}/messages/devicebound/# Themenfilter. Nachdem ein Abonnement eingerichtet wurde, empfängt das Gerät Cloud-zu-Gerät-Nachrichten, die nach dem Zeitpunkt des Abonnements an sie gesendet wurden. Wenn das Gerät eine Verbindung mit auf 0 festgelegtem CleanSession-Flag herstellt, behält das Abonnement verschiedene Sitzungen übergreifend bei. In diesem Fall empfängt das Gerät beim nächsten Verbindungsaufbau mit CleanSession 0 ausstehende Nachrichten, die ihm gesendet wurden, als es vom Netzwerk getrennt war. Wenn das Gerät jedoch das auf 1 festgelegte CleanSession-Flag verwendet, empfängt es erst dann Nachrichten von IoT Hub, wenn es dessen Geräteendpunkt abonniert hat.

IoT Hub sendet Nachrichten mit dem Themennamendevices/{device-id}/messages/devicebound/ oder devices/{device-id}/messages/devicebound/{property-bag}, wenn Nachrichteneigenschaften vorhanden sind. {property-bag} enthält URL-codierte Schlüssel-Wert-Paare von Nachrichteneigenschaften. Nur Anwendungseigenschaften und vom Benutzer festlegbare Systemeigenschaften (z.B. messageId oder correlationId) sind im Eigenschaftenbehälter enthalten. Systemeigenschaftennamen haben das Präfix $ , Anwendungseigenschaften verwenden den ursprünglichen Eigenschaftennamen ohne Präfix. Weitere Details zum Format des Eigenschaftenbehälters finden Sie unter Senden von D2C-Nachrichten.

Bei Cloud-zu-Gerät-Nachrichten werden die Werte im Eigenschaftenbehälter wie in folgender Tabelle gezeigt dargestellt:

Immobilienwert	Darstellung	BESCHREIBUNG
null	key	Nur der Schlüssel wird im Eigenschaftenbehälter angezeigt.
Leere Zeichenfolge	key=	Der Schlüssel gefolgt von einem Gleichheitszeichen ohne Wert
nicht NULL, nicht leerer Wert	key=value	Der Schlüssel gefolgt von einem Gleichheitszeichen und dem Wert

Das folgende Beispiel zeigt einen Eigenschaftenbehälter, der drei Anwendungseigenschaften enthält: prop1 mit einem Wert von null; prop2, eine leere Zeichenfolge („“) und prop3 mit einem Wert „eine Zeichenfolge“.

/?prop1&prop2=&prop3=a%20string

Wenn eine Geräteanwendung ein Thema mit QoS 2 abonniert, gewährt IoT Hub die maximale QoS-Ebene 1 im SUBACK-Paket . Danach übermittelt IoT Hub mithilfe von QoS 1 Nachrichten an das Gerät.

Abrufen der Eigenschaften von Gerätezwillingen

Als Erstes abonniert ein Gerät $iothub/twin/res/#, um die Antworten des Vorgangs zu erhalten. Anschließend wird eine leere Nachricht an das Thema $iothub/twin/GET/?$rid={request id} gesendet, wobei der Wert für request id ausgefüllt ist. Als Nächstes sendet der Dienst eine Antwortnachricht mit den Daten des Gerätezwillings im Thema $iothub/twin/res/{status}/?$rid={request-id}, indem der gleiche Wert für request id wie für die Anforderung verwendet wird.

Die Anforderungs-ID kann jeder beliebige gültige Wert für eine Nachrichteneigenschaft sein, und der Status wird als ganze Zahl validiert. Weitere Informationen finden Sie unter Senden und Empfangen von Nachrichten mit IoT Hub.

Der Text der Antwort enthält den Abschnitt mit den Eigenschaften des Gerätezwillings, wie im folgenden Antwortbeispiel gezeigt:

{
    "desired": {
        "telemetrySendFrequency": "5m",
        "$version": 12
    },
    "reported": {
        "telemetrySendFrequency": "5m",
        "batteryLevel": 55,
        "$version": 123
    }
}

Die möglichen Statuscodes lauten:

Status	BESCHREIBUNG
200	Erfolg
429	Zu viele Anforderungen (gedrosselt). Weitere Informationen finden Sie unter IoT Hub-Kontingente und -Einschränkung
5**	Serverfehler

Weitere Informationen finden Sie unter Verstehen und Verwenden von Gerätezwillingen in IoT Hub.

Aktualisieren der gemeldeten Eigenschaften des Gerätezwillings

Um gemeldete Eigenschaften zu aktualisieren, gibt das Gerät eine Anforderung an IoT Hub aus, indem es ein bestimmtes MQTT-Topic veröffentlicht. Nachdem IoT Hub die Anforderung verarbeitet hat, antwortet er mit dem Erfolgs- oder Fehlerstatus des Aktualisierungsvorgangs, indem er in einem anderen Thema veröffentlicht wird. Das Gerät kann dieses Thema abonnieren, um Benachrichtigungen über das Ergebnis der Twin Update-Anforderung zu erhalten. Um diese Art von Anforderungs-/Antwortinteraktion in MQTT zu implementieren, stellt das Gerät eine Anforderungs-ID ($rid) in seiner anfänglichen Updateanforderung bereit. Diese Anforderungs-ID ist dann in der Antwort von IoT Hub enthalten, damit das Gerät die Antwort auf die richtige Anforderung korreliert.

Die folgende Sequenz beschreibt, wie ein Gerät die gemeldeten Eigenschaften in dem Gerätezwilling in IoT Hub aktualisiert:

1. Ein Gerät abonniert zunächst das $iothub/twin/res/# Thema, damit es Antworten von IoT Hub empfangen kann.

2. Ein Gerät sendet eine Nachricht, die das Gerätezwillingsupdate enthält, an das Thema $iothub/twin/PATCH/properties/reported/?$rid={request-id}. Diese Nachricht enthält einen request ID-Wert.

3. Anschließend sendet der Dienst eine Antwortnachricht, die den neuen ETag-Wert für die Sammlung der gemeldeten Eigenschaften enthält, im Thema $iothub/twin/res/{status}/?$rid={request-id}. Diese Antwortnachricht verwendet den gleichen request id-Wert wie die Anforderung.

Der Text der Anforderungsnachricht enthält ein JSON-Dokument mit neuen Werten für gemeldete Eigenschaften. Jeder Member im JSON-Dokument wird aktualisiert, oder der entsprechende Member wird im Dokument des Gerätezwillings hinzugefügt. Wenn ein Member auf null festgelegt wurde, wird er aus dem enthaltenden Objekt gelöscht. Beispiel:

{
    "telemetrySendFrequency": "35m",
    "batteryLevel": 60
}

Die möglichen Statuscodes lauten:

Status	BESCHREIBUNG
204	Erfolg (es wird kein Inhalt zurückgegeben)
400	Ungültige Anforderung; falsch formatierter JSON-Code
429	Zu viele Anforderungen (gedrosselt), siehe Referenz: IoT Hub-Kontingente und -Drosselung
5**	Serverfehler

Der folgende Python-Codeschnipsel veranschaulicht den Aktualisierungsvorgang der vom Gerätezwilling gemeldeten Eigenschaften über MQTT mithilfe des Paho MQTT-Clients:

from paho.mqtt import client as mqtt

# authenticate the client with IoT Hub (not shown here)

client.subscribe("$iothub/twin/res/#")
rid = "1"
twin_reported_property_patch = "{\"firmware_version\": \"v1.1\"}"
client.publish("$iothub/twin/PATCH/properties/reported/?$rid=" +
               rid, twin_reported_property_patch, qos=0)

Wenn der Aktualisierungsprozess der gemeldeten Eigenschaften von Zwillingen erfolgreich ist, veröffentlicht IoT Hub eine Meldung an das folgende Thema: $iothub/twin/res/204/?$rid=1&$version=6, wobei 204 der Statuscode, der den Erfolg angibt, $rid=1 der der vom Gerät im Code bereitgestellten Anforderungs-ID entspricht und $version der Version des Abschnitts der gemeldeten Eigenschaften von Gerätezwillingen nach dem Update entspricht.

Weitere Informationen finden Sie unter Verstehen und Verwenden von Gerätezwillingen in IoT Hub.

Empfangen von aktualisierungsbenachrichtigungen für die gewünschten Eigenschaften

Wenn die Verbindung für ein Gerät hergestellt wird, sendet IoT Hub Benachrichtigungen an das Thema $iothub/twin/PATCH/properties/desired/?$version={new-version}. Die Benachrichtigungen enthalten den Inhalt der Aktualisierung, die vom Lösungs-Back-End durchgeführt wird. Beispiel:

{
    "telemetrySendFrequency": "5m",
    "route": null,
    "$version": 8
}

Für Aktualisierungen von Eigenschaften bedeutet die Angabe von null für die Werte, dass der JSON-Objektmember gelöscht wird. Außerdem gibt $version die neue Version des Abschnitts mit den gewünschten Eigenschaften des Zwillings an.

Wichtig

IoT Hub generiert Änderungsbenachrichtigungen nur, wenn Geräte verbunden sind. Stellen Sie sicher, dass Sie den Gerätewiederverbindungsablauf implementieren, um die gewünschten Eigenschaften zwischen IoT Hub und der Geräteanwendung zu synchronisieren.

Weitere Informationen finden Sie unter Verstehen und Verwenden von Gerätezwillingen in IoT Hub.

Antworten auf eine direkte Methode

Zuerst abonniert ein Gerät $iothub/methods/POST/#. IoT Hub sendet Methodenanforderungen an das Thema $iothub/methods/POST/{method-name}/?$rid={request-id}, die entweder gültigen JSON-Code oder leeren Text enthalten.

Als Antwort sendet das Gerät eine Nachricht mit einem gültigen JSON-Code oder leerem Text an das Thema $iothub/methods/res/{status}/?$rid={request-id}. In dieser Nachricht muss die Anforderungs-ID derjenigen in der Anforderungsnachricht entsprechen, und Status muss eine ganze Zahl sein.

Weitere Informationen finden Sie unter Verstehen und Aufrufen direkter Methoden von IoT Hub.

Nächste Schritte

Weitere Informationen zur Verwendung von MQTT finden Sie unter:

• MQTT-Dokumentation
• Tutorial: Verwenden von MQTT zum Entwickeln eines IoT-Geräteclients ohne Verwendung eines Geräte-SDK
• Beispiele für MQTT-Anwendungen
• Azure IoT SDKs