Kommunicera med en IoT-hubb med hjälp av MQTT-protokollet

Artikel
11/15/2023

Den här artikeln beskriver hur enheter kan använda MQTT-beteenden som stöds för att kommunicera med Azure IoT Hub. Med IoT Hub kan enheter kommunicera med IoT Hub-enhetsslutpunkterna med hjälp av:

MQTT v3.1.1 på TCP-port 8883
MQTT v3.1.1 via WebSocket på TCP-port 443.

Kommentar

Några av de funktioner som nämns i den här artikeln, t.ex. moln till enhet-meddelanden, enhetstvillingar och enhetshantering, är bara tillgängliga på IoT Hubs standardnivå. Mer information om de grundläggande och standard-/kostnadsfria IoT Hub-nivåerna finns i Välj rätt IoT Hub-nivå för din lösning.

All enhetskommunikation med IoT Hub måste skyddas med TLS/SSL. IoT Hub stöder därför inte icke-säkerhetsanslutningar via TCP-port 1883.

Jämför MQTT-stöd i IoT Hub och Event Grid

IoT Hub är inte en fullständig MQTT-mäklare och stöder inte alla beteenden som anges i MQTT v3.1.1-standarden. Om din lösning behöver MQTT rekommenderar vi MQTT-stöd i Azure Event Grid. Event Grid möjliggör dubbelriktad kommunikation mellan MQTT-klienter i flexibla hierarkiska ämnen med hjälp av en pub-sub-meddelandemodell. Du kan också dirigera MQTT-meddelanden till Azure-tjänster eller anpassade slutpunkter för vidare bearbetning.

I följande tabell förklaras skillnaderna i MQTT-stöd mellan de två tjänsterna:

IoT Hub	Event Grid
Klientservermodell med nära koppling mellan enheter och molnappar.	Publicera prenumerationsmodell som frikopplar utgivare och prenumeranter.
Begränsat funktionsstöd för MQTT v3.1.1 och begränsat funktionsstöd för MQTT v5 i förhandsversion. Mer funktionsstöd är inte planerat.	Protokollstöd för MQTT v3.1.1 och v5, med mer funktionsstöd och branschefterlevnad planerat.
Statiska, fördefinierade ämnen.	Anpassade hierarkiska ämnen med stöd för jokertecken.
Inget stöd för moln-till-enhet-sändningar och kommunikation mellan enheter.	Har stöd för sändningar från enhet till moln, utsända moln-till-enhet-sändningar och kommunikationsmönster från enhet till enhet.
Maximal meddelandestorlek på 256 KB.	Maximal meddelandestorlek på 512 KB.

Ansluta till IoT Hub

En enhet kan använda MQTT-protokollet för att ansluta till en IoT-hubb med något av följande alternativ:

Azure IoT SDK:er.
MQTT-protokollet direkt.

MQTT-porten (TCP-port 8883) blockeras i många företags- och utbildningsnätverksmiljöer. Om du inte kan öppna port 8883 i brandväggen rekommenderar vi att du använder MQTT via WebSockets. MQTT via WebSockets kommunicerar via port 443, som nästan alltid är öppen i nätverksmiljöer. Information om hur du anger protokollen MQTT och MQTT över WebSockets när du använder Azure IoT SDK:er finns i Använda enhets-SDK:er.

Använda enhetens SDK:er

Enhets-SDK:er som stöder MQTT-protokollet är tillgängliga för Java, Node.js, C, C# och Python. Enhets-SDK:erna använder den valda autentiseringsmekanismen för att upprätta en anslutning till en IoT-hubb. Om du vill använda MQTT-protokollet måste klientprotokollparametern anges till MQTT. Du kan också ange MQTT över WebSockets i klientprotokollparametern. Som standard ansluter enhetens SDK:er till en IoT Hub med flaggan CleanSession inställd på 0 och använder QoS 1 för meddelandeutbyte med IoT-hubben. Även om det är möjligt att konfigurera QoS 0 för snabbare meddelandeutbyte bör du notera att leveransen inte är garanterad eller bekräftad. Därför kallas QoS 0 ofta för "eld och glöm".

När en enhet är ansluten till en IoT-hubb tillhandahåller enhetens SDK:er metoder som gör det möjligt för enheten att utbyta meddelanden med en IoT-hubb.

Följande tabell innehåller länkar till kodexempel för varje språk som stöds och anger vilken parameter som ska användas för att upprätta en anslutning till IoT Hub med hjälp av protokollet MQTT eller MQTT via WebSockets.

Språk	MQTT-protokollparameter	MQTT över WebSockets-protokollparameter
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 återgår till MQTT över WebSockets om MQTT misslyckas. Om du bara vill ange MQTT över WebSockets använder du TransportType.Mqtt_WebSocket_Only
Python	Stöder MQTT som standard	Lägg till `websockets=True` i anropet för att skapa klienten

Följande fragment visar hur du anger MQTT över WebSockets-protokollet när du använder 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);

Följande fragment visar hur du anger MQTT över WebSockets-protokollet när du använder Azure IoT Python SDK:

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

Viktigt!

Den här artikeln innehåller steg för att ansluta en enhet med en signatur för delad åtkomst, även kallad symmetrisk nyckelautentisering. Den här autentiseringsmetoden är praktisk för testning och utvärdering, men att autentisera en enhet med X.509-certifikat är en säkrare metod. Mer information finns i Metodtips > för säkerhet Anslutningssäkerhet.

Standardtidsgränser för keep-alive

För att säkerställa att en klient-/IoT-hubbanslutning förblir aktiv skickar både tjänsten och klienten regelbundet en keep-alive-ping till varandra. Klienten som använder IoT SDK skickar en keep-alive med det intervall som definieras i följande tabell:

Språk	Standardintervall för keep-alive	Konfigureringsbart
Node.js	180 sekunder	Nej
Java	230 sekunder	Ja
C	240 sekunder	Ja
C#	300 sekunder	Ja
Python	60 sekunder	Ja

*C# SDK definierar standardvärdet för egenskapen MQTT KeepAliveInSeconds som 300 sekunder. I själva verket skickar SDK en ping-begäran fyra gånger per keep-alive-varaktighetsuppsättning. Med andra ord skickar SDK en keep-alive-ping en gång var 75:e sekund.

Enligt MQTT v3.1.1-specifikationen är IoT-hubbens keep-alive-pingintervall 1,5 gånger klientens keep-alive-värde. IoT-hubb begränsar dock den maximala tidsgränsen på serversidan till 29,45 minuter (1 767 sekunder). Den här gränsen finns eftersom alla Azure-tjänster är bundna till TCP-tidsgränsen för inaktivitet i Azure-lastbalanseraren, vilket är 29,45 minuter.

En enhet som använder Java SDK skickar till exempel pingen keep-alive och förlorar sedan nätverksanslutningen. 230 sekunder senare missar enheten pingen keep-alive eftersom den är offline. IoT Hub stänger dock inte anslutningen omedelbart – den väntar ytterligare några (230 * 1.5) - 230 = 115 sekunder innan enheten kopplas från med felet 404104 DeviceConnectionClosedRemotely.

Det maximala värdet för att hålla klienten vid liv som du kan ange är 1767 / 1.5 = 1177 sekunder. All trafik återställer keep-alive. En lyckad uppdatering av signaturen för delad åtkomst (SAS) återställer till exempel keep-alive.

Migrera en enhetsapp från AMQP till MQTT

Om du använder enhets-SDK:erna måste du ändra protokollparametern i klientinitiering, enligt vad som angavs tidigare, om du byter från AMQP till MQTT.

Kontrollera följande när du gör det:

AMQP returnerar fel för många villkor, medan MQTT avslutar anslutningen. Därför kan logiken för undantagshantering kräva vissa ändringar.
MQTT stöder inte avvisande åtgärder när meddelanden från moln till enhet tas emot. Om serverdelsappen behöver ta emot ett svar från enhetsappen bör du överväga att använda direkta metoder.
AMQP stöds inte i Python SDK.

Använda MQTT-protokollet direkt (som en enhet)

Om en enhet inte kan använda enhetens SDK:er kan den fortfarande ansluta till de offentliga enhetsslutpunkterna med MQTT-protokollet på port 8883.

I CONNECT-paketet ska enheten använda följande värden:

Använd deviceId för fältet ClientId.
I fältet Användarnamn använder du {iotHub-hostname}/{device-id}/?api-version=2021-04-12, där {iotHub-hostname} är hela CName IoT-hubben.

Om namnet på din IoT-hubb till exempel är contoso.azure-devices.net och om namnet på enheten är MyDevice01 ska det fullständiga fältet Användarnamn innehålla:

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

Vi rekommenderar att du inkluderar API-version i fältet . Annars kan det orsaka oväntade beteenden.
I fältet Lösenord använder du en SAS-token. Formatet för SAS-token är detsamma som för både HTTPS- och AMQP-protokollen:

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

Kommentar

Om du använder X.509-certifikatautentisering krävs inte SAS-tokenlösenord. Mer information finns i Självstudie: Skapa och ladda upp certifikat för testning och följ kodanvisningarna i avsnittet TLS/SSL-konfiguration.

Mer information om hur du genererar SAS-token finns i avsnittet Använda SAS-token som en enhet i Kontrollera åtkomst till IoT Hub med signaturer för delad åtkomst.

Du kan också använda Azure IoT Hub-tillägget mellan plattformar för Visual Studio Code eller CLI-tilläggskommandot az iot hub generate-sas-token för att snabbt generera en SAS-token. Du kan sedan kopiera och klistra in SAS-token i din egen kod i testsyfte.

En självstudiekurs om hur du använder MQTT direkt finns i Använda MQTT för att utveckla en IoT-enhetsklient utan att använda en enhets-SDK.

Använda Azure IoT Hub-tillägget för Visual Studio Code

I sidofältet expanderar du noden Enheter under avsnittet Azure IoT Hub .
Högerklicka på din IoT-enhet och välj Generera SAS-token för enhet på snabbmenyn.
Ange förfallotiden i timmar för SAS-token i indatarutan och välj sedan returnyckeln.
SAS-token skapas och kopieras till Urklipp.

DEN SAS-token som genereras har följande struktur:

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

Den del av den här token som ska användas som lösenordsfält för att ansluta med MQTT är:

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

Enhetsappen kan ange ett Will-meddelande i CONNECT-paketet . Enhetsappen ska använda devices/{device-id}/messages/events/ eller devices/{device-id}/messages/events/{property-bag} som will-ämnesnamnet för att definiera Will-meddelanden som ska vidarebefordras som ett telemetrimeddelande. I det här fallet, om nätverksanslutningen är stängd, men ett DISCONNECT-paket inte togs emot tidigare från enheten, skickar IoT Hub will-meddelandet som anges i CONNECT-paketet till telemetrikanalen. Telemetrikanalen kan vara antingen standardslutpunkten Händelser eller en anpassad slutpunkt som definieras av IoT Hub-routning. Meddelandet har egenskapen iothub-MessageType med värdet Will tilldelad till det.

Använda MQTT-protokollet direkt (som en modul)

Du kan ansluta till IoT Hub via MQTT med hjälp av en modulidentitet, ungefär som att ansluta till IoT Hub som en enhet. Mer information om hur du ansluter till IoT Hub via MQTT som en enhet finns i Använda MQTT-protokollet direkt (som en enhet). Du måste dock använda följande värden:

Ange klient-ID till {device-id}/{module-id}.
Om du autentiserar med användarnamn och lösenord anger du användarnamnet till <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2021-04-12 och använder den SAS-token som är associerad med modulidentiteten som ditt lösenord.
Använd devices/{device-id}/modules/{module-id}/messages/events/ som ett ämne för att publicera telemetri.
Använd devices/{device-id}/modules/{module-id}/messages/events/ som WILL-ämne.
Använd devices/{device-id}/modules/{module-id}/# som ett ämne för att ta emot meddelanden.
Ämnena GET och PATCH är identiska för moduler och enheter.
Tvillingstatusavsnittet är identiskt för moduler och enheter.

Mer information om hur du använder MQTT med moduler finns i Publicera och prenumerera med IoT Edge och läs mer om MQTT-slutpunkten för IoT Edge-hubben.

Exempel som använder MQTT utan Azure IoT SDK

IoT MQTT-exempellagringsplatsen innehåller C/C++-, Python- och CLI-exempel som visar hur du skickar telemetrimeddelanden, tar emot meddelanden från molnet till enheten och använder enhetstvillingar utan att använda Azure-enhets-SDK:erna.

C/C++-exemplen använder Eclipse Mosquitto-biblioteket , Python-exemplet använder Eclipse Paho och CLI-exemplen använder mosquitto_pub.

Mer information finns i Självstudie – Använda MQTT för att utveckla en IoT-enhetsklient.

TLS/SSL-konfiguration

Om du vill använda MQTT-protokollet direkt måste klienten ansluta via TLS/SSL. Försök att hoppa över det här steget misslyckas med anslutningsfel.

För att upprätta en TLS-anslutning kan du behöva ladda ned och referera till DigiCert-rotcertifikatet som Azure använder. Mellan 15 februari och 15 oktober 2023 migrerar Azure IoT Hub sitt TLS-rotcertifikat från DigiCert Baltimore-rotcertifikatet till DigiCert Global Root G2. Under migreringsperioden bör du ha båda certifikaten på dina enheter för att säkerställa anslutningen. Mer information om migreringen finns i Migrera IoT-resurser till en ny TLS-certifikatrot För mer information om dessa certifikat, se Digicerts webbplats.

I följande exempel visas hur du implementerar den här konfigurationen med hjälp av Python-versionen av Paho MQTT-biblioteket av Eclipse Foundation.

Installera först Paho-biblioteket från kommandoradsmiljön:

pip install paho-mqtt

Implementera sedan klienten i ett Python-skript. Ersätt dessa platshållare i följande kodfragment:

<local path to digicert.cer> är sökvägen till en lokal fil som innehåller DigiCert-rotcertifikatet. Du kan skapa den här filen genom att kopiera certifikatinformationen från certs.c i Azure IoT SDK för C. Inkludera raderna -----BEGIN CERTIFICATE----- och -----END CERTIFICATE-----, ta bort " märkena i början och slutet av varje rad och ta bort \r\n tecknen i slutet av varje rad.
<device id from device registry> är ID:t för en enhet som du har lagt till i din IoT-hubb.
<generated SAS token> är en SAS-token för enheten som skapades enligt beskrivningen tidigare i den här artikeln.
<iot hub name> namnet på din IoT-hubb.

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()

Om du vill autentisera med ett enhetscertifikat uppdaterar du det tidigare kodfragmentet med de ändringar som anges i följande kodfragment. Mer information om hur du förbereder för certifikatbaserad autentisering finns i avsnittet Hämta ett X.509 CA-certifikat för autentisera enheter med X.509 CA-certifikat.

# 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)

Skicka meddelanden från enhet till moln

När en enhet har anslutit kan den skicka meddelanden till IoT Hub med eller devices/{device-id}/messages/events/ som ämnesnamn.devices/{device-id}/messages/events/{property-bag} Med {property-bag} elementet kan enheten skicka meddelanden med andra egenskaper i ett URL-kodat format. Till exempel:

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

Kommentar

Det här {property_bag} elementet använder samma kodning som frågesträngar i HTTPS-protokollet.

Kommentar

Om du dirigerar D2C-meddelanden till ett Azure Storage-konto och vill använda JSON-kodning måste du ange information om innehållstyp och innehållskodning, inklusive $.ct=application%2Fjson&$.ce=utf-8, som en del av ovanstående {property_bag} i föregående anteckning.

Formatet för dessa attribut är protokollspecifikt. IoT Hub översätter dessa attribut till motsvarande systemegenskaper. Mer information finns i avsnittet Systemegenskaper i frågesyntaxen för IoT Hub-meddelanderoutning.

I följande lista beskrivs implementeringsspecifika beteenden för IoT Hub:

IoT Hub stöder inte QoS 2-meddelanden. Om en enhetsapp publicerar ett meddelande med QoS 2 stänger IoT Hub nätverksanslutningen.
IoT Hub bevarar inte Behåll meddelanden. Om en enhet skickar ett meddelande med flaggan RETAIN inställd på 1 lägger IoT Hub till programegenskapen mqtt-retain i meddelandet. I det här fallet skickar IoT Hub det till serverdelsappen i stället för att bevara kvarhållningsmeddelandet.
IoT Hub stöder endast en aktiv MQTT-anslutning per enhet. Alla nya MQTT-anslutningar för samma enhets-ID gör att IoT Hub släpper den befintliga anslutningen och 400027 ConnectionForcefullyClosedOnNewConnection loggas in i IoT Hub-loggar
Om du vill dirigera meddelanden baserat på meddelandetexten måste du först lägga till egenskapen "contentType" (ct) i slutet av MQTT-ämnet och ange dess värde så som application/json;charset=utf-8 det visas i följande exempel. Mer information om hur du dirigerar meddelanden antingen baserat på meddelandeegenskaper eller meddelandetext finns i dokumentationen om frågesyntax för IoT Hub-meddelanderoutning.

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

Mer information finns i Skicka meddelanden från enhet till moln och från moln till enhet med IoT Hub.

Ta emot meddelanden från moln till enhet

Om du vill ta emot meddelanden från IoT Hub bör en enhet prenumerera med hjälp av devices/{device-id}/messages/devicebound/# ett ämnesfilter. Jokertecknet # på flera nivåer i ämnesfiltret används bara för att tillåta att enheten tar emot fler egenskaper i ämnesnamnet. IoT Hub tillåter inte användning av # jokertecken eller ? jokertecken för filtrering av underfunktioner. Eftersom IoT Hub inte är en allmän meddelandekö för pub-sub stöder den bara de dokumenterade ämnesnamnen och ämnesfiltren. En enhet kan bara prenumerera på fem ämnen i taget.

Enheten får inga meddelanden från IoT Hub förrän den har prenumererat på sin enhetsspecifika slutpunkt, som representeras av devices/{device-id}/messages/devicebound/# ämnesfiltret. När en prenumeration har upprättats tar enheten emot meddelanden från molnet till enheten som skickades till den efter prenumerationens tid. Om enheten ansluter med flaggan CleanSession inställd på 0 sparas prenumerationen mellan olika sessioner. I det här fallet tar enheten nästa gång den ansluter till CleanSession 0 emot alla utestående meddelanden som skickas till den när den är frånkopplad. Om enheten använder Flaggan CleanSession inställd på 1 får den dock inga meddelanden från IoT Hub förrän den prenumererar på enhetsslutpunkten.

IoT Hub levererar meddelanden med ämnesnamnet devices/{device-id}/messages/devicebound/eller devices/{device-id}/messages/devicebound/{property-bag} när det finns meddelandeegenskaper. {property-bag} innehåller url-kodade nyckel/värde-par med meddelandeegenskaper. Endast programegenskaper och användaruppsättningsbara systemegenskaper (till exempel messageId eller correlationId) ingår i egenskapsväskan. Systemegenskapsnamn har prefixet $, programegenskaper använder det ursprungliga egenskapsnamnet utan prefix. Mer information om formatet på egenskapsväskan finns i Skicka meddelanden från enhet till moln.

I meddelanden från moln till enhet visas värden i egenskapsväskan som i följande tabell:

Egenskapsvärde	Representation	beskrivning
`null`	`key`	Endast nyckeln visas i egenskapsväskan
tom sträng	`key=`	Nyckeln följt av ett likhetstecken utan värde
icke-null, inget värde	`key=value`	Nyckeln följt av ett likhetstecken och värdet

I följande exempel visas en egenskapsväska som innehåller tre programegenskaper: prop1 med värdet null; prop2, en tom sträng (""); och prop3 med värdet "en sträng".

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

När en enhetsapp prenumererar på ett ämne med QoS 2 beviljar IoT Hub högsta QoS-nivå 1 i SUBACK-paketet . Därefter levererar IoT Hub meddelanden till enheten med hjälp av QoS 1.

Hämtar en enhetstvillings egenskaper

Först prenumererar $iothub/twin/res/#en enhet på för att ta emot åtgärdens svar. Sedan skickar den ett tomt meddelande till ämnet $iothub/twin/GET/?$rid={request id}, med ett ifyllt värde för begärande-ID. Tjänsten skickar sedan ett svarsmeddelande som innehåller enhetstvillingdata i ämnet $iothub/twin/res/{status}/?$rid={request-id}med samma begärande-ID som begäran.

Begärande-ID:t kan vara valfritt giltigt värde för ett meddelandeegenskapsvärde och statusen verifieras som ett heltal. Mer information finns i Skicka meddelanden från enhet till moln och från moln till enhet med IoT Hub.

Svarstexten innehåller egenskapsavsnittet för enhetstvillingen enligt följande svarsexempel:

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

Möjliga statuskoder är:

Status	beskrivning
200	Framgång
429	För många begäranden (begränsade). Mer information finns i IoT Hub-begränsning
5**	Serverfel

Mer information finns i Understand and use device twins in IoT Hub (Förstå och använda enhetstvillingar i IoT Hub).

Uppdatera enhetstvillingens rapporterade egenskaper

För att uppdatera rapporterade egenskaper utfärdar enheten en begäran till IoT Hub via en publikation via ett angivet MQTT-ämne. När IoT Hub har bearbetat begäran svarar den på uppdateringsåtgärdens status för lyckade eller misslyckade åtgärder via en publikation till ett annat ämne. Enheten kan prenumerera på det här avsnittet för att meddela den om resultatet av tvillinguppdateringsbegäran. För att implementera den här typen av interaktion mellan begäran och svar i MQTT använder vi begreppet begärande-ID ($rid) som ursprungligen tillhandahålls av enheten i dess uppdateringsbegäran. Det här begärande-ID:t ingår också i svaret från IoT Hub så att enheten kan korrelera svaret på dess specifika tidigare begäran.

I följande sekvens beskrivs hur en enhet uppdaterar de rapporterade egenskaperna i enhetstvillingen i IoT Hub:

En enhet måste först prenumerera på ämnet $iothub/twin/res/# för att få åtgärdens svar från IoT Hub.
En enhet skickar ett meddelande som innehåller enhetstvillinguppdateringen till ämnet $iothub/twin/PATCH/properties/reported/?$rid={request-id} . Det här meddelandet innehåller ett värde för begärande-ID .
Tjänsten skickar sedan ett svarsmeddelande som innehåller det nya ETag-värdet för den rapporterade egenskapssamlingen i ämnet $iothub/twin/res/{status}/?$rid={request-id}. Det här svarsmeddelandet använder samma begärande-ID som begäran.

Meddelandetexten för begäran innehåller ett JSON-dokument som innehåller nya värden för rapporterade egenskaper. Varje medlem i JSON-dokumentet uppdaterar eller lägger till motsvarande medlem i enhetstvillingens dokument. En medlemsuppsättning som tar null bort medlemmen från det innehållande objektet. Till exempel:

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

Möjliga statuskoder är:

Status	beskrivning
204	Lyckades (inget innehåll returneras)
400	Felaktig begäran. Felaktig JSON
429	För många begäranden (begränsade) enligt IoT Hub-begränsning
5**	Serverfel

Följande Python-kodfragment visar uppdateringsprocessen för tvillingrapporterade egenskaper via MQTT med paho MQTT-klienten:

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)

När uppdateringsprocessen för tvillingrapporterade egenskaper lyckades i det föregående kodfragmentet har publiceringsmeddelandet från IoT Hub följande ämne: $iothub/twin/res/204/?$rid=1&$version=6, där är statuskoden som 204 anger att den lyckades, $rid=1 motsvarar det begärande-ID som tillhandahålls av enheten i koden och $version motsvarar versionen av avsnittet rapporterade egenskaper för enhetstvillingar efter uppdateringen.

Mer information finns i Understand and use device twins in IoT Hub (Förstå och använda enhetstvillingar i IoT Hub).

Ta emot meddelanden om uppdatering av önskade egenskaper

När en enhet är ansluten skickar IoT Hub meddelanden till ämnet $iothub/twin/PATCH/properties/desired/?$version={new-version}, som innehåller innehållet i uppdateringen som utförs av lösningens serverdel. Till exempel:

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

När det gäller egenskapsuppdateringar null innebär värden att JSON-objektmedlemmen tas bort. $version Anger också den nya versionen av det önskade egenskapsavsnittet för tvillingen.

Viktigt!

IoT Hub genererar endast ändringsmeddelanden när enheter är anslutna. Se till att implementera enhetens återanslutningsflöde för att hålla önskade egenskaper synkroniserade mellan IoT Hub och enhetsappen.

Mer information finns i Understand and use device twins in IoT Hub (Förstå och använda enhetstvillingar i IoT Hub).

Svara på en direktmetod

Först måste en enhet prenumerera $iothub/methods/POST/#på . IoT Hub skickar metodbegäranden till ämnet $iothub/methods/POST/{method-name}/?$rid={request-id}med antingen en giltig JSON eller en tom brödtext.

För att svara skickar enheten ett meddelande med en giltig JSON eller tom brödtext till ämnet $iothub/methods/res/{status}/?$rid={request-id}. I det här meddelandet måste begärande-ID :t matcha det i begärandemeddelandet och statusen måste vara ett heltal.

Mer information finns i Förstå och anropa direktmetoder från IoT Hub.

Nästa steg

Mer information om hur du använder MQTT finns i:

Mer information om hur du använder IoT-enhets-SDKS finns i:

Azure IoT SDK:er

Mer information om hur du planerar din IoT Hub-distribution finns i:

Dela via

Kommunicera med en IoT-hubb med hjälp av MQTT-protokollet

Jämför MQTT-stöd i IoT Hub och Event Grid

Ansluta till IoT Hub

Använda enhetens SDK:er

Standardtidsgränser för keep-alive

Migrera en enhetsapp från AMQP till MQTT

Använda MQTT-protokollet direkt (som en enhet)

Använda Azure IoT Hub-tillägget för Visual Studio Code

Använda MQTT-protokollet direkt (som en modul)

Exempel som använder MQTT utan Azure IoT SDK

TLS/SSL-konfiguration

Skicka meddelanden från enhet till moln

Ta emot meddelanden från moln till enhet

Hämtar en enhetstvillings egenskaper

Uppdatera enhetstvillingens rapporterade egenskaper

Ta emot meddelanden om uppdatering av önskade egenskaper

Svara på en direktmetod

Nästa steg

Feedback

Ytterligare resurser