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

Der MQTT-Port (8883) wird in vielen Netzwerken von Unternehmen und Bildungseinrichtungen blockiert.The MQTT port (8883) is blocked in many corporate and educational networking environments. Wenn Sie Port 8883 in Ihrer Firewall nicht öffnen können, empfiehlt es sich, MQTT über WebSockets zu verwenden.If you can't open port 8883 in your firewall, we recommend using MQTT over Web Sockets. MQTT über WebSockets kommuniziert über Port 443, der in Netzwerkumgebungen fast immer geöffnet ist.MQTT over Web Sockets communicates over port 443, which is almost always open in networking environments. 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.To learn how to specify the MQTT and MQTT over Web Sockets protocols when using the Azure IoT SDKs, see Using the device SDKs.

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. Sie können MQTT über WebSockets auch im Parameter für das Clientprotokoll angeben.You can also specify MQTT over Web Sockets in the client protocol parameter. 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 IoT Hub über die Protokolle für MQTT oder MQTT über WebSockets 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 or the MQTT over Web Sockets protocol.

SpracheLanguage Parameter für das MQTT-ProtokollMQTT protocol parameter Parameter für das Protokoll für MQTT über WebSocketsMQTT over Web Sockets protocol parameter
Node.jsNode.js azure-iot-device-mqtt.Mqttazure-iot-device-mqtt.Mqtt azure-iot-device-mqtt.MqttWsazure-iot-device-mqtt.MqttWs
JavaJava IotHubClientProtocol.MQTTIotHubClientProtocol.MQTT IotHubClientProtocol.MQTT_WSIotHubClientProtocol.MQTT_WS
CC MQTT_ProtocolMQTT_Protocol MQTT_WebSocket_ProtocolMQTT_WebSocket_Protocol
C#C# TransportType.MqttTransportType.Mqtt TransportType.Mqtt greift auf MQTT über WebSockets zurück, wenn bei MQTT ein Fehler auftritt.TransportType.Mqtt falls back to MQTT over Web Sockets if MQTT fails. Um nur MQTT über WebSockets anzugeben, verwenden Sie TransportType.Mqtt_WebSocket_Only.To specify MQTT over Web Sockets only, use TransportType.Mqtt_WebSocket_Only
PythonPython Unterstützt standardmäßig MQTTSupports MQTT by default Fügen Sie websockets=True im Befehl hinzu, um den Client zu erstellen.Add websockets=True in the call to create the client

Das folgende Fragment zeigt, wie Sie bei Verwendung des Azure IoT SDK für Node.js das Protokoll für MQTT über WebSockets angeben:The following fragment shows how to specify the MQTT over Web Sockets protocol when using the Azure IoT Node.js SDK:

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 bei Verwendung des Azure IoT SDK für Python das Protokoll für MQTT über WebSockets angeben:The following fragment shows how to specify the MQTT over Web Sockets protocol when using the Azure IoT Python SDK:

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

Keep-Alive-StandardtimeoutDefault keep-alive timeout

Um sicherzustellen, dass eine Client/IoT Hub-Verbindung aktiv bleibt, senden sowohl der Dienst als auch der Client einander regelmäßig einen Keep-Alive-Ping.In order to ensure a client/IoT Hub connection stays alive, both the service and the client regularly send a keep-alive ping to each other. Der Client, der das IoT SDK verwendet, sendet in dem in der nachstehenden Tabelle definierten Intervall ein Keep-Alive:The client using IoT SDK sends a keep-alive at the interval defined in this table below:

SpracheLanguage Keep-Alive-StandardintervallDefault keep-alive interval KonfigurierbarConfigurable
Node.jsNode.js 180 Sekunden180 seconds NeinNo
JavaJava 230 Sekunden230 seconds NeinNo
CC 240 Sekunden240 seconds JaYes
C#C# 300 Sekunden300 seconds JaYes
Python (V2)Python (V2) 60 Sekunden60 seconds NeinNo

Entsprechend der MQTT-Spezifikation ist das Keep-Alive-Pingintervall von IoT Hub das 1,5-fache des Keep-Alive-Werts für Clients.Following MQTT spec, IoT Hub's keep-alive ping interval is 1.5 times the client keep-alive value. IoT Hub schränkt jedoch das maximale serverseitige Timeout auf 29,45 Minuten (1.767 Sekunden) ein, weil sämtliche Azure-Dienste an das TCP-Leerlauftimeout von Azure Load Balancer (29,45 Minuten) gebunden sind.However, IoT Hub limits the maximum server-side timeout to 29.45 minutes (1767 seconds) because all Azure services are bound to the Azure load balancer TCP idle timeout, which is 29.45 minutes.

So sendet beispielsweise ein Gerät, das das Java SDK verwendet, den Keep-Alive-Ping und verliert dann die Netzwerkkonnektivität.For example, a device using the Java SDK sends the keep-alive ping then loses network connectivity. 230 Sekunden später verpasst das Gerät den Keep-Alive-Ping, weil es offline ist.230 seconds later, the device misses the keep-alive ping because it's offline. 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.However, IoT Hub doesn't close the connection immediately - it waits another (230 * 1.5) - 230 = 115 seconds before disconnecting the device with the error 404104 DeviceConnectionClosedRemotely.

Als maximalen Keep-Alive-Wert für Clients können Sie 1767 / 1.5 = 1177 Sekunden festlegen.The maximum client keep-alive value you can set is 1767 / 1.5 = 1177 seconds. Das Keep-Alive wird durch jeglichen Datenverkehr zurückgesetzt.Any traffic will reset the keep-alive. Beispielsweise setzt eine erfolgreiche SAS-Tokenaktualisierung das Keep-Alive zurück.For example, a successful SAS token refresh resets the keep-alive.

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

Wie bereits erwähnt, muss bei Verwendung der Geräte-SDKs bei einem Wechsel von AMQP zu MQTT der Protokollparameter in der Clientinitialisierung geändert werden.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.

  • AMQP wird im Python SDK nicht unterstützt.AMQP is not supported in the Python SDK

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, und befolgen Sie die nachstehenden Codeanweisungen.For more information, see Set up X.509 security in your Azure IoT Hub and follow code instructions below.

    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 den CLI-Erweiterungsbefehl az iot hub generate-sas-token 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 CLI extension command az iot hub generate-sas-token to quickly generate a SAS token that you can copy and paste into your own code:

Für Azure IoT ToolsFor 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.

    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.

Ein Beispiel für C-Code, in dem MQTT ohne das Azure IoT C SDK verwendet wirdAn example of C code using MQTT without Azure IoT C SDK

In diesem Repository finden Sie einige Demoprojekte für C/C++, die zeigen, wie Sie Telemetrienachrichten senden und Ereignisse mit einem IoT Hub empfangen, ohne das Azure IoT C SDK verwenden zu müssen.In this repository, you'll find a couple of C/C++ demo projects showing how to send telemetry messages, receive events with an IoT hub without using the Azure IoT C SDK.

In diesen Beispielen dient die Eclipse Mosquitto-Bibliothek zum Senden von Nachrichten an den im IoT Hub implementierten MQTT-Broker.These samples use the Eclipse Mosquitto library to send message to the MQTT Broker implemented in the IoT hub.

Dieses Repository enthält Folgendes:This repository contains:

Für Windows:For Windows:

  • TelemetryMQTTWin32: Enthält Code zum Senden einer Telemetrienachricht an einen Azure IoT Hub, der auf einem Windows-Computer erstellt und ausgeführt wird.TelemetryMQTTWin32: contains code to send a telemetry message to an Azure IoT hub, built and run on a Windows machine.

  • SubscribeMQTTWin32: Enthält Code zum Abonnieren von Ereignissen eines bestimmten IoT Hubs auf einem Windows-Computer.SubscribeMQTTWin32: contains code to subscribe to events of a given IoT hub on a Windows machine.

  • DeviceTwinMQTTWin32: Enthält Code zum Abfragen und Abonnieren der Gerätezwillingsereignisse eines Geräts im Azure IoT Hub auf einem Windows-Computer.DeviceTwinMQTTWin32: contains code to query and subscribe to the device twin events of a device in the Azure IoT hub on a Windows machine.

  • PnPMQTTWin32: Enthält Code zum Senden einer Telemetrienachricht mit IoT Plug & Play-Gerätefunktionen in der Vorschauversion an einen Azure IoT Hub, der auf einem Windows-Computer erstellt und ausgeführt wird.PnPMQTTWin32: contains code to send a telemetry message with IoT Plug & Play preview Device capabilities to an Azure IoT hub, built and run on a Windows machine. Weitere Informationen zu IoT Plug & Play finden Sie hier.More on IoT Plug & Play here

Für Linux:For Linux:

  • MQTTLinux: Enthält Code und ein Buildskript zur Ausführung unter Linux (bisher wurden WSL, Ubuntu und Raspbian getestet).MQTTLinux: contains code and build script to run on Linux (WSL, Ubuntu, and Raspbian have been tested so far).

  • LinuxConsoleVS2019: Enthält denselben Code, aber in einem VS2019-Projekt für WSL (Windows-Subsystem für Linux).LinuxConsoleVS2019: contains the same code but in a VS2019 project targeting WSL (Windows Linux sub system). Dieses Projekt ermöglicht Ihnen das schrittweise Debuggen des unter Linux ausgeführten Codes in Visual Studio.This project allows you to debug the code running on Linux step by step from Visual Studio.

Für mosquitto_pub:For mosquitto_pub:

Dieser Ordner enthält zwei Beispielbefehle, die bei dem Hilfsprogrammtool „mosquitto_pub“ von Mosquitto.org verwendet werden.This folder contains two samples commands used with mosquitto_pub utility tool provided by Mosquitto.org.

  • „Mosquitto_sendmessage“: Dient zum Senden einer einfachen Textnachricht an einen Azure IoT Hub, der als Gerät fungiert.Mosquitto_sendmessage: to send a simple text message to an Azure IoT hub acting as a device.

  • „Mosquitto_subscribe“: Dient zum Anzeigen von Ereignissen, die in einem Azure IoT Hub eintreten.Mosquitto_subscribe: to see events occurring in an Azure IoT hub.

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 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=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_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()

Um sich mit einem Gerätezertifikat zu authentifizieren, aktualisieren Sie den obigen Codeausschnitt mit den folgenden Änderungen (siehe Abrufen eines X.509-Zertifizierungsstellenzertifikats, um mehr zur Vorbereitung der zertifikatsbasierten Authentifizierung zu erfahren):To authenticate using a device certificate, update the code snippet above with the following changes (see How to get an X.509 CA certificate on how to prepare for certificate-based authentication):

# 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=2018-06-30", 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 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. Weitere Details zum Format des Eigenschaftenbehälters finden Sie unter Senden von D2C-Nachrichten.For additional details about the format of the property bag, see Sending device-to-cloud messages.

Bei Cloud-zu-Gerät-Nachrichten werden die Werte im Eigenschaftenbehälter wie in folgender Tabelle gezeigt dargestellt:In cloud-to-device messages, values in the property bag are represented as in the following table:

EigenschaftswertProperty value DarstellungRepresentation BESCHREIBUNGDescription
null key Nur der Schlüssel wird im Eigenschaftenbehälter angezeigtOnly the key appears in the property bag
Leere Zeichenfolgeempty string key= Der Schlüssel gefolgt von einem Gleichheitszeichen ohne WertThe key followed by an equal sign with no value
nicht NULL, nicht leerer Wertnon-null, non-empty value key=value Der Schlüssel gefolgt von einem Gleichheitszeichen und dem WertThe key followed by an equal sign and the value

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“.The following example shows a property bag that contains three application properties: prop1 with a value of null; prop2, an empty string (""); and prop3 with a value of "a string".

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

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
200200 ErfolgSuccess
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 auch in der Antwort von IoT Hub enthalten, damit das Gerät die Antwort mit seiner jeweiligen früheren Anforderung korrelieren kann.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
204204 Erfolg (kein Inhalt)Success (no content is returned)
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 mean 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.

Weitere Ü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: