Delen via

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

In dit artikel wordt beschreven hoe apparaten het MQTT-protocol kunnen gebruiken om te communiceren met Azure IoT Hub. De IoT Hub-apparaateindpunten ondersteunen apparaatconnectiviteit met behulp van:

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

Alle apparaatcommunicatie met IoT Hub moet worden beveiligd met BEHULP van TLS. Daarom biedt IoT Hub geen ondersteuning voor onveilige MQTT-verbindingen via 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 een in de cloud gehoste MQTT-broker nodig heeft, gebruikt u Azure Event Grid . Event Grid maakt bidirectionele communicatie mogelijk tussen MQTT-clients op flexibele hiërarchische onderwerpen met behulp van een berichtenmodel voor publiceren/abonneren. Hiermee kunt u MQTT-berichten ook routeren naar andere Azure-services of aangepaste eindpunten voor verdere verwerking.

De volgende tabel bevat een overzicht van de huidige verschillen in MQTT-ondersteuning tussen de twee services:

IoT-hub Gebeurtenisgrid
Client-servermodel met nauwe koppeling tussen apparaten en cloud-apps. Het publish-subscribe model dat uitgevers en abonnees van elkaar loskoppelt.
Beperkte functieondersteuning voor MQTT v3.1.1. MQTT v3.1.1 en v5 protocolondersteuning.
Statische, vooraf gedefinieerde onderwerpen. Aangepaste hiërarchische onderwerpen met ondersteuning voor jokertekens.
Geen ondersteuning voor cloud-naar-apparaat-broadcasts of apparaat-naar-apparaat-communicatie. Biedt ondersteuning voor apparaat-naar-cloud- en high fan-out cloud-naar-apparaat-broadcasts, evenals 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:

Veel bedrijfs- en onderwijsfirewalls blokkeren de MQTT-poort (TCP-poort 8883). Als u poort 8883 niet kunt openen in uw firewall, gebruikt u MQTT via WebSockets. MQTT via WebSockets communiceert via poort 443, dat bijna altijd open is. Zie De apparaat-SDK's gebruiken voor meer informatie over het specificeren van de MQTT- en MQTT over WebSockets-protocollen bij gebruik van de Azure IoT SDK's.

De apparaat-SDK's gebruiken

Azure IoT-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 een snellere uitwisseling van berichten, moet u er rekening mee houden dat de bezorging niet gegarandeerd is en niet wordt bevestigd. Om deze reden wordt QoS 0 vaak aangeduid als 'schiet en vergeet'.

Wanneer een apparaat verbinding maakt 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-protocol parameter 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 Maakt standaard gebruik van MQTT Om de client te maken, voegt u websockets=True toe in de aanroep.

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 Beveiligingsbest practices voor IoT-oplossingen > Verbindingsbeveiliging voor meer informatie."

Standaard time-out voor keep-alive

Om ervoor te zorgen dat een clientverbinding met een IoT-hubverbinding actief blijft, verzenden zowel de service als de client regelmatig een keep alive-ping naar elkaar. Als u een van de apparaat-SDK's gebruikt, verzendt de client een keep-alive-bericht 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 Nee
C 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 pingverzoek vier keer per ingestelde 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 keep-alive ping-interval van IoT Hub 1,5 keer de keep-alive-waarde van de client; IoT Hub beperkt echter de maximale time-out aan serverzijde tot 29,45 minuten (1767 seconden).

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 netwerkverkeer reset de keep-alive. Bijvoorbeeld, wanneer een Shared Access Signature (SAS) token succesvol wordt vernieuwd, wordt de keep-alive opnieuw ingesteld.

Een apparaattoepassing migreren van AMQP naar MQTT

Als u de apparaat-SDK's gebruikt, moet u de protocolparameter in de client initialisatie wijzigen om over te schakelen van AMQP naar MQTT.

Wanneer u overstapt van AMQP naar MQTT, controleert u de volgende items:

  • AMQP retourneert fouten voor veel voorwaarden, terwijl MQTT de verbinding beëindigt. Als gevolg hiervan moet u mogelijk de logica voor het afhandelen van uitzonderingen wijzigen.

  • MQTT biedt geen ondersteuning voor de weigeringsbewerking wanneer er cloud-naar-apparaat-berichten worden ontvangen. Als uw back-endtoepassing een antwoord van de apparaattoepassing moet ontvangen, kunt u overwegen om directe methoden te gebruiken.

  • AMQP wordt niet ondersteund in de Python SDK.

Het MQTT-protocol rechtstreeks vanaf een apparaat gebruiken

Als een apparaat de SDK's van het IoT-apparaat 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.

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 Beveiligingsbest practices voor IoT-oplossingen > Verbindingsbeveiliging voor meer informatie."

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

  • Gebruik voor het ClientId-veld de deviceId.

  • Voor het Gebruikersnaamveld gebruikt u {iotHub-hostname}/{device-id}/?api-version=2021-04-12, waar {iotHub-hostname} de volledige CName van de IoT-hub is.

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

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

    Neem api-versie op in het veld om onverwacht gedrag te voorkomen.

  • Gebruik een SAS-token voor het veld Wachtwoord . In het volgende fragment ziet u de indeling van het SAS-token:

    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-configuratie voor meer informatie.

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

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

    De extensie genereert een SAS-token met 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 apparaattoepassing kan een Will-bericht opgeven in het CONNECT-pakket . De apparaattoepassing moet devices/{device-id}/messages/events/ of devices/{device-id}/messages/events/{property-bag} gebruiken als de naam van het Will-onderwerp 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 vanuit een module gebruiken

U kunt ook verbinding maken met IoT Hub via MQTT met behulp van een module-id. Deze benadering is vergelijkbaar met het maken van verbinding als een apparaat, maar u moet 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 in op <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2021-04-12. Als u SAS gebruikt, 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.

  • Gebruik devices/{device-id}/modules/{module-id}/messages/events/ als het Will-onderwerp.

  • Als onderwerp gebruiken devices/{device-id}/modules/{module-id}/# voor het ontvangen van berichten.

  • De GET- en PATCH-onderwerpen zijn hetzelfde voor modules en apparaten.

  • Het onderwerp van de dubbelen status is hetzelfde voor modules en apparaten.

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

Voorbeelden die MQTT gebruiken zonder een Azure IoT-apparaat-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 zonder een apparaat-SDK te gebruiken.

TLS-configuratie

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

Als u een TLS-verbinding tot stand wilt brengen, moet u mogelijk het DigiCert Global Root G2-basiscertificaat downloaden en ernaar verwijzen dat door Azure wordt gebruikt. Zie de website van Digicert voor meer informatie over dit certificaat.

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

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 Identiteiten verifiëren met X.509 certificaten voor meer informatie over het voorbereiden op authenticatie 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. Het {property-bag} element stelt het apparaat in staat berichten te verzenden met andere eigenschappen in een met URL gecodeerd formaat. Bijvoorbeeld:

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

Dit {property_bag} element maakt gebruik van dezelfde codering als queryreeksen in het HTTPS-protocol.

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} in de vorige notitie genoemde opmerking.

Notitie

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

De volgende lijst bevat een overzicht van het implementatiespecifieke gedrag van IoT Hub MQTT:

  • IoT Hub biedt geen ondersteuning voor QoS 2-berichten. Als een apparaattoepassing een bericht publiceert met QoS 2, sluit IoT Hub de netwerkverbinding.

  • IoT Hub bewaart geen Retain 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 geeft IoT Hub het bericht door aan de back-endtoepassing in plaats van het behouden 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 neer zet en 400027 ConnectionForcefullyClosedOnNewConnection schrijft in de IoT Hub-logboeken

  • Als u berichten wilt routeren op basis van de hoofdtekst van het bericht, voegt u eerst de eigenschap ct toe aan het einde van het MQTT-onderwerp en stelt u de waarde application/json;charset=utf-8 in op zoals wordt weergegeven in het volgende voorbeeld. Zie de IoT Hub-berichtroutering syntaxisdocumentatie voor meer informatie over het routeren van berichten op basis van berichteigenschappen of berichttekst.

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

Zie Berichten verzenden en ontvangen met IoT Hub voor meer informatie.

Cloud-naar-apparaat-berichten ontvangen

Om berichten van IoT Hub te ontvangen, moet een apparaat zich abonneren met devices/{device-id}/messages/devicebound/# als onderwerpfilter. Met het jokerteken # op meerdere niveaus in het onderwerpfilter kan het apparaat meer eigenschappen in de onderwerpnaam ontvangen. IoT Hub staat het gebruik van de # of ? jokertekens niet toe om subonderwerpen te filteren. IoT Hub is geen berichtenbroker voor algemeen gebruik voor publiceren/abonneren, maar ondersteunt 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 de CleanSession-vlag op 1 gezet heeft, ontvangt het geen berichten van IoT Hub totdat het zich abonneert op zijn apparaateindpunt.

IoT Hub levert berichten met de onderwerpnaamdevices/{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 het formaat 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-nul, niet-lege 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 apparaattoepassing 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.

De eigenschappen van de apparaat-tweeling 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 eigenschap van een bericht en de status wordt gevalideerd als een geheel getal. Zie Berichten verzenden en ontvangen met IoT Hub voor meer informatie.

De hoofdtekst van het antwoord bevat de sectie met eigenschappen van de apparaat-tweeling, zoals weergegeven in het volgende antwoordvoorbeeld.

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

De mogelijke statuscodes zijn:

Toestand Beschrijving
200 Succes
429 Te veel aanvragen (beperkt). Zie IoT Hub-quota en bandbreedtebeperking voor meer informatie
5** Serverfouten

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

Gerapporteerde eigenschappen van apparaat-tweeling bijwerken

Als u gerapporteerde eigenschappen wilt bijwerken, verzendt het apparaat een aanvraag naar IoT Hub door deze te publiceren naar een aangewezen MQTT-onderwerp. Nadat de aanvraag door IoT Hub is verwerkt, reageert deze met de succes- of foutstatus van de updatebewerking door deze naar een ander onderwerp te publiceren. Het apparaat kan zich abonneren op dit onderwerp om meldingen te ontvangen over het resultaat van de twin-updateaanvraag. Om dit type interactie tussen aanvragen/antwoorden in MQTT te implementeren, biedt het apparaat een aanvraag-id ($rid) in de eerste updateaanvraag. Deze aanvraag-id wordt vervolgens opgenomen in het antwoord van IoT Hub om het apparaat in staat te stellen het antwoord op de juiste aanvraag te correleren.

In de volgende reeks wordt beschreven hoe een apparaat de gerapporteerde eigenschappen in de apparaat-twin bijwerkt in IoT Hub:

  1. Een apparaat abonneert zich eerst op het $iothub/twin/res/# onderwerp om het in staat te stellen reacties van IoT Hub te ontvangen.

  2. Een apparaat verzendt een bericht met de update van de apparaat-tweeling naar het $iothub/twin/PATCH/properties/reported/?$rid={request-id} topic. Dit bericht bevat een aanvraag-id-waarde .

  3. 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 element in het JSON-document werkt het bijbehorende element in het document van de apparaatdubbel bij of voegt het toe. Een lid dat wordt ingesteld op null verwijdert het lid uit het bijbehorende object. Bijvoorbeeld:

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

De mogelijke statuscodes zijn:

Toestand Beschrijving
204 Geslaagd (er wordt geen inhoud geretourneerd)
400 Ongeldig verzoek. Onjuist geformatteerde JSON
429 Te veel aanvragen (snelheidsbeperking), volgens quota en snelheidsbeperking van IoT Hub
5** Serverfouten

In het volgende Python-codefragment wordt het updateproces van twin gerapporteerde eigenschappen via MQTT met behulp van de Paho MQTT-client gedemonstreerd:

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 van de gerapporteerde eigenschappen van tweelingapparaten is geslaagd, publiceert IoT Hub een bericht naar het volgende onderwerpskanaal: $iothub/twin/res/204/?$rid=1&$version=6, waarbij 204 de statuscode is die aangeeft dat het is gelukt, $rid=1 overeenkomt met de aanvraag-ID opgegeven door het apparaat in de code, en $version overeenkomt met de versie van de sectie van gerapporteerde eigenschappen van de apparaat-tweeling 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. Bijvoorbeeld:

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

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

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

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

Reageren op een directe methode

Eerst abonneert een apparaat zich 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: