Kommunikation mit Ihrem IoT Hub mithilfe des Protokolls MQTTCommunicate with your IoT hub using the MQTT protocol

IoT Hub ermöglicht Geräten die Kommunikation mit den IoT Hub-Geräteendpunkten mithilfe von:IoT Hub enables devices to communicate with the IoT Hub device endpoints using:

  • MQTT v3.1.1 an Port 8883MQTT v3.1.1 on port 8883
  • MQTT v3.1.1 über WebSocket an Port 443MQTT v3.1.1 over WebSocket on port 443.

IoT Hub ist kein voll funktionsfähiger MQTT-Broker und unterstützt nicht alle im MQTT 3.1.1-Standard angegebenen Verhaltensweisen.IoT Hub is not a full-featured MQTT broker and does not support all the behaviors specified in the MQTT v3.1.1 standard. In diesem Artikel wird beschrieben, wie Geräte unterstützte MQTT-Verhaltensweisen für die Kommunikation mit IoT Hub verwenden können.This article describes how devices can use supported MQTT behaviors to communicate with IoT Hub.

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.Some of the features mentioned in this article, like cloud-to-device messaging, device twins, and device management, are only available in the standard tier of IoT hub. Weitere Informationen zu den IoT Hub-Tarifen „Basic“ und „Standard“ finden Sie unter Choose the right IoT Hub tier for your solution (Wählen des passenden IoT Hub-Tarifs für Ihre Lösung).For more information about the basic and standard IoT Hub tiers, see How to choose the right IoT Hub tier.

Die gesamte Gerätekommunikation mit IoT Hub muss mithilfe von TLS/SSL gesichert werden.All device communication with IoT Hub must be secured using TLS/SSL. Daher unterstützt IoT Hub keine nicht sicheren Verbindungen über Port 1883.Therefore, IoT Hub doesn’t support non-secure connections over port 1883.

Herstellen einer Verbindung mit einem IoT HubConnecting to IoT Hub

Ein Gerät kann das MQTT-Protokoll zum Herstellen einer Verbindung mit einem IoT-Hub über die folgenden Optionen verwenden.A device can use the MQTT protocol to connect to an IoT hub using any of the following options.

Verwenden der Geräte-SDKsUsing the device SDKs

Geräte-SDKs, die das MQTT-Protokoll unterstützen, stehen für Java, Node.js, C, C# und Python zur Verfügung.Device SDKs that support the MQTT protocol are available for Java, Node.js, C, C#, and Python. Die SDKs für Geräte verwenden die IoT Hub-Standard-Verbindungszeichenfolge zum Herstellen einer Verbindung mit einem IoT Hub.The device SDKs use the standard IoT Hub connection string to establish a connection to an IoT hub. Um das MQTT-Protokoll verwenden zu können, muss der Clientprotokollparameter auf MQTTfestgelegt werden.To use the MQTT protocol, the client protocol parameter must be set to MQTT. 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.By default, the device SDKs connect to an IoT Hub with the CleanSession flag set to 0 and use QoS 1 for message exchange with the IoT hub.

Wenn ein Gerät mit einem IoT Hub verbunden ist, werden mit den SDKs von Geräten Methoden bereitgestellt, die dem Gerät den Austausch von Nachrichten mit einem IoT Hub ermöglichen.When a device is connected to an IoT hub, the device SDKs provide methods that enable the device to exchange messages with an IoT hub.

Die folgende Tabelle enthält Links zu Codebeispielen für jede unterstützte Sprache und gibt die Parameter zum Herstellen einer Verbindung mit einem IoT Hub über das Protokoll MQTT an.The following table contains links to code samples for each supported language and specifies the parameter to use to establish a connection to IoT Hub using the MQTT protocol.

SpracheLanguage „Protocol“-ParameterProtocol parameter
Node.jsNode.js azure-iot-device-mqttazure-iot-device-mqtt
JavaJava IotHubClientProtocol.MQTTIotHubClientProtocol.MQTT
CC MQTT_ProtocolMQTT_Protocol
C#C# TransportType.MqttTransportType.Mqtt
PythonPython IoTHubTransportProvider.MQTTIoTHubTransportProvider.MQTT

Migrieren einer Geräte-App von AMQP zu MQTTMigrating a device app from AMQP to MQTT

Bei Verwendung der Geräte-SDKs muss bei einem Wechsel von AMQP zu MQTT der Protokollparameter in der Clientinitialisierung geändert werden, wie bereits erwähnt.If you are using the device SDKs, switching from using AMQP to MQTT requires changing the protocol parameter in the client initialization as stated previously.

Dabei sollten Sie die folgenden Punkte beachten:When doing so, make sure to check the following items:

  • Bei AMQP werden Fehler für viele Bedingungen zurückgegeben, bei MQTT wird dagegen die Verbindung beendet.AMQP returns errors for many conditions, while MQTT terminates the connection. Daher müssen an der Ausnahmebehandlungslogik möglicherweise einige Änderungen vorgenommen werden.As a result your exception handling logic might require some changes.

  • MQTT unterstützt beim Empfang von Cloud-zu-Gerät-Nachrichten keine reject-Vorgänge.MQTT does not support the reject operations when receiving cloud-to-device messages. Wenn Ihre Back-End-App eine Antwort von der Geräte-App erhalten muss, können Sie direkte Methoden verwenden.If your back-end app needs to receive a response from the device app, consider using direct methods.

Direktes Verwenden des Protokolls MQTT (als Gerät)Using the MQTT protocol directly (as a device)

Wenn ein Gerät die SDKs von Geräten nicht verwenden kann, lässt es sich dennoch mithilfe des Protokolls MQTT über den Port 8883 mit den öffentlichen Geräteendpunkten verbinden.If a device cannot use the device SDKs, it can still connect to the public device endpoints using the MQTT protocol on port 8883. Das Gerät sollte im CONNECT-Paket die folgenden Werte verwenden:In the CONNECT packet, the device should use the following values:

  • Verwenden Sie für das Feld ClientId die deviceId-Eigenschaft.For the ClientId field, use the deviceId.

  • Verwenden Sie {iothubhostname}/{device_id}/?api-version=2018-06-30 für das Feld Benutzername, wobei {iothubhostname} der vollständige CNAME für den IoT Hub ist.For the Username field, use {iothubhostname}/{device_id}/?api-version=2018-06-30, where {iothubhostname} is the full CName of the IoT hub.

    Beispiel: Wenn der Name für den IoT Hub contoso.azure devices.net und der Name des Geräts MyDevice01 lautet, sollte das vollständige Feld Benutzername Folgendes enthalten:For example, if the name of your IoT hub is contoso.azure-devices.net and if the name of your device is MyDevice01, the full Username field should contain:

    contoso.azure-devices.net/MyDevice01/?api-version=2018-06-30

  • Verwenden Sie im Feld Kennwort ein SAS-Token.For the Password field, use a SAS token. Das Format des SAS-Tokens ist das gleiche wie das für die Protokolle HTTPS und AMQP:The format of the SAS token is the same as for both the HTTPS and AMQP protocols:

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

    Hinweis

    Bei Verwendung der X.509-Zertifikatauthentifizierung sind keine SAS-Tokenkennwörter erforderlich.If you use X.509 certificate authentication, SAS token passwords are not required. Weitere Informationen finden Sie unter Einrichten der X.509-Sicherheit in Ihrem Azure IoT Hub.For more information, see Set up X.509 security in your Azure IoT Hub

    Weitere Informationen zum Generieren von SAS-Token finden Sie unter Verwenden von IoT-Hub-Sicherheitstoken im Abschnitt zu Geräten.For more information about how to generate SAS tokens, see the device section of Using IoT Hub security tokens.

    Beim Testen können Sie auch die plattformübergreifenden Azure IoT-Tools für Visual Studio Code oder das Tool Device Explorer nutzen, um schnell ein SAS-Token zu generieren, das Sie kopieren und in Ihren eigenen Code einfügen können:When testing, you can also use the cross-platform Azure IoT Tools for Visual Studio Code or the Device Explorer tool to quickly generate a SAS token that you can copy and paste into your own code:

Für Azure IoT-Tools:For Azure IoT Tools:

  1. Erweitern Sie in der unteren linken Ecke von Visual Studio Code die Registerkarte AZURE IOT HUB-GERÄTE.Expand the AZURE IOT HUB DEVICES tab in the bottom left corner of Visual Studio Code.

  2. Klicken Sie mit der rechten Maustaste auf Ihr Gerät, und klicken Sie auf SAS-Token für Gerät generieren.Right-click your device and select Generate SAS Token for Device.

  3. Legen Sie die Ablaufzeit fest, und drücken Sie die EINGABETASTE.Set expiration time and press 'Enter'.

  4. Das SAS-Token wird erstellt und in die Zwischenablage kopiert.The SAS token is created and copied to clipboard.

Führen Sie im Device Explorer folgende Schritte durch:For Device Explorer:

  1. Klicken Sie in Device Explorer auf die Registerkarte Verwaltung.Go to the Management tab in Device Explorer.

  2. Klicken Sie auf SAS Token (oben rechts).Click SAS Token (top right).

  3. Wählen Sie unter SASTokenForm Ihr Gerät in der Dropdownliste DeviceID aus.On SASTokenForm, select your device in the DeviceID drop down. Legen Sie Ihre TTLfest.Set your TTL.

  4. Klicken Sie auf Generieren , um Ihr Token zu erstellen.Click Generate to create your token.

    Das generierte SAS-Token weist die folgende Struktur auf:The SAS token that's generated has the following structure:

    HostName={your hub name}.azure-devices.net;DeviceId=javadevice;SharedAccessSignature=SharedAccessSignature sr={your hub name}.azure-devices.net%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:The part of this token to use as the Password field to connect using MQTT is:

    SharedAccessSignature sr={your hub name}.azure-devices.net%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

Für die MQTT-Pakete CONNECT und DISCONNECT löst IoT Hub ein Ereignis im Kanal Vorgangsüberwachung aus.For MQTT connect and disconnect packets, IoT Hub issues an event on the Operations Monitoring channel. Dieses Ereignis weist zusätzliche Informationen auf, mit deren Hilfe Sie Konnektivitätsprobleme beheben können.This event has additional information that can help you to troubleshoot connectivity issues.

Die Geräte-App kann eine Will-Nachricht im CONNECT-Paket angeben.The device app can specify a Will message in the CONNECT packet. Für die Geräte-App sollte devices/{device_id}/messages/events/ oder devices/{device_id}/messages/events/{property_bag} als Will-Themenname verwendet werden, um festzulegen, dass Will-Nachrichten als Telemetrienachricht weitergeleitet werden sollen.The device app should use devices/{device_id}/messages/events/ or devices/{device_id}/messages/events/{property_bag} as the Will topic name to define Will messages to be forwarded as a telemetry message. Wenn die Netzwerkverbindung geschlossen ist, aber vorher kein DISCONNECT-Paket vom Gerät eingegangen ist, sendet IoT Hub in diesem Fall die im CONNECT-Paket bereitgestellte Will-Nachricht an den Telemetriekanal.In this case, if the network connection is closed, but a DISCONNECT packet was not previously received from the device, then IoT Hub sends the Will message supplied in the CONNECT packet to the telemetry channel. Der Telemetriekanal kann entweder der Standardendpunkt Ereignisse oder ein benutzerdefinierter Endpunkt sein, der per IoT Hub-Routing definiert wird.The telemetry channel can be either the default Events endpoint or a custom endpoint defined by IoT Hub routing. Die Nachricht verfügt über die iothub-MessageType-Eigenschaft, der der Wert Will zugewiesen ist.The message has the iothub-MessageType property with a value of Will assigned to it.

Direktes Verwenden des Protokolls MQTT (als Modul)Using the MQTT protocol directly (as a module)

Eine Verbindung mit IoT Hub über MQTT mithilfe einer Modulidentität erfolgt ähnlich wie beim Gerät (siehe die Beschreibung oben). Allerdings müssen Sie folgende Schritte ausführen:Connecting to IoT Hub over MQTT using a module identity is similar to the device (described above) but you need to use the following:

  • Legen Sie für die Client-ID {device_id}/{module_id} fest.Set the client id to {device_id}/{module_id}.

  • Bei einer Authentifizierung mit Benutzername und Kennwort legen Sie für den Benutzernamen <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2018-06-30 fest, und verwenden Sie das der Modulidentität zugeordnete SAS-Token als Ihr Kennwort.If authenticating with username and password, set the username to <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2018-06-30 and use the SAS token associated with the module identity as your password.

  • Verwenden Sie devices/{device_id}/modules/{module_id}/messages/events/ als Thema für die Veröffentlichung von Telemetriedaten.Use devices/{device_id}/modules/{module_id}/messages/events/ as topic for publishing telemetry.

  • Verwenden Sie devices/{device_id}/modules/{module_id}/messages/events/ als Will-Thema.Use devices/{device_id}/modules/{module_id}/messages/events/ as WILL topic.

  • Die Zwillingsthemen GET und PATCH sind bei Modulen und Geräten identisch.The twin GET and PATCH topics are identical for modules and devices.

  • Das Zwillingsstatusthema ist bei Modulen und Geräten identisch.The twin status topic is identical for modules and devices.

TLS/SSL-KonfigurationTLS/SSL configuration

Damit Sie das MQTT-Protokoll direkt verwenden können, muss Ihr Client die Verbindung über TLS/SSL herstellen.To use the MQTT protocol directly, your client must connect over TLS/SSL. Wenn Sie versuchen, diesen Schritt zu überspringen, treten Verbindungsfehler auf.Attempts to skip this step fail with connection errors.

Möglicherweise müssen Sie das DigiCert Baltimore-Stammzertifikat herunterladen und darauf verweisen, um eine TLS-Verbindung herstellen zu können.In order to establish a TLS connection, you may need to download and reference the DigiCert Baltimore Root Certificate. Dieses Zertifikat wird von Azure zum Sichern der Verbindung verwendet.This certificate is the one that Azure uses to secure the connection. Sie finden dieses Zertifikat im Repository Azure-iot-sdk-c.You can find this certificate in the Azure-iot-sdk-c repository. Weitere Informationen zu diesen Zertifikaten finden Sie auf der Website von Digicert.More information about these certificates can be found on Digicert's website.

Ein Beispiel zur Implementierung mithilfe der Python-Version der Paho MQTT-Bibliothek von der Eclipse Foundation könnte wie folgt aussehen.An example of how to implement this using the Python version of the Paho MQTT library by the Eclipse Foundation might look like the following.

Installieren Sie zunächst die Paho-Bibliothek aus Ihrer Befehlszeilenumgebung:First, install the Paho library from your command-line environment:

pip install paho-mqtt

Implementieren Sie anschließend den Client in einem Python-Skript.Then, implement the client in a Python script. Ersetzen Sie die Platzhalter wie folgt:Replace the placeholders as follows:

  • <local path to digicert.cer> ist der Pfad zu einer lokalen Datei, die das DigiCert Baltimore-Stammzertifikat enthält.<local path to digicert.cer> is the path to a local file that contains the DigiCert Baltimore Root certificate. 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.You can create this file by copying the certificate information from certs.c in the Azure IoT SDK for C. Include the lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----, remove the " marks at the beginning and end of every line, and remove the \r\n characters at the end of every line.

  • <device id from device registry> ist die ID eines Geräts, das Sie Ihrem IoT Hub hinzugefügt haben.<device id from device registry> is the ID of a device you added to your IoT hub.

  • <generated SAS token> ist ein SAS-Token für das Gerät, das wie zuvor in diesem Artikel beschrieben erstellt wurde.<generated SAS token> is a SAS token for the device created as described previously in this article.

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

from paho.mqtt import client as mqtt
import ssl

path_to_root_cert = "<local path to digicert.cer>"
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=2018-06-30", 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, 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()

Senden von D2C-NachrichtenSending device-to-cloud messages

Nachdem Sie erfolgreich eine Verbindung hergestellt haben, kann ein Gerät Nachrichten mithilfe von devices/{device_id}/messages/events/ oder devices/{device_id}/messages/events/{property_bag} als Themenname an IoT Hub senden.After making a successful connection, a device can send messages to IoT Hub using devices/{device_id}/messages/events/ or devices/{device_id}/messages/events/{property_bag} as a Topic Name. Das {property_bag} -Element ermöglicht dem Gerät das Senden von Nachrichten mit zusätzlichen Eigenschaften in einem URL-codierten Format.The {property_bag} element enables the device to send messages with additional properties in a url-encoded format. Beispiel:For example:

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

Hinweis

Dieses {property_bag}-Element verwendet die gleiche Codierung wie Abfragezeichenfolgen im HTTPS-Protokoll.This {property_bag} element uses the same encoding as query strings in the HTTPS protocol.

Hier ist eine Liste mit dem spezifischen Verhalten für die IoT Hub-Implementierung angegeben:The following is a list of IoT Hub implementation-specific behaviors:

  • IoT Hub unterstützt keine QoS 2-Nachrichten.IoT Hub does not support QoS 2 messages. Wenn eine Geräte-App eine Nachricht mit QoS 2veröffentlicht, schließt IoT Hub die Netzwerkverbindung.If a device app publishes a message with QoS 2, IoT Hub closes the network connection.

  • IoT Hub speichert Beibehaltungsnachrichten („Retain“) nicht beständig.IoT Hub does not persist Retain messages. Wenn ein Geräte eine Nachricht mit auf 1 festgelegtem RETAIN-Flag sendet, fügt IoT Hub der Nachricht die Anwendungseigenschaft x-opt-retain hinzu.If a device sends a message with the RETAIN flag set to 1, IoT Hub adds the x-opt-retain application property to the message. In diesem Fall speichert IoT Hub die Beibehaltungsnachricht nicht beständig, sondern übergibt sie an die Back-End-App.In this case, instead of persisting the retain message, IoT Hub passes it to the backend app.

  • IoT Hub unterstützt nur eine aktive MQTT-Verbindung pro Gerät.IoT Hub only supports one active MQTT connection per device. Jede neue MQTT-Verbindung für die gleiche Geräte-ID bewirkt, dass IoT Hub die vorhandene Verbindung löscht.Any new MQTT connection on behalf of the same device ID causes IoT Hub to drop the existing connection.

Weitere Informationen finden Sie im Entwicklerhandbuch zum Messaging.For more information, see Messaging developer's guide.

Empfangen von C2D-NachrichtenReceiving cloud-to-device messages

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.To receive messages from IoT Hub, a device should subscribe using devices/{device_id}/messages/devicebound/# as a Topic Filter. Der Platzhalter mit mehreren Ebenen # im Themenfilter wird nur verwendet, um dem Gerät das Empfangen zusätzlicher Eigenschaften im Themennamen zu erlauben.The multi-level wildcard # in the Topic Filter is used only to allow the device to receive additional properties in the topic name. IoT Hub lässt die Verwendung des Platzhalters # oder ? für die Filterung von Unterthemen nicht zu.IoT Hub does not allow the usage of the # or ? wildcards for filtering of subtopics. Da IoT Hub kein allgemeiner Nachrichtenbrokerdienst für das Veröffentlichen und Abonnieren ist, werden nur die dokumentierten Themennamen und -filter unterstützt.Since IoT Hub is not a general-purpose pub-sub messaging broker, it only supports the documented topic names and topic filters.

Das Gerät empfängt erst Nachrichten von der IoT Hub-Instanz, nachdem es deren gerätespezifischen Endpunkt erfolgreich abonniert hat, der vom Themenfilter devices/{device_id}/messages/devicebound/# dargestellt wird.The device does not receive any messages from IoT Hub, until it has successfully subscribed to its device-specific endpoint, represented by the devices/{device_id}/messages/devicebound/# topic filter. Nachdem ein Abonnement eingerichtet wurde, empfängt das Gerät C2D-Nachrichten, die nach dem Zeitpunkt des Abonnements an das Gerät gesendet wurden.After a subscription has been established, the device receives cloud-to-device messages that were sent to it after the time of the subscription. Wenn das Gerät eine Verbindung mit auf 0 festgelegtem CleanSession-Flag herstellt, behält das Abonnement verschiedene Sitzungen übergreifend bei.If the device connects with CleanSession flag set to 0, the subscription is persisted across different sessions. 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.In this case, the next time the device connects with CleanSession 0 it receives any outstanding messages sent to it while disconnected. Wenn das Gerät das auf 1 festgelegte CleanSession-Flag verwendet, empfängt es erst dann Nachrichten von der IoT Hub-Instanz, wenn es deren Geräteendpunkt abonniert.If the device uses CleanSession flag set to 1 though, it does not receive any messages from IoT Hub until it subscribes to its device-endpoint.

IoT Hub sendet Nachrichten mit dem Themennamen devices/{device_id}/messages/devicebound/ oder devices/{device_id}/messages/devicebound/{property_bag}, wenn Nachrichteneigenschaften vorhanden sind.IoT Hub delivers messages with the Topic Name devices/{device_id}/messages/devicebound/, or devices/{device_id}/messages/devicebound/{property_bag} when there are message properties. {property_bag} enthält URL-codierte Schlüssel-Wert-Paare von Nachrichteneigenschaften.{property_bag} contains url-encoded key/value pairs of message properties. Nur Anwendungseigenschaften und vom Benutzer festlegbare Systemeigenschaften (z.B. messageId oder correlationId) sind im Eigenschaftenbehälter enthalten.Only application properties and user-settable system properties (such as messageId or correlationId) are included in the property bag. Systemeigenschaftennamen haben das Präfix $ , Anwendungseigenschaften verwenden den ursprünglichen Eigenschaftennamen ohne Präfix.System property names have the prefix $, application properties use the original property name with no prefix.

Wenn eine Geräte-App ein Thema mit QoS 2 abonniert, gewährt IoT Hub im SUBACK-Paket maximal die QoS-Ebene 1.When a device app subscribes to a topic with QoS 2, IoT Hub grants maximum QoS level 1 in the SUBACK packet. Danach übermittelt IoT Hub mithilfe von QoS 1 Nachrichten an das Gerät.After that, IoT Hub delivers messages to the device using QoS 1.

Abrufen der Eigenschaften eines GerätezwillingsRetrieving a device twin's properties

Als Erstes abonniert ein Gerät $iothub/twin/res/#, um die Antworten des Vorgangs zu erhalten.First, a device subscribes to $iothub/twin/res/#, to receive the operation's responses. 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.Then, it sends an empty message to topic $iothub/twin/GET/?$rid={request id}, with a populated value for request ID. Als Nächstes sendet der Dienst eine Antwortnachricht mit den Daten des Gerätezwillings im Thema $iothub/twin/res/{status}/?$rid={request id}, indem die gleiche request id wie für die Anforderung verwendet wird.The service then sends a response message containing the device twin data on topic $iothub/twin/res/{status}/?$rid={request id}, using the same request ID as the request.

Die Anforderungs-ID (request id) kann ein beliebiger gültiger Wert für den Eigenschaftswert einer Nachricht sein (siehe Entwicklerhandbuch zum IoT-Hub-Messaging). Der Status wird als Integer validiert.Request ID can be any valid value for a message property value, as per IoT Hub messaging developer's guide, and status is validated as an integer.

Der Text der Antwort enthält den Abschnitt mit den Eigenschaften des Gerätezwillings, wie im folgenden Antwortbeispiel gezeigt:The response body contains the properties section of the device twin, as shown in the following response example:

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

Die möglichen Statuscodes lauten:The possible status codes are:

StatusStatus BESCHREIBUNGDescription
204204 Erfolg (kein Inhalt)Success (no content is returned)
429429 Zu viele Anforderungen (gedrosselt), siehe IoT Hub-DrosselungToo many requests (throttled), as per IoT Hub throttling
5**5** ServerfehlerServer errors

Weitere Informationen finden Sie im Entwicklerhandbuch zu Gerätezwillingen.For more information, see Device twins developer's guide.

Aktualisieren der gemeldeten Eigenschaften des GerätezwillingsUpdate device twin's reported properties

Zum Aktualisieren der gemeldeten Eigenschaften gibt das Gerät eine Anforderung an den IoT Hub in Form einer Veröffentlichung über ein designiertes MQTT-Thema aus.To update reported properties, the device issues a request to IoT Hub via a publication over a designated MQTT topic. Nach dem Verarbeiten dieser Anforderung antwortet IoT Hub mit dem Erfolgs- oder Fehlerstatus des Aktualisierungsvorgangs in Form einer Veröffentlichung unter einem anderen Thema.After processing the request, IoT Hub responds the success or failure status of the update operation via a publication to another topic. Dieses Thema kann vom Gerät abonniert werden, um es über das Ergebnis der Aktualisierungsanforderung seines Gerätezwillings zu benachrichtigen.This topic can be subscribed by the device in order to notify it about the result of its twin update request. Um diese Art von Anforderungs-/Antwortinteraktion in MQTT zu implementieren, nutzen wir das Konzept der Anforderungs-ID ($rid), die ursprünglich vom Gerät in seiner Aktualisierungsanforderung bereitgestellt wurde.To implement this type of request/response interaction in MQTT, we leverage the notion of request id ($rid) provided initially by the device in its update request. Diese Anforderungs-ID ist ebenfalls in der Antwort von IoT Hub enthalten, um dem Gerät das Zuordnen der Antwort zu seiner einzelnen früheren Anforderung zu ermöglichen.This request id is also included in the response from IoT Hub to allow the device to correlate the response to its particular earlier request.

Die folgende Sequenz beschreibt, wie ein Gerät die gemeldeten Eigenschaften in dem Gerätezwilling in IoT Hub aktualisiert:The following sequence describes how a device updates the reported properties in the device twin in IoT Hub:

  1. Ein Gerät muss zuerst das Thema $iothub/twin/res/# abonnieren, um die Antworten des Vorgangs von IoT Hub zu empfangen.A device must first subscribe to the $iothub/twin/res/# topic to receive the operation's responses from IoT Hub.

  2. Ein Gerät sendet eine Nachricht, die das Gerätezwillingsupdate enthält, an das Thema $iothub/twin/PATCH/properties/reported/?$rid={request id}.A device sends a message that contains the device twin update to the $iothub/twin/PATCH/properties/reported/?$rid={request id} topic. Diese Nachricht enthält einen request ID-Wert.This message includes a request ID value.

  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}.The service then sends a response message that contains the new ETag value for the reported properties collection on topic $iothub/twin/res/{status}/?$rid={request id}. Diese Antwortnachricht verwendet den gleichen request id-Wert wie die Anforderung.This response message uses the same request ID as the request.

Der Nachrichtentext der Anforderung enthält ein JSON-Dokument mit neuen Werten für gemeldete Eigenschaften.The request message body contains a JSON document, that contains new values for reported properties. Jeder Member im JSON-Dokument wird aktualisiert, oder der entsprechende Member wird im Dokument des Gerätezwillings hinzugefügt.Each member in the JSON document updates or add the corresponding member in the device twin’s document. Wenn ein Member auf null festgelegt ist, wird der Member aus dem enthaltenden Objekt gelöscht.A member set to null, deletes the member from the containing object. Beispiel:For example:

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

Die möglichen Statuscodes lauten:The possible status codes are:

StatusStatus BESCHREIBUNGDescription
200200 ErfolgreichSuccess
400400 Ungültige Anforderung;Bad Request. falsch formatierter JSON-CodeMalformed JSON
429429 Zu viele Anforderungen (gedrosselt), siehe IoT Hub-DrosselungToo many requests (throttled), as per IoT Hub throttling
5**5** ServerfehlerServer errors

Der Python-Codeausschnitt unten veranschaulicht den Aktualisierungsvorgang der vom Gerätezwilling gemeldeten Eigenschaften über MQTT (mithilfe des Paho MQTT-Clients):The python code snippet below, demonstrates the twin reported properties update process over MQTT (using Paho MQTT client):

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)

Bei erfolgreichem Abschluss des Aktualisierungsvorgangs der vom Gerätezwilling gemeldeten Eigenschaften oben weist die Veröffentlichungsnachricht von IoT Hub das folgende Thema auf: $iothub/twin/res/204/?$rid=1&$version=6, wobei 204 der Statuscode ist, der den Erfolg angibt, $rid=1 der vom Gerät im Code übergebenen Anforderungs-ID und $version der Version des Abschnitts der gemeldeten Eigenschaften der Gerätezwillinge nach der Aktualisierung entspricht.Upon success of twin reported properties update operation above, the publication message from IoT Hub will have the following topic: $iothub/twin/res/204/?$rid=1&$version=6, where 204 is the status code indicating success, $rid=1 corresponds to the request ID provided by the device in the code, and $version corresponds to the version of reported properties section of device twins after the update.

Weitere Informationen finden Sie im Entwicklerhandbuch zu Gerätezwillingen.For more information, see Device twins developer's guide.

Empfangen von Aktualisierungsbenachrichtigungen für gewünschte EigenschaftenReceiving desired properties update notifications

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.When a device is connected, IoT Hub sends notifications to the topic $iothub/twin/PATCH/properties/desired/?$version={new version}, which contain the content of the update performed by the solution back end. Beispiel:For example:

{
    "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.As for property updates, null values means that the JSON object member is being deleted. Beachten Sie auch, dass $version die neue Version des Abschnitts mit den gewünschten Eigenschaften des Zwillings angibt.Also, note that $version indicates the new version of the desired properties section of the twin.

Wichtig

IoT Hub generiert Änderungsbenachrichtigungen nur, wenn Geräte verbunden sind.IoT Hub generates change notifications only when devices are connected. Achten Sie darauf, den Flow zur Wiederherstellung der Geräteverbindung zu implementieren, um für die gewünschten Eigenschaften die Synchronisierung zwischen dem IoT-Hub und der Geräte-App aufrechtzuerhalten.Make sure to implement the device reconnection flow to keep the desired properties synchronized between IoT Hub and the device app.

Weitere Informationen finden Sie im Entwicklerhandbuch zu Gerätezwillingen.For more information, see Device twins developer's guide.

Antworten auf eine direkte MethodeRespond to a direct method

Als Erstes muss ein Gerät $iothub/methods/POST/# abonnieren.First, a device has to subscribe to $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.IoT Hub sends method requests to the topic $iothub/methods/POST/{method name}/?$rid={request id}, with either a valid JSON or an empty body.

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}.To respond, the device sends a message with a valid JSON or empty body to the topic $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.In this message, the request ID must match the one in the request message, and status must be an integer.

Weitere Informationen finden Sie im Entwicklerhandbuch zu direkten Methoden.For more information, see Direct method developer's guide.

Zusätzliche ÜberlegungenAdditional considerations

Wenn Sie das Verhalten des MQTT-Protokolls auf der Cloudseite anpassen müssen, sollten Sie den Artikel zum Azure IoT-Protokollgateway lesen.As a final consideration, if you need to customize the MQTT protocol behavior on the cloud side, you should review the Azure IoT protocol gateway. Diese Software ermöglicht Ihnen die Bereitstellung eines benutzerdefinierten Hochleistungs-Protokollgateways, das eine direkte Schnittstelle mit IoT Hub bildet.This software enables you to deploy a high-performance custom protocol gateway that interfaces directly with IoT Hub. Das Azure IoT-Protokollgateway dient zum Anpassen des Geräteprotokolls zum Unterstützen von Brownfield MQTT-Bereitstellungen oder anderer benutzerdefinierter Protokolle.The Azure IoT protocol gateway enables you to customize the device protocol to accommodate brownfield MQTT deployments or other custom protocols. Dieser Ansatz setzt jedoch voraus, dass Sie ein benutzerdefiniertes Protokollgateway ausführen und betreiben.This approach does require, however, that you run and operate a custom protocol gateway.

Nächste SchritteNext steps

Weitere Informationen zum MQTT-Protokoll finden Sie in der MQTT-Dokumentation.To learn more about the MQTT protocol, see the MQTT documentation.

Weitere Informationen zum Planen Ihrer IoT Hub-Bereitstellung finden Sie unter:To learn more about planning your IoT Hub deployment, see:

Weitere Informationen zu den Funktionen von IoT Hub finden Sie unter:To further explore the capabilities of IoT Hub, see: