Communiceren met een IoT-hub met behulp van het MQTT-protocol

Artikel
11/15/2023

In dit artikel wordt beschreven hoe apparaten ondersteunde MQTT-gedrag kunnen gebruiken om te communiceren met Azure IoT Hub. Met IoT Hub kunnen apparaten communiceren met de IoT Hub-apparaateindpunten met behulp van:

MQTT v3.1.1 op TCP-poort 8883
MQTT v3.1.1 via WebSocket op TCP-poort 443.

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. Zie De juiste IoT Hub-laag voor uw oplossing kiezen voor meer informatie over de Basic- en Standard-/gratis IoT Hub-lagen.

Alle apparaatcommunicatie met IoT Hub moet worden beveiligd met BEHULP van TLS/SSL. Daarom biedt IoT Hub geen ondersteuning voor onbeveiligde verbindingen via TCP-poort 1883.

MQTT-ondersteuning vergelijken in IoT Hub en Event Grid

IoT Hub is geen volledige MQTT-broker en biedt geen ondersteuning voor alle gedragingen die zijn opgegeven in de MQTT v3.1.1-standaard. Als uw oplossing MQTT nodig heeft, raden we MQTT-ondersteuning aan in Azure Event Grid. Event Grid maakt bidirectionele communicatie tussen MQTT-clients mogelijk voor flexibele hiërarchische onderwerpen met behulp van een pub-sub messaging-model. Hiermee kunt u MQTT-berichten ook routeren naar Azure-services of aangepaste eindpunten voor verdere verwerking.

In de volgende tabel worden de verschillen in MQTT-ondersteuning tussen de twee services uitgelegd:

IoT Hub	Event Grid
Client-servermodel met nauwe koppeling tussen apparaten en cloud-apps.	Publish-subscribe model waarmee uitgevers en abonnees worden losgekoppeld.
Beperkte functieondersteuning voor MQTT v3.1.1 en beperkte functieondersteuning voor MQTT v5 in preview. Er is geen ondersteuning voor meer functies gepland.	MQTT v3.1.1- en v5-protocolondersteuning, met meer functieondersteuning en branchenaleving gepland.
Statische, vooraf gedefinieerde onderwerpen.	Aangepaste hiërarchische onderwerpen met ondersteuning voor jokertekens.
Geen ondersteuning voor cloud-naar-apparaat-broadcasts en apparaat-naar-apparaat-communicatie.	Biedt ondersteuning voor apparaat-naar-cloud- en high-out cloud-naar-apparaat-broadcasts en apparaat-naar-apparaat-communicatiepatronen.
Maximale berichtgrootte van 256 kB.	Maximale berichtgrootte van 512 kB.

Verbinding maken met 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:

De Azure IoT SDK's.
Het MQTT-protocol rechtstreeks.

De MQTT-poort (TCP-poort 8883) wordt geblokkeerd in veel bedrijfs- en onderwijsnetwerkomgevingen. Als u poort 8883 niet kunt openen in uw firewall, raden we u aan MQTT te gebruiken via WebSockets. MQTT via WebSockets communiceert via poort 443, dat bijna altijd open is in netwerkomgevingen. Zie De APPARAAT-SDK's gebruiken voor meer informatie over het opgeven van de MQTT- en MQTT-protocollen via WebSockets-protocollen wanneer u de Azure IoT SDK's gebruikt.

De apparaat-SDK's gebruiken

Apparaat-SDK's die ondersteuning bieden voor het MQTT-protocol zijn beschikbaar voor Java, Node.js, C, C# en Python. De apparaat-SDK's gebruiken het gekozen verificatiemechanisme om een verbinding met een IoT-hub tot stand te brengen. Als u het MQTT-protocol wilt gebruiken, moet de parameter van het clientprotocol worden ingesteld op MQTT. U kunt MQTT ook opgeven via WebSockets in de parameter van het clientprotocol. De APPARAAT-SDK's maken standaard verbinding met een IoT Hub met de vlag CleanSession ingesteld op 0 en gebruiken QoS 1 voor berichtuitwisseling met de IoT-hub. Hoewel het mogelijk is om QoS 0 te configureren voor snellere berichtuitwisseling, moet u er rekening mee houden dat de bezorging niet gegarandeerd of bevestigd is. Om deze reden wordt QoS 0 vaak aangeduid als 'vuur en vergeet'.

Wanneer een apparaat is verbonden met een IoT-hub, bieden de apparaat-SDK's methoden waarmee het apparaat berichten kan uitwisselen met een IoT-hub.

De volgende tabel bevat koppelingen naar codevoorbeelden voor elke ondersteunde taal en geeft de parameter op die moet worden gebruikt om een verbinding met IoT Hub tot stand te brengen met behulp van de MQTT of het MQTT via WebSockets-protocol.

Taal	MQTT-protocolparameter	MQTT via WebSockets-protocolparameter
Node.js	azure-iot-device-mqtt. Mqtt	azure-iot-device-mqtt. MqttWs
Java	IotHubClientProtocol. MQTT	IotHubClientProtocol.MQTT_WS
C	MQTT_Protocol	MQTT_WebSocket_Protocol
C#	TransportType. Mqtt	TransportType.Mqtt valt terug op MQTT via WebSockets als MQTT mislukt. Als u alleen MQTT via WebSockets wilt opgeven, gebruikt u TransportType.Mqtt_WebSocket_Only
Python	Biedt standaard ondersteuning voor MQTT	De aanroep toevoegen `websockets=True` om de client te maken

In het volgende fragment ziet u hoe u het MQTT-protocol via WebSockets opgeeft wanneer u de Azure IoT Node.js SDK gebruikt:

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

In het volgende fragment ziet u hoe u het MQTT-protocol via WebSockets opgeeft wanneer u de Azure IoT Python SDK gebruikt:

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

Belangrijk

Dit artikel bevat stappen voor het verbinden van een apparaat met behulp van een Shared Access Signature, ook wel symmetrische sleutelverificatie genoemd. Deze verificatiemethode is handig voor testen en evalueren, maar het verifiëren van een apparaat met X.509-certificaten is een veiligere benadering. Zie Best practices > voor beveiliging voor verbindingsbeveiliging voor meer informatie.

Standaard time-out voor keep-alive

Om ervoor te zorgen dat een client-/IoT Hub-verbinding actief blijft, verzenden zowel de service als de client regelmatig een keep-alive-ping naar elkaar. De client die IoT SDK gebruikt, verzendt een keep-alive met het interval dat is gedefinieerd in de volgende tabel:

Taal	Standaard interval voor keep-alive	Configureerbaar
Node.js	180 seconden	Nee
Java	230 seconden	Ja
E	240 seconden	Ja
C#	300 seconden*	Ja
Python	60 seconden	Ja

*De C#-SDK definieert de standaardwaarde van de eigenschap MQTT KeepAliveInSeconds als 300 seconden. In werkelijkheid verzendt de SDK een pingaanvraag vier keer per set duur van keep alive. Met andere woorden, de SDK verzendt elke 75 seconden een keep-alive ping.

Na de MQTT v3.1.1-specificatie is het interval voor keep-alive-ping van IoT Hub 1,5 keer de waarde voor keep-alive van de client. IoT Hub beperkt echter de maximale time-out aan de serverzijde tot 29,45 minuten (1767 seconden). Deze limiet bestaat omdat alle Azure-services zijn gebonden aan de time-out bij inactiviteit van Azure load balancer TCP. Dit is 29,45 minuten.

Een apparaat met de Java SDK verzendt bijvoorbeeld de keep-alive ping en verliest vervolgens de netwerkverbinding. 230 seconden later mist het apparaat de keep-alive-ping omdat het offline is. IoT Hub sluit de verbinding echter niet onmiddellijk. Er wordt nog een (230 * 1.5) - 230 = 115 paar seconden gewacht voordat de verbinding met het apparaat wordt verbroken met de fout 404104 DeviceConnectionClosedRemotely.

De maximale keep-alive-waarde van de client die u kunt instellen, is 1767 / 1.5 = 1177 seconden. Elk verkeer stelt de keep-alive opnieuw in. Als een SAS-token (Shared Access Signature) bijvoorbeeld is vernieuwd, wordt de keep-alive opnieuw ingesteld.

Een apparaat-app migreren van AMQP naar MQTT

Als u de apparaat-SDK's gebruikt, moet u overschakelen van AMQP naar MQTT om de protocolparameter in de client initialisatie te wijzigen, zoals eerder vermeld.

Als u dit doet, controleert u de volgende items:

AMQP retourneert fouten voor veel voorwaarden, terwijl MQTT de verbinding beëindigt. Als gevolg hiervan kan uw logica voor het afhandelen van uitzonderingen enkele wijzigingen vereisen.
MQTT biedt geen ondersteuning voor weigeringsbewerkingen bij het ontvangen van cloud-naar-apparaat-berichten. Als uw back-end-app een antwoord van de apparaat-app moet ontvangen, kunt u overwegen om directe methoden te gebruiken.
AMQP wordt niet ondersteund in de Python SDK.

Het MQTT-protocol rechtstreeks gebruiken (als apparaat)

Als een apparaat de APPARAAT-SDK's niet kan gebruiken, kan het nog steeds verbinding maken met de eindpunten van het openbare apparaat met behulp van het MQTT-protocol op poort 8883.

In het CONNECT-pakket moet het apparaat de volgende waarden gebruiken:

Gebruik de deviceId voor het veld ClientId.
Voor het veld Gebruikersnaam gebruikt {iotHub-hostname}/{device-id}/?api-version=2021-04-12u , waar {iotHub-hostname} bevindt zich de volledige CName IoT-hub.

Als de naam van uw IoT-hub bijvoorbeeld is contoso.azure-devices.net en als de naam van uw apparaat MyDevice01 is, moet het volledige veld Gebruikersnaam het volgende bevatten:

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

Het is raadzaam om api-versie in het veld op te nemen. Anders kan dit onverwacht gedrag veroorzaken.
Gebruik een SAS-token voor het veld Wachtwoord . De indeling van het SAS-token is hetzelfde als voor de HTTPS- en AMQP-protocollen:

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

Notitie

Als u X.509-certificaatverificatie gebruikt, zijn SAS-tokenwachtwoorden niet vereist. Zie Zelfstudie: Certificaten maken en uploaden voor het testen en volgen van code-instructies in de sectie TLS/SSL-configuratie voor meer informatie.

Zie voor meer informatie over het genereren van SAS-tokens de sectie SAS-tokens gebruiken als een apparaatsectie van toegang tot IoT Hub met behulp van Shared Access Signatures.

U kunt ook de platformoverschrijdende Azure IoT Hub-extensie voor Visual Studio Code of de CLI-extensieopdracht az iot hub generate-sas-token gebruiken om snel een SAS-token te genereren. Vervolgens kunt u het SAS-token kopiëren en plakken in uw eigen code voor testdoeleinden.

Zie MQTT gebruiken om een IoT-apparaatclient te ontwikkelen zonder een apparaat-SDK te gebruiken voor een zelfstudie over het rechtstreeks gebruiken van MQTT.

De Azure IoT Hub-extensie voor Visual Studio Code gebruiken

Vouw in de zijbalk het knooppunt Apparaten uit onder de sectie Azure IoT Hub .
Klik met de rechtermuisknop op uw IoT-apparaat en selecteer SAS-token genereren voor apparaat in het contextmenu.
Voer de verlooptijd in uren in voor het SAS-token in het invoervak en selecteer vervolgens de Enter-toets.
Het SAS-token wordt gemaakt en gekopieerd naar het Klembord.

Het SAS-token dat wordt gegenereerd, heeft de volgende structuur:

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

Het deel van dit token dat moet worden gebruikt als het veld Wachtwoord om verbinding te maken met MQTT is:

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

De apparaat-app kan een Will-bericht opgeven in het CONNECT-pakket. De apparaat-app moet of devices/{device-id}/messages/events/{property-bag} als de naam van het Will-onderwerp gebruiken devices/{device-id}/messages/events/ om Will-berichten te definiëren die moeten worden doorgestuurd als telemetriebericht. In dit geval, als de netwerkverbinding is gesloten, maar een DISCONNECT-pakket niet eerder van het apparaat is ontvangen, verzendt IoT Hub het will-bericht dat is opgegeven in het CONNECT-pakket naar het telemetriekanaal. Het telemetriekanaal kan het standaardeindpunt gebeurtenissen of een aangepast eindpunt zijn dat is gedefinieerd door IoT Hub-routering. Het bericht heeft de eigenschap iothub-MessageType met de waarde Will toegewezen.

Het MQTT-protocol rechtstreeks gebruiken (als een module)

U kunt verbinding maken met IoT Hub via MQTT met behulp van een module-id, vergelijkbaar met het maken van verbinding met IoT Hub als een apparaat. Zie Het MQTT-protocol rechtstreeks gebruiken (als een apparaat) voor meer informatie over het maken van verbinding met IoT Hub via MQTT als apparaat. U moet echter de volgende waarden gebruiken:

Stel de client-id in op {device-id}/{module-id}.
Als u verificatie met gebruikersnaam en wachtwoord wilt uitvoeren, stelt u de gebruikersnaam <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2021-04-12 in op en gebruikt u het SAS-token dat is gekoppeld aan de module-id als uw wachtwoord.
Gebruiken devices/{device-id}/modules/{module-id}/messages/events/ als onderwerp voor het publiceren van telemetrie.
Als devices/{device-id}/modules/{module-id}/messages/events/ WILL-onderwerp gebruiken.
Als onderwerp gebruiken devices/{device-id}/modules/{module-id}/# voor het ontvangen van berichten.
De onderwerpen get en PATCH zijn identiek voor modules en apparaten.
Het onderwerp over de status van de dubbel is identiek voor modules en apparaten.

Zie Publiceren en abonneren met IoT Edge en meer informatie over het MQTT-eindpunt van de IoT Edge-hub voor meer informatie over het gebruik van MQTT met modules.

Voorbeelden die MQTT gebruiken zonder een Azure IoT SDK

De Voorbeeldopslagplaats ioT MQTT bevat C/C++-, Python- en CLI-voorbeelden die laten zien hoe u telemetrieberichten verzendt, cloud-naar-apparaat-berichten ontvangt en apparaatdubbels gebruikt zonder de SDK's van het Azure-apparaat te gebruiken.

De C/C++-voorbeelden maken gebruik van de Eclipse Mosquitto-bibliotheek, het Python-voorbeeld maakt gebruik van Eclipse Paho en de CLI-voorbeelden.mosquitto_pub

Zie Zelfstudie: MQTT gebruiken om een IoT-apparaatclient te ontwikkelen voor meer informatie.

TLS/SSL-configuratie

Als u het MQTT-protocol rechtstreeks wilt gebruiken, moet uw client verbinding maken via TLS/SSL. Pogingen om deze stap over te slaan, mislukken met verbindingsfouten.

Als u een TLS-verbinding tot stand wilt brengen, moet u mogelijk het DigiCert-basiscertificaat downloaden en ernaar verwijzen dat azure gebruikt. Tussen 15 februari en 15 oktober 2023 migreert Azure IoT Hub het TLS-basiscertificaat van het DigiCert Baltimore-basiscertificaat naar de DigiCert Global Root G2. Tijdens de migratieperiode moet u beide certificaten op uw apparaten hebben om de connectiviteit te garanderen. Zie IoT-resources migreren naar een nieuwe TLS-certificaathoofdmap voor meer informatie over deze certificaten. Zie de website van Digicert voor meer informatie over deze certificaten.

In het volgende voorbeeld ziet u hoe u deze configuratie implementeert met behulp van de Python-versie van de Paho MQTT-bibliotheek door de Eclipse Foundation.

Installeer eerst de Paho-bibliotheek vanuit uw opdrachtregelomgeving:

pip install paho-mqtt

Implementeer vervolgens de client in een Python-script. Vervang deze tijdelijke aanduidingen in het volgende codefragment:

<local path to digicert.cer> is het pad naar een lokaal bestand dat het DigiCert-basiscertificaat bevat. U kunt dit bestand maken door de certificaatgegevens te kopiëren van certs.c in de Azure IoT SDK voor C. Neem de regels -----BEGIN CERTIFICATE----- op en -----END CERTIFICATE-----verwijder de " markeringen aan het begin en einde van elke regel en verwijder de \r\n tekens aan het einde van elke regel.
<device id from device registry> is de id van een apparaat dat u hebt toegevoegd aan uw IoT-hub.
<generated SAS token> is een SAS-token voor het apparaat dat is gemaakt zoals eerder in dit artikel is beschreven.
<iot hub name> de naam van uw 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=2021-04-12", password=sas_token)

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

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

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

Als u wilt verifiëren met behulp van een apparaatcertificaat, werkt u het vorige codefragment bij met de wijzigingen die zijn opgegeven in het volgende codefragment. Zie de sectie Een X.509-CA-certificaat ophalen van apparaten verifiëren met X.509-CA-certificaten voor meer informatie over het voorbereiden van verificatie op basis van certificaten.

# Create the client as before
# ...

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

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

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

Apparaat-naar-cloud-berichten verzenden

Nadat een apparaat verbinding heeft gemaakt, kan het berichten verzenden naar IoT Hub met behulp van devices/{device-id}/messages/events/ of devices/{device-id}/messages/events/{property-bag} als onderwerpnaam. Met {property-bag} het element kan het apparaat berichten verzenden met andere eigenschappen in een indeling met URL-codering. Bijvoorbeeld:

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 codering als queryreeksen in het HTTPS-protocol.

Notitie

Als u D2C-berichten doorsturen naar een Azure Storage-account en u JSON-codering wilt gebruiken, moet u het inhoudstype en de inhoudscoderingsinformatie opgeven, waaronder $.ct=application%2Fjson&$.ce=utf-8, als onderdeel van de {property_bag} vorige opmerking.

De indeling van deze kenmerken is protocolspecifiek. IoT Hub vertaalt deze kenmerken in de bijbehorende systeemeigenschappen. Zie de sectie Systeemeigenschappen van de querysyntaxis voor berichtroutering van IoT Hub voor meer informatie.

In de volgende lijst worden de implementatiespecifieke gedragingen van IoT Hub beschreven:

IoT Hub biedt geen ondersteuning voor QoS 2-berichten. Als een apparaat-app een bericht publiceert met QoS 2, sluit IoT Hub de netwerkverbinding.
IoT Hub bewaart geen berichten. Als een apparaat een bericht verzendt met de vlag BEHOUDEN ingesteld op 1, voegt IoT Hub de toepassingseigenschap mqtt-behoud toe aan het bericht. In dit geval wordt het bericht door IoT Hub doorgegeven aan de back-end-app in plaats van het bericht te behouden.
IoT Hub ondersteunt slechts één actieve MQTT-verbinding per apparaat. Elke nieuwe MQTT-verbinding namens dezelfde apparaat-id zorgt ervoor dat IoT Hub de bestaande verbinding laat vallen en 400027 ConnectionForcefullyClosedOnNewConnection wordt aangemeld bij IoT Hub-logboeken
Als u berichten wilt routeren op basis van de berichttekst, moet u eerst de eigenschap 'contentType' (ct) toevoegen aan het einde van het MQTT-onderwerp en de waarde instellen op basis application/json;charset=utf-8 van het volgende voorbeeld. Zie de syntaxisdocumentatie voor ioT Hub-berichtroutering voor meer informatie over routeringsberichten op basis van berichteigenschappen of berichttekst.

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

Zie Apparaat-naar-cloud- en cloud-naar-apparaat-berichten verzenden met IoT Hub voor meer informatie.

Cloud-naar-apparaat-berichten ontvangen

Als u berichten van IoT Hub wilt ontvangen, moet een apparaat zich abonneren devices/{device-id}/messages/devicebound/# als onderwerpfilter. Het jokerteken # op meerdere niveaus in het onderwerpfilter wordt alleen gebruikt om toe te staan dat het apparaat meer eigenschappen in de onderwerpnaam ontvangt. IoT Hub staat het gebruik van de # of ? jokertekens niet toe voor het filteren van subonderwerpen. Omdat IoT Hub geen pub-sub messaging-broker voor algemeen gebruik is, ondersteunt het alleen de gedocumenteerde onderwerpnamen en onderwerpfilters. Een apparaat kan zich slechts op vijf onderwerpen tegelijk abonneren.

Het apparaat ontvangt geen berichten van IoT Hub totdat het is geabonneerd op het apparaatspecifieke eindpunt, vertegenwoordigd door het devices/{device-id}/messages/devicebound/# onderwerpfilter. Nadat een abonnement tot stand is gebracht, ontvangt het apparaat cloud-naar-apparaat-berichten die naar het apparaat zijn verzonden na de tijd van het abonnement. Als het apparaat verbinding maakt met cleanSession-vlag ingesteld op 0, blijft het abonnement behouden in verschillende sessies. In dit geval ontvangt het apparaat de volgende keer dat het apparaat verbinding maakt met CleanSession 0 alle openstaande berichten die naar het apparaat worden verzonden terwijl de verbinding is verbroken. Als het apparaat echter cleanSession-vlag op 1 gebruikt, ontvangt het geen berichten van IoT Hub totdat het zich abonneert op het apparaateindpunt.

IoT Hub levert berichten met de onderwerpnaam devices/{device-id}/messages/devicebound/of devices/{device-id}/messages/devicebound/{property-bag} wanneer er berichteigenschappen zijn. {property-bag} bevat url-gecodeerde sleutel-waardeparen van berichteigenschappen. Alleen toepassingseigenschappen en door de gebruiker ingestelde systeemeigenschappen (zoals messageId of correlationId) zijn opgenomen in de eigenschappenverzameling. Systeemeigenschapsnamen hebben het voorvoegsel $, toepassingseigenschappen gebruiken de oorspronkelijke eigenschapsnaam zonder voorvoegsel. Zie Apparaat-naar-cloud-berichten verzenden voor meer informatie over de indeling van de eigenschappentas.

In cloud-naar-apparaat-berichten worden waarden in de eigenschappentas weergegeven zoals in de volgende tabel:

Eigenschapwaarde	Vertegenwoordiging	Beschrijving
`null`	`key`	Alleen de sleutel wordt weergegeven in de eigenschappentas
lege tekenreeks	`key=`	De sleutel gevolgd door een gelijkteken zonder waarde
niet-null, geenmpty-waarde	`key=value`	De sleutel gevolgd door een gelijkteken en de waarde

In het volgende voorbeeld ziet u een eigenschappenverzameling met drie toepassingseigenschappen: prop1 met een waarde van null; prop2, een lege tekenreeks (""); en prop3 met een waarde van 'een tekenreeks'.

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

Wanneer een apparaat-app zich abonneert op een onderwerp met QoS 2, verleent IoT Hub maximaal QoS-niveau 1 in het SUBACK-pakket . Daarna levert IoT Hub berichten aan het apparaat met QoS 1.

Eigenschappen van een apparaatdubbel ophalen

Eerst abonneert een apparaat zich op $iothub/twin/res/#, om de antwoorden van de bewerking te ontvangen. Vervolgens wordt er een leeg bericht naar het onderwerp $iothub/twin/GET/?$rid={request id}verzonden, met een ingevulde waarde voor de aanvraag-id. De service verzendt vervolgens een antwoordbericht met de apparaatdubbelgegevens over het onderwerp $iothub/twin/res/{status}/?$rid={request-id}, met behulp van dezelfde aanvraag-id als de aanvraag.

De aanvraag-id kan elke geldige waarde zijn voor een waarde van een berichteigenschap en de status wordt gevalideerd als een geheel getal. Zie Apparaat-naar-cloud- en cloud-naar-apparaat-berichten verzenden met IoT Hub voor meer informatie.

De hoofdtekst van het antwoord bevat de eigenschappensectie van de apparaatdubbel, zoals wordt weergegeven in het volgende antwoordvoorbeeld:

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

De mogelijke statuscodes zijn:

-Status	Beschrijving
200	Voltooid
429	Te veel aanvragen (beperkt). Zie IoT Hub-beperking voor meer informatie
5**	Serverfouten

Zie Apparaatdubbels begrijpen en gebruiken in IoT Hub voor meer informatie.

Gerapporteerde eigenschappen van apparaatdubbel bijwerken

Als u gerapporteerde eigenschappen wilt bijwerken, verzendt het apparaat een aanvraag naar IoT Hub via een publicatie via een aangewezen MQTT-onderwerp. Nadat ioT Hub de aanvraag heeft verwerkt, reageert deze op de geslaagde of mislukte status van de updatebewerking via een publicatie naar een ander onderwerp. Het apparaat kan zich abonneren op dit onderwerp om het te informeren over het resultaat van de updateaanvraag van de tweeling. Om dit type interactie tussen aanvragen/antwoorden in MQTT te implementeren, gebruiken we het begrip aanvraag-id ($rid) dat in eerste instantie door het apparaat is verstrekt in de updateaanvraag. Deze aanvraag-id wordt ook opgenomen in het antwoord van IoT Hub, zodat het apparaat de reactie kan correleren met de eerdere aanvraag.

In de volgende volgorde wordt beschreven hoe een apparaat de gerapporteerde eigenschappen in de apparaatdubbel in IoT Hub bijwerken:

Een apparaat moet zich eerst abonneren op het $iothub/twin/res/# onderwerp om de reacties van de bewerking van IoT Hub te ontvangen.
Een apparaat verzendt een bericht met de update van de apparaatdubbel naar het $iothub/twin/PATCH/properties/reported/?$rid={request-id} onderwerp. Dit bericht bevat een aanvraag-id-waarde .
De service verzendt vervolgens een antwoordbericht met de nieuwe ETag-waarde voor de gerapporteerde eigenschappenverzameling in het onderwerp $iothub/twin/res/{status}/?$rid={request-id}. Dit antwoordbericht gebruikt dezelfde aanvraag-id als de aanvraag.

De hoofdtekst van het aanvraagbericht bevat een JSON-document met nieuwe waarden voor gerapporteerde eigenschappen. Elk lid in het JSON-document wordt bijgewerkt of voegt het bijbehorende lid toe aan het document van de apparaatdubbel. Een lid dat is ingesteld op null het verwijderen van het lid uit het bijbehorende object. Voorbeeld:

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

De mogelijke statuscodes zijn:

-Status	Beschrijving
204	Geslaagd (er wordt geen inhoud geretourneerd)
400	Ongeldig verzoek. Ongeldige JSON
429	Te veel aanvragen (beperkt), volgens ioT Hub-beperking
5**	Serverfouten

In het volgende Python-codefragment ziet u het updateproces voor gerapporteerde eigenschappen van de dubbel via MQTT met behulp van de 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)

Wanneer het updateproces voor gerapporteerde eigenschappen van de dubbel is geslaagd in het vorige codefragment, heeft het publicatiebericht van IoT Hub het volgende onderwerp: $iothub/twin/res/204/?$rid=1&$version=6, waar 204 staat de statuscode die aangeeft dat het succes is geslaagd, $rid=1 komt overeen met de aanvraag-id die door het apparaat in de code is opgegeven en $version komt overeen met de versie van de gerapporteerde eigenschappensectie van apparaatdubbels na de update.

Zie Apparaatdubbels begrijpen en gebruiken in IoT Hub voor meer informatie.

Meldingen ontvangen over het bijwerken van gewenste eigenschappen

Wanneer een apparaat is verbonden, verzendt IoT Hub meldingen naar het onderwerp $iothub/twin/PATCH/properties/desired/?$version={new-version}, die de inhoud van de update bevatten die door de back-end van de oplossing wordt uitgevoerd. Voorbeeld:

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

Wat betreft het bijwerken van eigenschappen, null betekenen waarden dat het JSON-objectlid wordt verwijderd. $version Geeft ook de nieuwe versie van de sectie gewenste eigenschappen van de dubbel aan.

Belangrijk

IoT Hub genereert alleen wijzigingsmeldingen wanneer apparaten zijn verbonden. Zorg ervoor dat u de stroom voor opnieuw verbinden van het apparaat implementeert om de gewenste eigenschappen gesynchroniseerd te houden tussen IoT Hub en de apparaat-app.

Zie Apparaatdubbels begrijpen en gebruiken in IoT Hub voor meer informatie.

Reageren op een directe methode

Eerst moet een apparaat zich abonneren op $iothub/methods/POST/#. IoT Hub verzendt methodeaanvragen naar het onderwerp $iothub/methods/POST/{method-name}/?$rid={request-id}, met een geldige JSON of een lege hoofdtekst.

Om te reageren, verzendt het apparaat een bericht met een geldige JSON of lege hoofdtekst naar het onderwerp $iothub/methods/res/{status}/?$rid={request-id}. In dit bericht moet de aanvraag-id overeenkomen met de id in het aanvraagbericht en moet de status een geheel getal zijn.

Zie Directe methoden van IoT Hub begrijpen en aanroepen voor meer informatie.

Volgende stappen

Zie voor meer informatie over het gebruik van MQTT:

Zie voor meer informatie over het gebruik van IoT Device SDKS:

SDK’s voor Azure IoT

Zie voor meer informatie over het plannen van uw IoT Hub-implementatie:

Delen via

Communiceren met een IoT-hub met behulp van het MQTT-protocol

MQTT-ondersteuning vergelijken in IoT Hub en Event Grid

Verbinding maken met IoT Hub

De apparaat-SDK's gebruiken

Standaard time-out voor keep-alive

Een apparaat-app migreren van AMQP naar MQTT

Het MQTT-protocol rechtstreeks gebruiken (als apparaat)

De Azure IoT Hub-extensie voor Visual Studio Code gebruiken

Het MQTT-protocol rechtstreeks gebruiken (als een module)

Voorbeelden die MQTT gebruiken zonder een Azure IoT SDK

TLS/SSL-configuratie

Apparaat-naar-cloud-berichten verzenden

Cloud-naar-apparaat-berichten ontvangen

Eigenschappen van een apparaatdubbel ophalen

Gerapporteerde eigenschappen van apparaatdubbel bijwerken

Meldingen ontvangen over het bijwerken van gewenste eigenschappen

Reageren op een directe methode

Volgende stappen

Feedback

Aanvullende resources