Anteckning
Åtkomst till den här sidan kräver auktorisering. Du kan prova att logga in eller ändra kataloger.
Åtkomst till den här sidan kräver auktorisering. Du kan prova att ändra kataloger.
Den här artikeln beskriver hur enheter kan använda MQTT-protokollet för att kommunicera med Azure IoT Hub. IoT Hub-enhetsslutpunkterna stöder enhetsanslutning med hjälp av:
- MQTT v3.1.1 på port 8883
- MQTT v3.1.1 över WebSocket på port 443
Anmärkning
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å och storlek för din lösning.
All enhetskommunikation med IoT Hub måste skyddas med hjälp av TLS. IoT Hub stöder därför inte osäkra MQTT-anslutningar via 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 en molnbaserad MQTT-koordinator använder du Azure Event Grid i stället. Event Grid möjliggör dubbelriktad kommunikation mellan MQTT-klienter i flexibla hierarkiska ämnen med hjälp av en meddelandemodell för publicering och prenumeration. Du kan också dirigera MQTT-meddelanden till andra Azure-tjänster eller anpassade slutpunkter för vidare bearbetning.
I följande tabell sammanfattas de aktuella skillnaderna i MQTT-stöd mellan de två tjänsterna:
| IoT Hub | Event Grid (händelsenätverk) |
|---|---|
| Klientservermodell med nära koppling mellan enheter och molnappar. | Publisera-prenumerera-modell som frikopplar publicister och prenumeranter. |
| Begränsat funktionsstöd för MQTT v3.1.1. | Protokollstöd för MQTT v3.1.1 och v5. |
| Statiska, fördefinierade ämnen. | Anpassade hierarkiska ämnen med stöd för vildkort. |
| Inget stöd för moln-till-enhet-sändningar eller kommunikation mellan enheter. | Stödjer enhet-till-moln-kommunikation, högfrekventa moln-till-enhet-sändningar och enhet-till-enhet-kommunikationsmönster. |
| 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-enhets-SDK:er.
- MQTT-protokollet direkt.
Många företags- och utbildningsbrandväggar blockerar MQTT-porten (TCP-port 8883). Om du inte kan öppna port 8883 i brandväggen använder du MQTT via WebSockets. MQTT över WebSockets kommunicerar via port 443, som nästan alltid är öppen. 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
Azure IoT-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 och inte bekräftas. Därför kallas QoS 0 ofta för "eld och glöm".
När en enhet ansluter till en IoT-hubb tillhandahåller enhets-SDK:erna 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 | Använder MQTT som standard | Om du vill skapa klienten lägger du till websockets=True i anropet |
Följande fragment visar hur du anger protokollet MQTT över WebSockets 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 för IoT-lösningar > Anslutningssäkerhet.
Standard timeout för keep-alive
För att säkerställa att en klientanslutning till en IoT Hub-anslutning förblir aktiv skickar både tjänsten och klienten regelbundet en keep-alive-ping till varandra. Om du använder någon av enhetens SDK:er skickar klienten ett keep-alive-meddelande 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 | Nej |
| 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 inställd keep-alive-period. Med andra ord skickar SDK en keep-alive-ping en gång var 75:e sekund.
Enligt MQTT v3.1.1-specifikationen är IoT Hubs keep-alive ping-intervall 1,5 gånger klientens keep-alive-värde. IoT Hub begränsar dock den maximala tidsgränsen på serversidan till 29,45 minuter (1 767 sekunder).
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 ett enhetsprogram från AMQP till MQTT
Om du använder enhetens SDK:er måste du ändra protokollparametern i klientinitiering för att växla från AMQP till MQTT.
När du ändrar från AMQP till MQTT kontrollerar du följande:
AMQP returnerar fel för många villkor, medan MQTT avslutar anslutningen. Därför kan du behöva ändra logiken för undantagshantering.
MQTT stöder inte avvisningsåtgärden när den tar emot meddelanden från molnet till enheten. Om serverdelsprogrammet 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 från en enhet
Om en enhet inte kan använda IoT-enhets-SDK:er kan den fortfarande ansluta till de offentliga enhetsslutpunkterna med hjälp av MQTT-protokollet på port 8883.
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 för IoT-lösningar > Anslutningssäkerhet.
I CONNECT-paketet ska enheten använda följande värden:
För fältet ClientId, använd deviceId.
I fältet Användarnamn använder du
{iotHub-hostname}/{device-id}/?api-version=2021-04-12, där{iotHub-hostname}är helaCNameIoT-hubben.Om namnet på din IoT-hubb till exempel är contoso.azure-devices.net och om namnet på enheten är MyDevice01 innehåller fältet Användarnamn :
contoso.azure-devices.net/MyDevice01/?api-version=2021-04-12Om du vill undvika oväntat beteende tar du med API-versionen i fältet.
I fältet Lösenord använder du en SAS-token. Följande kodfragment visar formatet för SAS-token:
SharedAccessSignature sig={signature-string}&se={expiry}&sr={URL-encoded-resourceURI}Anmärkning
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-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 för Visual Studio Code eller CLI-tilläggskommandot az iot hub generate-sas-token för att generera en SAS-token. Du kan sedan kopiera och klistra in SAS-token i din egen kod i testsyfte.
Tillägget genererar en SAS-token med 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=1456481802Den 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
Enhetsprogrammet kan ange ett Will-meddelande i CONNECT-paketet . Enhetsprogrammet 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-meddelandetsom 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 från en modul
Du kan också ansluta till IoT Hub via MQTT med hjälp av en modulidentitet. Den här metoden liknar anslutning som en enhet, men du måste 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. Om du använder SAS använder du DEN SAS-token som är associerad med modulidentiteten som 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 likvärdiga för både moduler och enheter.
Ämnet tvillingstatus är detsamma för moduler och enheter.
Mer information om hur du använder MQTT med moduler finns i IoT Edge Hub MQTT-slutpunkten.
Exempel som använder MQTT utan en Azure IoT-enhets-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 utan att använda en enhets-SDK.
TLS-konfiguration
Om du vill använda MQTT-protokollet direkt måste klienten ansluta via TLS 1.2. Alla 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 rotcertifikatet DigiCert Global Root G2 som Azure använder. Mer information om det här certifikatet finns på Digicerts webbplats.
I följande exempel visas hur du implementerar den här konfigurationen med hjälp av Python-versionen av Paho MQTT-biblioteket.
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\ntecknen 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 i Autentisera identiteter med X.509-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 devices/{device-id}/messages/events/ eller devices/{device-id}/messages/events/{property-bag} som ett ämnesnamn. 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>)…
Det här {property_bag} elementet använder samma kodning som frågesträngar i HTTPS-protokollet.
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.
Anmärkning
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 sammanfattas IoT Hub MQTT-implementeringsspecifika beteenden:
IoT Hub stöder inte QoS 2-meddelanden. Om ett enhetsprogram publicerar ett meddelande med QoS 2 stänger IoT Hub nätverksanslutningen.
IoT Hub bevarar inte
Retainmeddelanden. 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 serverdelsprogrammet i stället för att spara det bevarade meddelandet.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 skriver 400027 ConnectionForcefullyClosedOnNewConnection till IoT Hub-loggarna
Om du vill dirigera meddelanden baserat på meddelandetexten lägger du först till egenskapen
cti slutet av MQTT-ämnet och anger dess värde tillapplication/json;charset=utf-8enligt 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 och ta emot meddelanden 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 gör att enheten kan ta emot fler egenskaper i ämnesnamnet. IoT Hub tillåter inte användning av jokertecknen # eller ? för att filtrera delämnen. IoT Hub är inte en allmän meddelandekö för publicering och prenumeration, den stöder 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 prenumererar 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å sin enhetsslutpunkt.
IoT Hub levererar meddelanden med ämnesnamnetdevices/{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, icke-tomt 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 ett enhetsprogram 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ämta egenskaper för enhetstvillingar
Först prenumererar en enhet på $iothub/twin/res/# 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 och ta emot meddelanden 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:
| Läge | beskrivning |
|---|---|
| 200 | Framgång |
| 429 | För många förfrågningar (strypning). Mer information finns i IoT Hub-kvoter och 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 genom att publicera till ett angivet MQTT-ämne. När IoT Hub har bearbetat begäran svarar den med statusen lyckad eller misslyckad för uppdateringsåtgärden genom att publicera till ett annat ämne. Enheten kan prenumerera på det här avsnittet för att få meddelanden om resultatet av tvillinguppdateringsbegäran. För att implementera den här typen av interaktion mellan begäran och svar i MQTT tillhandahåller enheten ett begärande-ID ($rid) i sin första uppdateringsbegäran. Det här begärande-ID:t ingår sedan i svaret från IoT Hub för att göra det möjligt för enheten att korrelera svaret på rätt begäran.
I följande sekvens beskrivs hur en enhet uppdaterar de rapporterade egenskaperna i enhetstvillingen i IoT Hub:
En enhet prenumererar först på ämnet
$iothub/twin/res/#så att den kan ta emot 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. Att ställa in en medlem på null tar bort medlemmen från det innehållande objektet. Till exempel:
{
"telemetrySendFrequency": "35m",
"batteryLevel": 60
}
Möjliga statuskoder är:
| Läge | 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-kvoter och 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 lyckas publicerar IoT Hub ett meddelande till 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 med 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 önskade egenskaper för uppdatering
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å ett direkt angreppssätt
Först prenumererar en enhet på $iothub/methods/POST/#. 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: