Communiceren met uw IoT-hub met het MQTT-protocol

IoT Hub stelt apparaten in staat om te communiceren met de IoT Hub apparaateindpunten met behulp van:

  • MQTT v3.1.1 op poort 8883
  • MQTT v3.1.1 via WebSocket op poort 443.

IoT Hub is geen volledige MQTT-broker en biedt geen ondersteuning voor alle gedragingen die zijn opgegeven in de MQTT v3.1.1-standaard. In dit artikel wordt beschreven hoe apparaten ondersteund MQTT-gedrag kunnen gebruiken om te communiceren met 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. 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.

Alle apparaatcommunicatie met IoT Hub moet worden beveiligd met TLS/SSL. Daarom biedt IoT Hub geen ondersteuning voor niet-beveiligde verbindingen via poort 1883.

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 MQTT-poort (8883) wordt geblokkeerd in veel zakelijke en educatieve netwerkomgevingen. Als u poort 8883 niet kunt openen in uw firewall, raden we u aan MQTT via Web Sockets te gebruiken. MQTT via Web Sockets 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 Web Sockets-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 Web Sockets in de clientprotocolparameter. Standaard maken de apparaat-SDK's 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. Daarom wordt QoS 0 vaak 'vuur en vergeet' genoemd.

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 voor het tot stand brengen van een verbinding met IoT Hub met behulp van de MQTT of de MQTT via het Web Sockets-protocol.

Taal MQTT-protocolparameter MQTT via web sockets-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 Web Sockets als MQTT mislukt. Als u alleen MQTT via Web Sockets 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 Web Sockets 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 Web Sockets 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)

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 in deze tabel hieronder is gedefinieerd:

Taal Standaard interval voor keep alive Configureerbaar
Node.js 180 seconden Nee
Java 230 seconden Ja
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, maar in werkelijkheid verzendt de SDK vier keer een pingaanvraag per duurset voor keep alive. Dit betekent dat de SDK elke 75 seconden een keep-alive ping verzendt.

Na de MQTT-specificatie is IoT Hub interval voor keep-alive ping 1,5 keer de waarde van de client. Met IoT Hub wordt de maximale time-out aan de serverzijde echter beperkt tot 29,45 minuten (1767 seconden), omdat alle Azure-services zijn gebonden aan de time-out voor inactieve TCP van Azure-load balancer, namelijk 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 deze 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 het SAS-token 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 overstappen 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 de logica voor het verwerken van uitzonderingen enkele wijzigingen vereisen.

  • MQTT biedt geen ondersteuning voor de 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.

Voorbeeld in C met MQTT zonder Een Azure IoT SDK

In de IoT MQTT-voorbeeldopslagplaats vindt u een aantal C/C++-demoprojecten waarin wordt getoond hoe u telemetrieberichten verzendt en gebeurtenissen ontvangt met een IoT-hub zonder de Azure IoT C SDK te gebruiken.

Deze voorbeelden gebruiken de Eclipse Mosquitto-bibliotheek om berichten te verzenden naar de MQTT Broker die is geïmplementeerd in de IoT-hub.

Zie Zelfstudie: MQTT gebruiken om een IoT-Plug en Play-apparaatclient te ontwikkelen voor meer informatie over het aanpassen van de voorbeelden voor het gebruik van de Azure IoT-Plug en Play-conventies.

Deze opslagplaats bevat:

Voor Windows:

  • TelemetryMQTTWin32: bevat code voor het verzenden van een telemetriebericht naar een Azure IoT-hub, gebouwd en uitgevoerd op een Windows-computer.

  • SubscribeMQTTWin32: bevat code om u te abonneren op gebeurtenissen van een bepaalde IoT-hub op een Windows-computer.

  • DeviceTwinMQTTWin32: bevat code voor het opvragen en abonneren op de gebeurtenissen van een apparaatdubbel van een apparaat in de Azure IoT-hub op een Windows-computer.

  • PnPMQTTWin32: bevat code voor het verzenden van een telemetriebericht met IoT Plug en Play apparaatmogelijkheden naar een Azure IoT-hub, gebouwd en uitgevoerd op een Windows-computer. Meer informatie over IoT-Plug en Play

Voor Linux:

  • MQTTLinux: bevat code en buildscript dat moet worden uitgevoerd op Linux (WSL, Ubuntu en Raspbian zijn tot nu toe getest).

  • LinuxConsoleVS2019: bevat dezelfde code, maar in een VS2019-project gericht op WSL (Windows Linux-subsysteem). Met dit project kunt u stapsgewijs vanuit Visual Studio fouten opsporen in de code die wordt uitgevoerd in Linux.

Voor mosquitto_pub:

Deze map bevat twee voorbeeldopdrachten die worden gebruikt met het hulpprogramma mosquitto_pub hulpprogramma dat wordt geleverd door Mosquitto.org.

  • Mosquitto_sendmessage: een sms-bericht verzenden naar een IoT-hub die fungeert als een apparaat.

  • Mosquitto_subscribe: als u gebeurtenissen wilt zien die plaatsvinden in een IoT-hub.

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.

  • Gebruik voor het veld {iotHub-hostname}/{device-id}/?api-version=2021-04-12{iotHub-hostname}Gebruikersnaam de volledige CName van de 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 op te nemen in het veld. 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 X.509-beveiliging instellen in uw Azure IoT Hub en volg de code-instructies in de sectie TLS/SSL-configuratie voor meer informatie.

    Zie de sectie over het gebruik van IoT Hub beveiligingstokens voor meer informatie over het genereren van SAS-tokens.

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

Voor Azure IoT Tools

  1. Vouw het tabblad AZURE IOT HUB DEVICES in de linkerbenedenhoek van Visual Studio Code uit.

  2. Klik met de rechtermuisknop op uw apparaat en selecteer SAS-token genereren voor apparaat.

  3. Stel de verlooptijd in en druk op Enter.

  4. 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/devices/{device-id}/messages/events/{property-bag} als de naam van het Will-onderwerp gebruiken om Will-berichten te definiëren die moeten worden doorgestuurd als telemetriebericht. In dit geval, als de netwerkverbinding is gesloten, maar er geen DISCONNECT-pakket eerder van het apparaat is ontvangen, stuurt 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)

Verbinding maken met IoT Hub via MQTT met behulp van een module-id is vergelijkbaar met het apparaat (beschreven in de sectie over het rechtstreeks gebruiken van het MQTT-protocol als apparaat), maar u moet het volgende gebruiken:

  • Stel de client-id in op {device-id}/{module-id}.

  • Als u verificatie wilt uitvoeren met gebruikersnaam en wachtwoord, stelt u de gebruikersnaam in op <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2021-04-12 en gebruikt u het SAS-token dat is gekoppeld aan de module-id als uw wachtwoord.

  • Als onderwerp gebruiken devices/{device-id}/modules/{module-id}/messages/events/ voor het publiceren van telemetrie.

  • Als devices/{device-id}/modules/{module-id}/messages/events/ WILL-onderwerp gebruiken.

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

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

  • Het onderwerp over de dubbelstatus is identiek voor modules en apparaten.

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

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 Baltimore-basiscertificaat downloaden en ernaar verwijzen. Dit certificaat is het certificaat dat door Azure wordt gebruikt om de verbinding te beveiligen. U vindt dit certificaat in de Azure-iot-sdk-c-opslagplaats . Meer informatie over deze certificaten vindt u op de website van Digicert.

Een voorbeeld van het implementeren hiervan met behulp van de Python-versie van de Paho MQTT-bibliotheek door eclipse Foundation kan er als volgt uitzien.

Installeer eerst de Paho-bibliotheek vanuit uw opdrachtregelomgeving:

pip install paho-mqtt

Implementeer vervolgens de client in een Python-script. Vervang de tijdelijke aanduidingen als volgt:

  • <local path to digicert.cer> is het pad naar een lokaal bestand dat het DigiCert Baltimore-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 bovenstaande codefragment bij met de volgende wijzigingen (zie Een X.509 CA-certificaat ophalen voor 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 verbinding is gemaakt, kan een apparaat 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 extra eigenschappen in een url-gecodeerde indeling. Bijvoorbeeld:

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

Notitie

Dit {property_bag} element gebruikt dezelfde codering als querytekenreeksen in het HTTPS-protocol.

Notitie

Als u D2C-berichten doorsturen naar een opslagaccount en u JSON-codering wilt levarage, moet u het inhoudstype en de inhoudscoderingsgegevens opgeven, inclusief $.ct=application%2Fjson&$.ce=utf-8 als onderdeel van de {property_bag} hierboven genoemde informatie.

Deze indeling van kenmerken is protocolspecifiek en wordt door IoT Hub omgezet in de relatieve systeemeigenschappen, zoals hier wordt beschreven

Hier volgt een lijst met IoT Hub implementatiespecifieke gedragingen:

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

  • IoT Hub bewaart geen berichten. Als een apparaat een bericht verzendt met de vlag RETAIN 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-end-app in plaats van het behouden 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 verwijderen 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 application/json;charset=utf-8. Hieronder kunt u een voorbeeld bekijken. Zie de documentatie IoT Hub querysyntaxis voor berichtroutering voor meer informatie over routeringsberichten op basis van berichteigenschappen of berichttekst.

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

Zie de handleiding voor berichtontwikkelaars voor meer informatie.

Cloud-naar-apparaat-berichten ontvangen

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

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 voor verschillende sessies. In dit geval ontvangt het apparaat de volgende keer dat het 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 gebruikt die is ingesteld op 1, ontvangt het geen berichten van IoT Hub totdat het zich abonneert op het apparaateindpunt.

IoT Hub berichten bezorgt 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 eigenschappentas. 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 eigenschapstas.

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

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

In het volgende voorbeeld ziet u een eigenschappentas 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 een leeg bericht naar het onderwerp $iothub/twin/GET/?$rid={request id}verzonden, met een ingevulde waarde voor 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.

Aanvraag-id kan elke geldige waarde zijn voor een berichteigenschapswaarde, volgens de handleiding van de IoT Hub berichtenontwikkelaar en de status wordt gevalideerd als een geheel getal.

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 Geslaagd
429 Te veel aanvragen (beperkt), volgens IoT Hub beperking
5** Serverfouten

Zie de ontwikkelaarshandleiding voor apparaatdubbels voor meer informatie.

Gerapporteerde eigenschappen van apparaatdubbel bijwerken

Als u gerapporteerde eigenschappen wilt bijwerken, verzendt het apparaat een aanvraag voor IoT Hub via een publicatie via een aangewezen MQTT-onderwerp. Na het verwerken van de aanvraag reageert IoT Hub de geslaagde of foutstatus van de updatebewerking via een publicatie naar een ander onderwerp. Dit onderwerp kan door het apparaat worden geabonneerd om het bericht te informeren over het resultaat van de aanvraag voor het bijwerken van dubbels. 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 in de updateaanvraag wordt verstrekt. Deze aanvraag-id wordt ook opgenomen in het antwoord van IoT Hub zodat het apparaat de reactie kan correleren met de specifieke eerdere aanvraag.

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

  1. Een apparaat moet zich eerst abonneren op het $iothub/twin/res/# onderwerp om de reacties van de bewerking van IoT Hub te ontvangen.

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

  3. De service verzendt vervolgens een antwoordbericht met de nieuwe ETag-waarde voor de gerapporteerde eigenschappenverzameling op 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 betreffende object. Bijvoorbeeld:

{
    "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 onderstaande Python-codefragment ziet u het updateproces voor gerapporteerde eigenschappen van twee gerapporteerde eigenschappen via MQTT (met behulp van 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)

Na het slagen van de bovenstaande updatebewerking voor gerapporteerde eigenschappen van dubbels, heeft het publicatiebericht van IoT Hub het volgende onderwerp: $iothub/twin/res/204/?$rid=1&$version=6, waar 204 is de statuscode die aangeeft dat is geslaagd, $rid=1 komt overeen met de aanvraag-id van het apparaat in de code en $version komt overeen met de versie van de gerapporteerde eigenschappensectie van apparaatdubbels na de update.

Zie de ontwikkelaarshandleiding voor apparaatdubbels voor meer informatie.

Meldingen ontvangen voor het bijwerken van gewenste eigenschappen

Wanneer een apparaat is verbonden, stuurt 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 betekenen null waarden dat het lid van het JSON-object wordt verwijderd. $version Geeft ook de nieuwe versie van de gewenste eigenschappensectie van de tweeling 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 de ontwikkelaarshandleiding voor apparaatdubbels voor meer informatie.

Reageren op een directe methode

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

Als u wilt 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 de handleiding voor ontwikkelaars van directe methoden voor meer informatie.

Volgende stappen

Zie de MQTT-documentatie voor meer informatie over het MQTT-protocol.

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

Zie voor meer informatie over de mogelijkheden van IoT Hub: