Communiceren met uw IoT-hub met het MQTT-protocol

IoT Hub kunnen apparaten communiceren met de eindpunten van IoT Hub apparaat met behulp van:

  • MQTT v3.1.1 op poort 8883
  • MQTT v3.1.1 via WebSocket op poort 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. 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) is geblokkeerd in veel bedrijfs- en onderwijsnetwerkomgevingen. 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, die bijna altijd open is in netwerkomgevingen. Zie Using the device SDKs (De apparaat-SDK's gebruiken) voor meer informatie over het opgeven van de MQTT- en MQTT via Web Sockets-protocollen bij het gebruik van de Azure IoT-SDK's.

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 de IoT Hub connection string om een verbinding met een IoT-hub tot stand te brengen. Als u het MQTT-protocol wilt gebruiken, moet de clientprotocolparameter worden ingesteld op MQTT. U kunt ook MQTT via Web Sockets opgeven in de clientprotocolparameter. Standaard maken de apparaat-SDK's verbinding met een IoT Hub met de CleanSession-vlag ingesteld op 0 en gebruiken ze 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 levering niet wordt gegarandeerd of bevestigd. Daarom wordt QoS 0 vaak 'fire and forget' 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 om een verbinding tot stand te brengen met IoT Hub met behulp van het MQTT- of MQTT-over-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 naar MQTT via Web Sockets als MQTT uitvalt. Als u alleen MQTT via websocket wilt opgeven, gebruikt u TransportType.Mqtt_WebSocket_Only
Python Ondersteunt MQTT standaard Voeg websockets=True toe aan de aanroep om de client te maken

In het volgende fragment ziet u hoe u het protocol MQTT via Web Sockets opgeeft bij het gebruik van de 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);

In het volgende fragment ziet u hoe u het MQTT via Web Sockets-protocol 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 blijft werken, verzenden zowel de service als de client regelmatig een keep-alive ping naar elkaar. De client die IoT SDK gebruikt, verzendt een keep-alive op het interval dat in deze tabel hieronder is gedefinieerd:

Taal Standaardinterval voor keep-alive Configureerbaar
Node.js 180 seconden No
Java 230 seconden No
C 240 seconden Ja
C# 300 seconden Ja
Python 60 seconden No

Volgens de MQTT-specificatieis IoT Hub pinginterval van de client 1,5 keer de keep-alive-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-tijd van Azure load balancer, namelijk 29,45 minuten.

Een apparaat dat de Java SDK gebruikt, 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. De IoT Hub wordt echter niet onmiddellijk verbroken. Er wordt nog een seconden gewacht voordat het apparaat wordt losgekoppeld met de fout (230 * 1.5) - 230 = 115 404104 DeviceConnectionClosedRemotely.

De maximale waarde voor keep-alive van de client die u kunt instellen, is 1767 / 1.5 = 1177 seconden. Verkeer stelt de keep-alive opnieuw in. Als bijvoorbeeld een SAS-token is vernieuwd, wordt de keep-alive opnieuw ingesteld.

Een apparaat-app migreren van AMQP naar MQTT

Als u de apparaat-SDK'sgebruikt, moet u bij het overschakelen van AMQP naar MQTT de protocolparameter wijzigen in de client-initialisatie, 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 de weigeringsbewerkingen bij het ontvangen van cloud-naar-apparaat-berichten. Als uw back-end-app een reactie 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 voorbeeldopslagplaats van IoT MQTTvindt u een aantal C/C++-demoprojecten die laten zien hoe u telemetrieberichten verzendt en gebeurtenissen ontvangt met een IoT-hub zonder de Azure IoT C SDK te gebruiken.

In deze voorbeelden wordt de Eclipse Mosquitto-bibliotheek gebruikt om berichten te verzenden naar de MQTT Broker die is geïmplementeerd in de IoT-hub.

Zie Tutorial - Use MQTT to develop an IoT Plug en Play device client (Zelfstudie - MQTT gebruiken om een IoT-client voor Plug en Play 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 machine.

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

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

  • 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 machine. Meer informatie over IoT-Plug en Play

Voor Linux:

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

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

Voor mosquitto_pub:

Deze map bevat twee voorbeelden opdrachten die worden gebruikt met mosquitto_pub hulpprogramma geleverd door Mosquitto.org.

  • Mosquitto_sendmessage: een eenvoudig sms-bericht verzenden naar een Azure IoT-hub die als een apparaat optreedt.

  • Mosquitto_subscribe: om gebeurtenissen te zien die plaatsvinden in een Azure IoT-hub.

Het MQTT-protocol rechtstreeks gebruiken (als een 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 voor het veld ClientId de deviceId.

  • Gebruik voor het veld Gebruikersnaam , waarbij de volledige {iothubhostname}/{device_id}/?api-version=2018-06-30 {iothubhostname} CName van de IoT-hub is.

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

    contoso.azure-devices.net/MyDevice01/?api-version=2018-06-30

    Het wordt sterk aanbevolen om de API-versie in het veld op te nemen. Anders kan dit onverwacht gedrag veroorzaken.

  • Gebruik voor het veld Wachtwoord een SAS-token. De indeling van het SAS-token is hetzelfde als voor zowel de HTTPS- als 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 apparaatsectie van Using IoT Hub security tokens (Beveiligingstokens gebruiken) voor meer informatie over het genereren IoT Hub SAS-tokens.

    Tijdens 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 linkeronderhoek 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={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 veld Wachtwoord om verbinding te maken met behulp van 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-verbinding maken en de verbinding met pakketten verbreken, IoT Hub een gebeurtenis op het Operations Monitoring-kanaal. Deze gebeurtenis biedt aanvullende informatie die u kan helpen bij het oplossen van verbindingsproblemen.

De apparaat-app kan een Will-bericht opgeven in het CONNECT-pakket. De apparaat-app moet of gebruiken als de onderwerpnaam Will om Will-berichten te definiëren die devices/{device_id}/messages/events/ devices/{device_id}/messages/events/{property_bag} moeten worden doorgestuurd als een telemetriebericht. Als in dit geval de netwerkverbinding wordt verbroken, maar er niet eerder een DISCONNECT-pakket van het apparaat is ontvangen, verzendt IoT Hub het bericht Will dat is opgegeven in het CONNECT-pakket naar het telemetriekanaal. Het telemetriekanaal kan het standaardgebeurtenis-eindpunt zijn of een aangepast eindpunt 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 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 als een apparaat gebruiken van het MQTT-protocol),maar u moet het volgende gebruiken:

  • Stel de client-id in op {device_id}/{module_id} .

  • Als u met een gebruikersnaam en wachtwoord wilt verifiëren, stelt u de gebruikersnaam in op en gebruikt u het SAS-token dat is gekoppeld aan de <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2018-06-30 module-id als uw wachtwoord.

  • Gebruik 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 WILL-onderwerp.

  • De get- en PATCH-onderwerpen voor de tweeling zijn identiek voor modules en apparaten.

  • Het onderwerp status van de tweeling is identiek voor modules en apparaten.

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 hier naar verwijzen. Dit certificaat wordt door Azure gebruikt om de verbinding te beveiligen. U vindt dit certificaat in de opslagplaats Azure-iot-sdk-c. Meer informatie over deze certificaten vindt u op de website van Digicert.

Een voorbeeld van hoe u dit implementeert met behulp van de Python-versie van de Paho MQTT-bibliotheek van de Eclipse Foundation kan er als volgt uitzien.

Installeer eerst de Paho-bibliotheek vanuit uw opdrachtregelomgeving:

pip install paho-mqtt

Implementeert 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 Root-certificaat bevat. U kunt dit bestand maken door de certificaatgegevens van certs.c te kopiëren in de Azure IoT SDK voor C. Neem de regels en op, verwijder de markeringen aan het begin en einde van elke regel en verwijder de tekens aan het einde van -----BEGIN CERTIFICATE----- -----END CERTIFICATE----- elke " \r\n 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=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 apparaatcertificaat, werkt u het bovenstaande codefragment bij met de volgende wijzigingen (zie Een X.509 CA-certificaat verkrijgen over het voorbereiden op 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=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 verzenden

Nadat de verbinding tot stand is brengen, kan een apparaat berichten naar de IoT Hub devices/{device_id}/messages/events/ met of devices/{device_id}/messages/events/{property_bag} als onderwerpnaam. Met {property_bag} het -element kan het apparaat berichten met aanvullende eigenschappen verzenden 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.

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, wordt IoT Hub de netwerkverbinding gesloten.

  • IoT Hub niet behouden Berichten behouden. Als een apparaat een bericht verzendt met de vlag RETAIN ingesteld op 1, IoT Hub de toepassings-eigenschap mqtt-retain toegevoegd aan het bericht. In dit geval wordt het bericht niet behouden, maar IoT Hub aan de back-end-app.

  • IoT Hub ondersteunt slechts één actieve MQTT-verbinding per apparaat. Een 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 Logs

Zie ontwikkelaarshandleiding voor Messaging voor meer informatie.

Cloud-naar-apparaat-berichten ontvangen

Als u berichten wilt ontvangen van IoT Hub, moet een apparaat zich abonneren met devices/{device_id}/messages/devicebound/# als onderwerpfilter. Het jokerteken op meerdere niveaus in het onderwerpfilter wordt alleen gebruikt om het apparaat toe te staan aanvullende eigenschappen # in de onderwerpnaam te ontvangen. IoT Hub staat het gebruik van de jokertekens of # voor het filteren van ? subtopics niet toe. Omdat IoT Hub geen broker voor pubsubberichten voor algemeen gebruik is, worden alleen de gedocumenteerde onderwerpnamen en onderwerpfilters ondersteund.

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 de CleanSession-vlag ingesteld op 0, wordt het abonnement tussen verschillende sessies persistent gemaakt. In dit geval ontvangt het apparaat de volgende keer dat het verbinding maakt met CleanSession 0 openstaande berichten die naar het apparaat worden verzonden terwijl de verbinding is verbroken. Als het apparaat echter de cleanSession-vlag gebruikt die is ingesteld op 1, ontvangt het geen berichten van IoT Hub totdat het zich abonneert op het apparaat-eindpunt.

IoT Hub levert berichten met de onderwerpnaam devices/{device_id}/messages/devicebound/ of wanneer er devices/{device_id}/messages/devicebound/{property_bag} berichteigenschappen zijn. {property_bag} bevat url-gecodeerde sleutel-waardeparen van berichteigenschappen. Alleen toepassingseigenschappen en door de gebruiker in te stellen systeemeigenschappen (zoals messageId of correlationId) worden opgenomen in de eigenschappenset. Systeemeigenschappennamen hebben het voorvoegsel $ , toepassingseigenschappen gebruiken de oorspronkelijke eigenschapsnaam zonder voorvoegsel. Zie Apparaat-naar-cloud-berichtenverzenden 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:

Eigenschapswaarde Vertegenwoordiging Description
null key Alleen de sleutel wordt weergegeven in de eigenschappentas
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 die drie toepassingseigenschappen bevat: prop1 met de waarde null ; prop2, een lege tekenreeks (""); en prop3 met de waarde 'een tekenreeks'.

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

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

De eigenschappen van een apparaat dubbel ophalen

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

Aanvraag-id kan elke geldige waarde voor een waarde van een bericht-eigenschap zijn, volgens de ontwikkelaarshandleiding voor IoT Hubmessaging en de status wordt gevalideerd als een geheel getal.

De antwoord-body bevat de sectie Eigenschappen van de apparaat dubbel, 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 apparaattweeling voor meer informatie.

Gerapporteerde eigenschappen van apparaat dubbel bijwerken

Als u gerapporteerde eigenschappen wilt bijwerken, moet het apparaat een aanvraag indienen IoT Hub via een publicatie via een aangewezen MQTT-onderwerp. Nadat de aanvraag is verwerkt, IoT Hub via een publicatie naar een ander onderwerp de status geslaagd of mislukt van de updatebewerking. Dit onderwerp kan door het apparaat worden geabonneerd om het te informeren over het resultaat van de dubbele updateaanvraag. Voor het implementeren van dit type interactie tussen aanvraag en antwoord in MQTT maken we gebruik van de notie van aanvraag-id ( ) die in eerste instantie door het apparaat is opgegeven in de $rid updateaanvraag. Deze aanvraag-id is ook opgenomen in het antwoord van IoT Hub zodat het apparaat het antwoord kan correleren met de specifieke eerdere aanvraag.

In de volgende reeks wordt beschreven hoe een apparaat de gerapporteerde eigenschappen in de apparaat dubbel in IoT Hub:

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

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

  3. De service verzendt vervolgens een antwoordbericht met de nieuwe ETag-waarde voor de verzameling gerapporteerde eigenschappen in het onderwerp $iothub/twin/res/{status}/?$rid={request id} . Dit antwoordbericht gebruikt dezelfde aanvraag-id als de aanvraag.

De body van het aanvraagbericht bevat een JSON-document met nieuwe waarden voor gerapporteerde eigenschappen. Elk lid in het JSON-document werkt het bijbehorende lid bij of voegt het bijbehorende lid toe aan het document van de apparaattweeling. Een lid dat is null ingesteld op verwijdert het lid uit het object dat het bevat. Bijvoorbeeld:

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

De mogelijke statuscodes zijn:

Status Beschrijving
204 Geslaagd (er wordt geen inhoud geretourneerd)
400 Slechte aanvraag. Verkeerd vormgevormde JSON
429 Te veel aanvragen (beperkt), volgens IoT Hub beperking
5** Serverfouten

In het onderstaande Python-codefragment ziet u het updateproces van de dubbel gerapporteerde eigenschappen 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)

Als de updatebewerking voor dubbele gerapporteerde eigenschappen hierboven is geslaagd, heeft het publicatiebericht van IoT Hub het volgende onderwerp: , waarbij de statuscode is die aangeeft dat het is gelukt, overeenkomt met de aanvraag-id die is opgegeven door het apparaat in de code en overeenkomt met de sectie met de versie van gerapporteerde eigenschappen van apparaattweeling na $iothub/twin/res/204/?$rid=1&$version=6 204 de $rid=1 $version update.

Zie de ontwikkelaarshandleiding voor apparaattweeling voor meer informatie.

Gewenste updatemeldingen voor eigenschappen ontvangen

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

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

Net als bij updates van eigenschappen null betekenen waarden dat het JSON-objectlid wordt verwijderd. Houd er ook rekening mee $version dat de nieuwe versie van de sectie gewenste eigenschappen van de tweeling aangeeft.

Belangrijk

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

Zie de ontwikkelaarshandleiding voor apparaattweeling 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 body.

Om te reageren, verzendt het apparaat een bericht met een geldige JSON of lege body 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 ontwikkelaarshandleiding voor directe methoden voor meer informatie.

Aanvullende overwegingen

Als laatste overweging: als u het gedrag van het MQTT-protocol aan de cloudzijde moet aanpassen, moet u de gateway van het Azure IoT-protocol bekijken. Met deze software kunt u een krachtige aangepaste protocolgateway implementeren die rechtstreeks met de IoT Hub. Met de Azure IoT-protocolgateway kunt u het apparaatprotocol aanpassen voor brownfield MQTT-implementaties of andere aangepaste protocollen. Voor deze aanpak is echter wel vereist dat u een aangepaste protocolgateway kunt uitvoeren en gebruiken.

Volgende stappen

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

Zie voor meer informatie over het plannen IoT Hub implementatie:

Zie voor meer informatie over de mogelijkheden van IoT Hub: