Communiceren met uw IoT-hub met behulp van het MQTT-ProtocolCommunicate with your IoT hub using the MQTT protocol

Met IoT Hub kunnen apparaten communiceren met de eind punten van IoT Hub apparaten met behulp van:IoT Hub enables devices to communicate with the IoT Hub device endpoints using:

  • MQTT v 3.1.1 op poort 8883MQTT v3.1.1 on port 8883
  • MQTT v 3.1.1 over WebSocket op poort 443.MQTT v3.1.1 over WebSocket on port 443.

IoT Hub is niet een volledig functionele MQTT-broker en biedt geen ondersteuning voor al het gedrag in de MQTT v3.1.1-standaard.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 dit artikel wordt beschreven hoe apparaten ondersteund MQTT-gedrag kunnen gebruiken om te communiceren met IoT Hub.This article describes how devices can use supported MQTT behaviors to communicate with IoT Hub.

Notitie

Sommige van de functies die in dit artikel worden genoemd, zoals cloud-naar-apparaat-berichten, apparaatdubbels en apparaatbeheer, zijn alleen beschikbaar in de standaardlaag van IoT Hub.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. Raadpleeg How to choose the right IoT Hub tier (De juiste IoT Hub-prijscategorie kiezen) voor meer informatie over de Basic- en Standard-prijscategorieën van IoT Hub.For more information about the basic and standard IoT Hub tiers, see How to choose the right IoT Hub tier.

De communicatie van alle apparaten met IoT Hub moet worden beveiligd met behulp van TLS/SSL.All device communication with IoT Hub must be secured using TLS/SSL. Daarom biedt IoT Hub geen ondersteuning voor niet-beveiligde verbindingen via poort 1883.Therefore, IoT Hub doesn't support non-secure connections over port 1883.

Verbinding maken met IoT HubConnecting to IoT Hub

Een apparaat kan het MQTT-protocol gebruiken om verbinding te maken met een IoT-hub met behulp van een van de volgende opties.A device can use the MQTT protocol to connect to an IoT hub using any of the following options.

De MQTT-poort (8883) is geblokkeerd in veel bedrijfs-en educatieve netwerk omgevingen.The MQTT port (8883) is blocked in many corporate and educational networking environments. Als u poort 8883 niet in uw firewall kunt openen, kunt u het beste MQTT via web Sockets gebruiken.If you can't open port 8883 in your firewall, we recommend using MQTT over Web Sockets. MQTT via web sockets communiceert via poort 443, wat bijna altijd is geopend in netwerk omgevingen.MQTT over Web Sockets communicates over port 443, which is almost always open in networking environments. Zie de apparaat-Sdk's gebruikenvoor meer informatie over het opgeven van de MQTT en MQTT via web sockets-protocollen wanneer u de Azure IOT sdk's gebruikt.To learn how to specify the MQTT and MQTT over Web Sockets protocols when using the Azure IoT SDKs, see Using the device SDKs.

De apparaat-Sdk's gebruikenUsing the device SDKs

Apparaat-sdk's die het MQTT-protocol ondersteunen, zijn beschikbaar voor Java, node. js, C, C# en python.Device SDKs that support the MQTT protocol are available for Java, Node.js, C, C#, and Python. De Sdk's van het apparaat maken gebruik van de Standard-IoT Hub connection string om een verbinding met een IoT-hub tot stand te brengen.The device SDKs use the standard IoT Hub connection string to establish a connection to an IoT hub. Als u het MQTT-protocol wilt gebruiken, moet de para meter client protocol worden ingesteld op MQTT.To use the MQTT protocol, the client protocol parameter must be set to MQTT. U kunt ook MQTT via web sockets opgeven in de para meter client protocol.You can also specify MQTT over Web Sockets in the client protocol parameter. De Sdk's van het apparaat maken standaard verbinding met een IoT Hub met de vlag CleanSession ingesteld op 0 en gebruiken QoS 1 voor berichten uitwisseling met de IOT-hub.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.

Wanneer een apparaat is verbonden met een IoT-hub, bieden de Sdk's van het apparaat methoden die het apparaat in staat stellen om berichten uit te wisselen met een IoT-hub.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.

De volgende tabel bevat koppelingen naar code voorbeelden voor elke ondersteunde taal en geeft de para meter op die moet worden gebruikt om een verbinding tot stand te brengen met IoT Hub met behulp van het MQTT-of het MQTT via web sockets-protocol.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.

TaalLanguage Para meter MQTT-ProtocolMQTT protocol parameter MQTT over web sockets protocol-para meterMQTT 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
GC MQTT_ProtocolMQTT_Protocol MQTT_WebSocket_ProtocolMQTT_WebSocket_Protocol
C#C# Transport type. MqttTransportType.Mqtt Transport type. Mqtt valt terug naar MQTT via web sockets als MQTT mislukt.TransportType.Mqtt falls back to MQTT over Web Sockets if MQTT fails. Als u alleen MQTT via web-sockets wilt opgeven, gebruikt u transport type. Mqtt_WebSocket_OnlyTo specify MQTT over Web Sockets only, use TransportType.Mqtt_WebSocket_Only
PythonPython Biedt standaard ondersteuning voor MQTTSupports MQTT by default Toevoegen websockets=True in de aanroep voor het maken van de clientAdd websockets=True in the call to create the client

Het volgende fragment laat zien hoe u het MQTT via web sockets kunt opgeven wanneer u de Azure IoT node. js-SDK gebruikt: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);

Het volgende fragment laat zien hoe u het MQTT via web sockets-protocol opgeeft wanneer u de Azure IoT python-SDK gebruikt: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)

Standaard time-out voor Keep-AliveDefault keep-alive timeout

Om ervoor te zorgen dat een client/IoT Hub verbinding actief blijft, worden zowel de service als de client regel matig een Keep-Alive ping naar elkaar verzonden.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. De client die IoT SDK gebruikt, verzendt een Keep-Alive met het interval dat is gedefinieerd in deze tabel:The client using IoT SDK sends a keep-alive at the interval defined in this table below:

TaalLanguage Standaard interval voor Keep-AliveDefault keep-alive interval ConfigureerbaarConfigurable
Node.jsNode.js 180 seconden180 seconds NeeNo
JavaJava 230 seconden230 seconds NeeNo
CC 240 seconden240 seconds JaYes
C#C# 300 seconden300 seconds JaYes
Python (v2)Python (V2) 60 seconden60 seconds NeeNo

De volgende MQTT-specificatie, het Keep-Alive ping-interval van IoT Hub is 1,5 keer de client Keep-Alive-waarde.Following MQTT spec, IoT Hub's keep-alive ping interval is 1.5 times the client keep-alive value. IoT Hub beperkt echter de maximale time-out aan de server zijde tot 29,45 minuten (1767 seconden), omdat alle Azure-Services zijn gebonden aan de Azure load balancer TCP-time-out voor inactiviteit, 29,45 minuten.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.

Bijvoorbeeld: een apparaat dat de Java-SDK gebruikt, verzendt de Keep-Alive ping, waarna de netwerk verbinding wordt verbroken.For example, a device using the Java SDK sends the keep-alive ping then loses network connectivity. 230 seconden later is het apparaat de Keep-Alive ping missen omdat het offline is.230 seconds later, the device misses the keep-alive ping because it's offline. IoT Hub de verbinding echter niet onmiddellijk sluit, wacht u nog een (230 * 1.5) - 230 = 115 paar seconden voordat u de verbinding met het apparaat verbreekt met de fout 404104 DeviceConnectionClosedRemotely.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.

De maximale client Keep-Alive-waarde die u kunt instellen is 1767 / 1.5 = 1177 seconden.The maximum client keep-alive value you can set is 1767 / 1.5 = 1177 seconds. Elk verkeer stelt de Keep-Alive opnieuw in.Any traffic will reset the keep-alive. Bijvoorbeeld: een geslaagde SAS-token vernieuwing stelt de Keep-Alive opnieuw in.For example, a successful SAS token refresh resets the keep-alive.

Een apparaat-app migreren van AMQP naar MQTTMigrating a device app from AMQP to MQTT

Als u de apparaat- sdk'sgebruikt, moet u bij het overschakelen van het gebruik van AMQP naar MQTT de para meter protocol in de initialisatie van de client wijzigen zoals eerder is aangegeven.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.

Zorg er daarom voor dat u de volgende items controleert:When doing so, make sure to check the following items:

  • AMQP retourneert fouten voor veel omstandigheden, terwijl MQTT de verbinding beëindigt.AMQP returns errors for many conditions, while MQTT terminates the connection. Als gevolg hiervan kan de logica voor het afhandelen van uitzonde ringen enkele wijzigingen vereisen.As a result your exception handling logic might require some changes.

  • MQTT biedt geen ondersteuning voor de afwijzings bewerkingen wanneer er Cloud-naar-apparaat-berichten wordenontvangen.MQTT does not support the reject operations when receiving cloud-to-device messages. Als uw back-end-app een reactie van de apparaat-app moet ontvangen, overweeg dan om directe methodente gebruiken.If your back-end app needs to receive a response from the device app, consider using direct methods.

  • AMQP wordt niet ondersteund in de python-SDKAMQP is not supported in the Python SDK

Het MQTT-protocol direct gebruiken (als een apparaat)Using the MQTT protocol directly (as a device)

Als een apparaat de Sdk's van het apparaat niet kan gebruiken, kan het nog steeds verbinding maken met de eind punten van het open bare apparaat met behulp van het MQTT-protocol op poort 8883.If a device cannot use the device SDKs, it can still connect to the public device endpoints using the MQTT protocol on port 8883. In het Connect -pakket moet het apparaat de volgende waarden gebruiken:In the CONNECT packet, the device should use the following values:

  • Gebruik voor het veld ClientId het apparaat-id.For the ClientId field, use the deviceId.

  • Voor het veld username gebruikt u {iothubhostname}/{device_id}/?api-version=2018-06-30 , waarbij {iothubhostname} de volledige CNAME is van de IOT-hub.For the Username field, use {iothubhostname}/{device_id}/?api-version=2018-06-30, where {iothubhostname} is the full CName of the IoT hub.

    Als de naam van uw IoT-hub bijvoorbeeld contoso.Azure-devices.net is en als de naam van uw apparaat MyDevice01is, moet het veld volledige gebruikers naam het volgende bevatten: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

  • Gebruik voor het wachtwoord veld een SAS-token.For the Password field, use a SAS token. De indeling van de SAS-token is hetzelfde als voor de HTTPS-en AMQP-protocollen: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}

    Notitie

    Als u X. 509-certificaat authenticatie gebruikt, zijn SAS-token wachtwoorden niet vereist.If you use X.509 certificate authentication, SAS token passwords are not required. Zie voor meer informatie instellen van X. 509-beveiliging in uw Azure IOT hub en volg de onderstaandecode instructies.For more information, see Set up X.509 security in your Azure IoT Hub and follow code instructions below.

    Zie voor meer informatie over het genereren van SAS-tokens het gedeelte apparaat van het gebruik van IOT hub beveiligings tokens.For more information about how to generate SAS tokens, see the device section of Using IoT Hub security tokens.

    Bij het testen kunt u ook de platformoverschrijdende Azure IOT-Hulpprogram ma's voor Visual Studio code of de CLI-extensie opdracht AZ IOT hub generate-SAS-token gebruiken om snel een SAS-token te genereren dat u kunt kopiëren en plakken in uw eigen code: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:

Voor Azure IoT-Hulpprogram Ma'sFor Azure IoT Tools

  1. Vouw het tabblad apparaten van Azure IOT hub uit in de linkerbovenhoek van Visual Studio code.Expand the AZURE IOT HUB DEVICES tab in the bottom left corner of Visual Studio Code.

  2. Klik met de rechter muisknop op uw apparaat en selecteer SAS-token voor apparaat genereren.Right-click your device and select Generate SAS Token for Device.

  3. Stel de verval tijd in en druk op ENTER.Set expiration time and press 'Enter'.

  4. Het SAS-token wordt gemaakt en naar het klem bord gekopieerd.The SAS token is created and copied to clipboard.

    Het SAS-token dat wordt gegenereerd, heeft de volgende structuur: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

    Het deel van dit token dat moet worden gebruikt als het wachtwoord veld om verbinding te maken met MQTT is: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

Voor MQTT Connect-en Disconnect-pakketten IoT Hub een gebeurtenis op het kanaal van de Operations-bewaking .For MQTT connect and disconnect packets, IoT Hub issues an event on the Operations Monitoring channel. Deze gebeurtenis bevat aanvullende informatie die u kan helpen bij het oplossen van verbindings problemen.This event has additional information that can help you to troubleshoot connectivity issues.

De apparaat-app kan een bericht in het Connect -pakket opgeven.The device app can specify a Will message in the CONNECT packet. De app van het apparaat moet de naam van het devices/{device_id}/messages/events/ devices/{device_id}/messages/events/{property_bag} onderwerp gebruiken om Will te definiëren dat berichten worden doorgestuurd als een telemetrie-bericht. WillThe 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. Als de netwerk verbinding is gesloten, maar er nog geen Verbrekings pakket van het apparaat is ontvangen, stuurt IOT hub het bericht dat in het Connect -pakket is opgegeven, naar het telemetrie-kanaal.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. Het telemetrie-kanaal kan het eind punt van de standaard gebeurtenissen zijn of een aangepast eind punt dat is gedefinieerd door IOT hub route ring.The telemetry channel can be either the default Events endpoint or a custom endpoint defined by IoT Hub routing. Aan het bericht is de eigenschap iothub-Message type met de waarde van toegewezen .The message has the iothub-MessageType property with a value of Will assigned to it.

Een voor beeld van een C-code met behulp van MQTT zonder Azure IoT C SDKAn example of C code using MQTT without Azure IoT C SDK

In deze opslag plaatsvindt u een aantal C/C++-demo projecten die laten zien hoe u telemetrie-berichten verzendt, gebeurtenissen ontvangt met een IOT-hub zonder de Azure IOT C SDK te gebruiken.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 deze voor beelden wordt de Mosquitto-bibliotheek van de eclips gebruikt om een bericht te verzenden naar de MQTT-Broker die in de IoT hub is geïmplementeerd.These samples use the Eclipse Mosquitto library to send message to the MQTT Broker implemented in the IoT hub.

Deze opslag plaats bevat:This repository contains:

Voor Windows:For Windows:

  • TelemetryMQTTWin32: bevat code voor het verzenden van een telemetrie-bericht naar een Azure IoT hub, gebouwd en uitgevoerd op een Windows-computer.TelemetryMQTTWin32: contains code to send a telemetry message to an Azure IoT hub, built and run on a Windows machine.

  • SubscribeMQTTWin32: bevat code voor het abonneren op gebeurtenissen van een bepaalde IoT-hub op een Windows-computer.SubscribeMQTTWin32: contains code to subscribe to events of a given IoT hub on a Windows machine.

  • DeviceTwinMQTTWin32: bevat code voor het zoeken naar en abonneren op de dubbele gebeurtenissen van een apparaat in de Azure IoT hub op een 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: bevat code voor het verzenden van een telemetrie-bericht met IoT plug & Play preview-mogelijkheden voor apparaten naar een Azure IoT hub, gebouwd en uitgevoerd op een Windows-computer.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. Meer informatie over IoT plug & hier afspelenMore on IoT Plug & Play here

Voor Linux:For Linux:

  • MQTTLinux: bevat code en bouw script voor uitvoering op Linux (WSL, Ubuntu en Raspbian zijn tot nu toe getest).MQTTLinux: contains code and build script to run on Linux (WSL, Ubuntu, and Raspbian have been tested so far).

  • LinuxConsoleVS2019: bevat dezelfde code, maar in een VS2019-project gericht WSL (Windows Linux-subsysteem).LinuxConsoleVS2019: contains the same code but in a VS2019 project targeting WSL (Windows Linux sub system). Met dit project kunt u fouten opsporen in de code die wordt uitgevoerd in Linux stap voor stap van Visual Studio.This project allows you to debug the code running on Linux step by step from Visual Studio.

Voor mosquitto_pub:For mosquitto_pub:

Deze map bevat twee voor beelden van opdrachten die worden gebruikt met mosquitto_pub hulp programma van Mosquitto.org.This folder contains two samples commands used with mosquitto_pub utility tool provided by Mosquitto.org.

  • Mosquitto_sendmessage: een eenvoudig tekst bericht verzenden naar een Azure IoT hub die fungeert als een apparaat.Mosquitto_sendmessage: to send a simple text message to an Azure IoT hub acting as a device.

  • Mosquitto_subscribe: om gebeurtenissen weer te geven die in een Azure IoT-hub optreden.Mosquitto_subscribe: to see events occurring in an Azure IoT hub.

Het MQTT-protocol direct gebruiken (als een module)Using the MQTT protocol directly (as a module)

Verbinding maken met IoT Hub via MQTT via een module-identiteit is vergelijkbaar met het apparaat ( hierbovenbeschreven), maar u moet het volgende gebruiken:Connecting to IoT Hub over MQTT using a module identity is similar to the device (described above) but you need to use the following:

  • Stel de client-ID in op {device_id}/{module_id} .Set the client ID to {device_id}/{module_id}.

  • Als verificatie met gebruikers naam en wacht woord, stelt u de gebruikers naam in op <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2018-06-30 en gebruikt u het SAS-token dat is gekoppeld aan de module identiteit als uw wacht woord.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.

  • Gebruiken devices/{device_id}/modules/{module_id}/messages/events/ als onderwerp voor het publiceren van telemetrie.Use devices/{device_id}/modules/{module_id}/messages/events/ as topic for publishing telemetry.

  • Gebruik devices/{device_id}/modules/{module_id}/messages/events/ als onderwerp.Use devices/{device_id}/modules/{module_id}/messages/events/ as WILL topic.

  • De dubbele GET-en PATCH-onderwerpen zijn identiek voor modules en apparaten.The twin GET and PATCH topics are identical for modules and devices.

  • Het onderwerp dubbele status is identiek voor modules en apparaten.The twin status topic is identical for modules and devices.

TLS/SSL-configuratieTLS/SSL configuration

Als u het MQTT-protocol direct wilt gebruiken, moet de client verbinding maken via TLS/SSL.To use the MQTT protocol directly, your client must connect over TLS/SSL. Pogingen om deze stap over te slaan mislukken met verbindings fouten.Attempts to skip this step fail with connection errors.

Als u een TLS-verbinding wilt maken, moet u mogelijk het DigiCert Baltimore-basis certificaat downloaden en hiernaar verwijzen.In order to establish a TLS connection, you may need to download and reference the DigiCert Baltimore Root Certificate. Dit certificaat is de versie die door Azure wordt gebruikt om de verbinding te beveiligen.This certificate is the one that Azure uses to secure the connection. U kunt dit certificaat vinden in de Azure-IOT-SDK-c- opslag plaats.You can find this certificate in the Azure-iot-sdk-c repository. Meer informatie over deze certificaten vindt u op de website van Digicert.More information about these certificates can be found on Digicert's website.

Een voor beeld van hoe u dit kunt implementeren met behulp van de python-versie van de PAHO MQTT-bibliotheek van de eclips-basis, kan er als volgt uitzien.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.

Installeer eerst de PAHO-bibliotheek vanaf uw opdracht regel omgeving:First, install the Paho library from your command-line environment:

pip install paho-mqtt

Implementeer vervolgens de client in een python-script.Then, implement the client in a Python script. Vervang de tijdelijke aanduidingen als volgt:Replace the placeholders as follows:

  • <local path to digicert.cer>is het pad naar een lokaal bestand dat het DigiCert Baltimore-basis certificaat bevat.<local path to digicert.cer> is the path to a local file that contains the DigiCert Baltimore Root certificate. U kunt dit bestand maken door de certificaat gegevens te kopiëren van certificaten. c in de Azure IOT SDK voor c. Voeg de regels toe -----BEGIN CERTIFICATE----- en -----END CERTIFICATE----- Verwijder de " markeringen aan het begin en het einde van elke regel, en verwijder de \r\n tekens aan het einde van elke regel.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>is de ID van een apparaat dat u hebt toegevoegd aan uw IoT-hub.<device id from device registry> is the ID of a device you added to your IoT hub.

  • <generated SAS token>is een SAS-token voor het apparaat dat is gemaakt zoals eerder in dit artikel is beschreven.<generated SAS token> is a SAS token for the device created as described previously in this article.

  • <iot hub name>de naam van uw IoT-hub.<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()

Als u wilt verifiëren met behulp van een certificaat voor een apparaat, werkt u het code fragment hierboven bij met de volgende wijzigingen (Zie een X. 509 CA-certificaat verkrijgen over het voorbereiden op verificatie op basis van een certificaat):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)

Apparaat-naar-Cloud-berichten verzendenSending device-to-cloud messages

Na een geslaagde verbinding kan een apparaat berichten verzenden naar IoT Hub met devices/{device_id}/messages/events/ of devices/{device_id}/messages/events/{property_bag} als onderwerpnaam.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. Met het- {property_bag} element kan het apparaat berichten verzenden met aanvullende eigenschappen in een indeling met URL-code ring.The {property_bag} element enables the device to send messages with additional properties in a url-encoded format. Bijvoorbeeld:For example:

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

Notitie

Dit {property_bag} element maakt gebruik van dezelfde code ring als query reeksen in het HTTPS-protocol.This {property_bag} element uses the same encoding as query strings in the HTTPS protocol.

Hier volgt een lijst met IoT Hub implementatie-specifieke gedragingen:The following is a list of IoT Hub implementation-specific behaviors:

  • IoT Hub biedt geen ondersteuning voor QoS 2-berichten.IoT Hub does not support QoS 2 messages. Als een apparaat-app een bericht publiceert met QoS 2, wordt de netwerk verbinding IOT hub gesloten.If a device app publishes a message with QoS 2, IoT Hub closes the network connection.

  • IoT Hub blijven geen berichten behouden.IoT Hub does not persist Retain messages. Als een apparaat een bericht verzendt waarbij de vlag bewaren is ingesteld op 1, IOT hub voegt de eigenschap x-opt-retain- toepassing toe aan het bericht.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 dit geval wordt in plaats van het behouden bericht te blijven IoT Hub door gegeven aan de back-end-app.In this case, instead of persisting the retain message, IoT Hub passes it to the backend app.

  • IoT Hub ondersteunt slechts één actieve MQTT-verbinding per apparaat.IoT Hub only supports one active MQTT connection per device. Een nieuwe MQTT-verbinding namens dezelfde apparaat-ID leidt ertoe IoT Hub de bestaande verbinding te verwijderen.Any new MQTT connection on behalf of the same device ID causes IoT Hub to drop the existing connection.

Zie voor meer informatie de hand leiding voor SMS-ontwikkel aars.For more information, see Messaging developer's guide.

Cloud-naar-apparaat-berichten ontvangenReceiving cloud-to-device messages

Als u berichten van IoT Hub wilt ontvangen, moet een apparaat zich abonneren met devices/{device_id}/messages/devicebound/# als een onderwerps filter.To receive messages from IoT Hub, a device should subscribe using devices/{device_id}/messages/devicebound/# as a Topic Filter. Het Joker teken op meerdere niveaus # in het onderwerps filter wordt alleen gebruikt om het apparaat in staat te stellen extra eigenschappen in de onderwerpnaam te ontvangen.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 staat het gebruik van de of- # ? joker tekens voor het filteren van subonderwerpen niet toe.IoT Hub does not allow the usage of the # or ? wildcards for filtering of subtopics. Omdat IoT Hub geen pub-submessa ging Broker voor algemeen gebruik is, worden alleen de gedocumenteerde onderwerps namen en onderwerps filters ondersteund.Since IoT Hub is not a general-purpose pub-sub messaging broker, it only supports the documented topic names and topic filters.

Het apparaat ontvangt geen berichten van IoT Hub, totdat het is geabonneerd op het apparaat-specifieke eind punt dat wordt vertegenwoordigd door het devices/{device_id}/messages/devicebound/# onderwerps filter.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. Nadat een abonnement is ingesteld, ontvangt het apparaat Cloud-naar-apparaat-berichten die zijn verzonden na het tijdstip van het abonnement.After a subscription has been established, the device receives cloud-to-device messages that were sent to it after the time of the subscription. Als het apparaat verbinding maakt met de vlag CleanSession ingesteld op 0, wordt het abonnement gehandhaafd in verschillende sessies.If the device connects with CleanSession flag set to 0, the subscription is persisted across different sessions. In dit geval wordt de volgende keer dat het apparaat verbinding maakt met CleanSession 0 alle openstaande berichten ontvangen die worden verzonden terwijl de verbinding is verbroken.In this case, the next time the device connects with CleanSession 0 it receives any outstanding messages sent to it while disconnected. Als het apparaat gebruikmaakt van een CleanSession -vlag ingesteld op 1 , worden er geen berichten van IOT hub ontvangen totdat deze zich op het eind punt van het apparaat abonneert.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 levert berichten met de onderwerpnaam devices/{device_id}/messages/devicebound/ of devices/{device_id}/messages/devicebound/{property_bag} wanneer er bericht eigenschappen zijn.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}bevat URL-gecodeerde sleutel/waarde-paren van bericht eigenschappen.{property_bag} contains url-encoded key/value pairs of message properties. Alleen toepassings eigenschappen en door de gebruiker instel bare systeem eigenschappen (zoals messageId of correlationId) worden opgenomen in de eigenschappen verzameling.Only application properties and user-settable system properties (such as messageId or correlationId) are included in the property bag. De namen van systeem eigenschappen hebben het voor voegsel $ , toepassings eigenschappen gebruiken de oorspronkelijke eigenschaps naam zonder voor voegsel.System property names have the prefix $, application properties use the original property name with no prefix.

Wanneer een apparaat-app zich abonneert op een onderwerp met QoS 2, geeft IOT hub Maxi maal QoS-niveau 1 in het SUBACK -pakket.When a device app subscribes to a topic with QoS 2, IoT Hub grants maximum QoS level 1 in the SUBACK packet. Daarna levert IoT Hub berichten naar het apparaat met behulp van QoS 1.After that, IoT Hub delivers messages to the device using QoS 1.

De eigenschappen van een onderliggend apparaat ophalenRetrieving a device twin's properties

Eerst wordt een apparaat geabonneerd op om $iothub/twin/res/# de reacties van de bewerking te ontvangen.First, a device subscribes to $iothub/twin/res/#, to receive the operation's responses. Vervolgens wordt er een leeg bericht naar het onderwerp verzonden $iothub/twin/GET/?$rid={request id} met een ingevuld waarde voor aanvraag-id.Then, it sends an empty message to topic $iothub/twin/GET/?$rid={request id}, with a populated value for request ID. De service verzendt vervolgens een antwoord bericht met daarin het apparaat dubbele gegevens over $iothub/twin/res/{status}/?$rid={request id} het onderwerp, waarbij dezelfde aanvraag-id wordt gebruikt als voor de aanvraag.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.

De aanvraag-ID kan bestaan uit een geldige waarde voor de waarde van een bericht eigenschap, conform de IOT hub Messa ging-ontwikkelaars gidsen de status wordt gevalideerd als een geheel getal.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.

De hoofd tekst van het antwoord bevat de sectie eigenschappen van het apparaat, zoals wordt weer gegeven in het volgende voor beeld van een antwoord: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
    }
}

De mogelijke status codes zijn:The possible status codes are:

StatusStatus BeschrijvingDescription
200200 GeslaagdSuccess
429429 Te veel aanvragen (beperkt), conform IOT hub beperkingToo many requests (throttled), as per IoT Hub throttling
5 * *5** ServerfoutenServer errors

Zie de ontwikkelaars handleiding voor Device apparaatdubbelsvoor meer informatie.For more information, see Device twins developer's guide.

De gerapporteerde eigenschappen van het apparaat bijwerkenUpdate device twin's reported properties

Voor het bijwerken van de gerapporteerde eigenschappen geeft het apparaat een verzoek om IoT Hub via een publicatie in een aangewezen MQTT-onderwerp.To update reported properties, the device issues a request to IoT Hub via a publication over a designated MQTT topic. Nadat de aanvraag is verwerkt, reageert IoT Hub de geslaagde of mislukte status van de update bewerking via een publicatie naar een ander onderwerp.After processing the request, IoT Hub responds the success or failure status of the update operation via a publication to another topic. Dit onderwerp kan worden geabonneerd op het apparaat, zodat het kan worden gewaarschuwd over het resultaat van de dubbele update aanvraag.This topic can be subscribed by the device in order to notify it about the result of its twin update request. Voor het implementeren van dit type aanvraag/antwoord interactie in MQTT maken we gebruik van het principe van de aanvraag-ID ( $rid ) die in eerste instantie door het apparaat wordt gegeven in de update-aanvraag.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. Deze aanvraag-ID is ook opgenomen in de reactie van IoT Hub, zodat het apparaat de reactie op de specifieke eerdere aanvraag kan correleren.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.

In de volgende reeks wordt beschreven hoe een apparaat de gerapporteerde eigenschappen bijwerkt in het apparaat dubbele in IoT Hub:The following sequence describes how a device updates the reported properties in the device twin in IoT Hub:

  1. Een apparaat moet eerst worden geabonneerd op het $iothub/twin/res/# onderwerp om de reacties van de bewerking van IOT hub te ontvangen.A device must first subscribe to the $iothub/twin/res/# topic to receive the operation's responses from IoT Hub.

  2. Een apparaat verzendt een bericht dat de dubbele update van het apparaat naar het $iothub/twin/PATCH/properties/reported/?$rid={request id} onderwerp bevat.A device sends a message that contains the device twin update to the $iothub/twin/PATCH/properties/reported/?$rid={request id} topic. Dit bericht bevat een aanvraag-ID- waarde.This message includes a request ID value.

  3. De service verzendt vervolgens een antwoord bericht met daarin de nieuwe ETag-waarde voor de gerapporteerde eigenschappen verzameling in het onderwerp $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}. Dit antwoord bericht gebruikt dezelfde aanvraag-id als de aanvraag.This response message uses the same request ID as the request.

De hoofd tekst van het aanvraag bericht bevat een JSON-document dat nieuwe waarden voor gerapporteerde eigenschappen bevat.The request message body contains a JSON document, that contains new values for reported properties. Elk lid in het JSON-document of voegt het overeenkomstige lid toe aan het document van het dubbele apparaat.Each member in the JSON document updates or add the corresponding member in the device twin's document. Een lid ingesteld op null , verwijdert het lid van het container object.A member set to null, deletes the member from the containing object. Bijvoorbeeld:For example:

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

De mogelijke status codes zijn:The possible status codes are:

StatusStatus BeschrijvingDescription
204204 Geslaagd (er is geen inhoud geretourneerd)Success (no content is returned)
400400 Ongeldige aanvraag.Bad Request. Onjuist gevormde JSONMalformed JSON
429429 Te veel aanvragen (beperkt), conform IOT hub beperkingToo many requests (throttled), as per IoT Hub throttling
5 * *5** ServerfoutenServer errors

In het onderstaande code fragment python ziet u het dubbele gerapporteerde eigenschappen update proces via MQTT (met behulp van PAHO MQTT-client):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)

Bij het slagen van dubbele gerapporteerde update-bewerking hierboven heeft het publicatie bericht van IoT Hub het volgende onderwerp: $iothub/twin/res/204/?$rid=1&$version=6 , waarbij 204 de status code aangeeft dat geslaagd is, $rid=1 overeenkomt met de aanvraag-id die is opgegeven door het apparaat in de code en $version overeenkomt met de versie van de sectie gerapporteerde eigenschappen van Device apparaatdubbels na de update.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.

Zie de ontwikkelaars handleiding voor Device apparaatdubbelsvoor meer informatie.For more information, see Device twins developer's guide.

Meldingen voor gewenste eigenschappen van updates ontvangenReceiving desired properties update notifications

Wanneer een apparaat is verbonden, stuurt IoT Hub meldingen naar het onderwerp $iothub/twin/PATCH/properties/desired/?$version={new version} , dat de inhoud bevat van de update die is uitgevoerd door de back-end van de oplossing.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. Bijvoorbeeld:For example:

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

Als voor updates van eigenschappen, null betekenen waarden dat het lid van het JSON-object wordt verwijderd.As for property updates, null values mean that the JSON object member is being deleted. Houd er ook rekening mee dat $version de nieuwe versie van het gedeelte gewenste eigenschappen van de dubbele.Also, note that $version indicates the new version of the desired properties section of the twin.

Belangrijk

IoT Hub genereert alleen wijzigings meldingen wanneer apparaten zijn verbonden.IoT Hub generates change notifications only when devices are connected. Zorg ervoor dat u de stroom voor het opnieuw verbinden van apparaten implementeert om ervoor te zorgen dat de gewenste eigenschappen gesynchroniseerd worden tussen IOT hub en de apparaat-app.Make sure to implement the device reconnection flow to keep the desired properties synchronized between IoT Hub and the device app.

Zie de ontwikkelaars handleiding voor Device apparaatdubbelsvoor meer informatie.For more information, see Device twins developer's guide.

Reageren op een directe methodeRespond to a direct method

Eerst moet een apparaat zich abonneren op $iothub/methods/POST/# .First, a device has to subscribe to $iothub/methods/POST/#. IoT Hub verzendt methode aanvragen naar het onderwerp $iothub/methods/POST/{method name}/?$rid={request id} met een geldige JSON of een lege hoofd tekst.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.

Om te reageren, stuurt het apparaat een bericht met een geldige JSON of lege hoofd tekst naar het onderwerp $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 dit bericht moet de aanvraag-id overeenkomen met het account in het aanvraag bericht en moet de status een geheel getal zijn.In this message, the request ID must match the one in the request message, and status must be an integer.

Zie directe methode hand leiding voor ontwikkel aarsvoor meer informatie.For more information, see Direct method developer's guide.

Aanvullende overwegingenAdditional considerations

Als laatste overweging: als u het MQTT-protocol gedrag aan de Cloud zijde moet aanpassen, moet u de Azure IOT-protocol gatewaydoor nemen.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. Met deze software kunt u een aangepaste protocol gateway met hoge prestaties implementeren die rechtstreeks is verbonden met IoT Hub.This software enables you to deploy a high-performance custom protocol gateway that interfaces directly with IoT Hub. Met de Azure IoT-protocol gateway kunt u het Protocol van het apparaat aanpassen om Brownfield MQTT-implementaties of andere aangepaste protocollen aan te passen.The Azure IoT protocol gateway enables you to customize the device protocol to accommodate brownfield MQTT deployments or other custom protocols. Deze benadering vereist echter dat u een aangepaste protocol gateway uitvoert en gebruikt.This approach does require, however, that you run and operate a custom protocol gateway.

Volgende stappenNext steps

Zie de MQTT-documentatievoor meer informatie over het MQTT-protocol.To learn more about the MQTT protocol, see the MQTT documentation.

Zie voor meer informatie over het plannen van uw IoT Hub-implementatie:To learn more about planning your IoT Hub deployment, see:

Zie voor meer informatie over de mogelijkheden van IoT Hub:To further explore the capabilities of IoT Hub, see: