IoT Hub MQTT 5 támogatás (elavult)
Verzió: 2.0 api-verzió: 2020-10-01-preview
Ez a dokumentum az 5.0-s verziójú MQTT protokollon keresztül definiálja az IoT Hub adatsík API-t. Az API-ban található teljes definíciókért tekintse meg az API-referenciát .
Feljegyzés
Az IoT Hub MQTT 5 támogatása elavult, és az IoT Hub korlátozott funkciótámogatással rendelkezik az MQTT-hez. Ha a megoldáshoz MQTT 3.1.1-es vagy v5-ös támogatás szükséges, javasoljuk az MQTT támogatását az Azure Event Gridben. További információ: MQTT-támogatás összehasonlítása az IoT Hubban és az Event Gridben.
Előfeltételek
- Hozzon létre egy teljesen új IoT Hubot, amelyen engedélyezve van az előnézeti mód. Az MQTT 5 csak előzetes módban érhető el, és meglévő IoT Hubot nem válthat előnézeti módra. További információ: Előnézeti mód engedélyezése
- Az MQTT 5 specifikációjának előzetes ismerete.
Támogatási szint és korlátozások
Az MQTT 5 IoT Hub-támogatása előzetes verzióban érhető el, és a következő módokon korlátozott (az ügyfélnek tulajdonságokon keresztül CONNACK
kommunikálva, hacsak másként nem rendelkezik kifejezetten):
- A hivatalos Azure IoT-eszköz SDK-k még nem támogatottak .
- Az előfizetés-azonosítók nem támogatottak.
- A megosztott előfizetések nem támogatottak.
RETAIN
nem támogatott.Maximum QoS
az1
.Maximum Packet Size
(256 KiB
műveletenként további korlátozások vonatkoznak).- A hozzárendelt ügyfélazonosítók nem támogatottak.
Keep Alive
19 min
legfeljebb (az élőség ellenőrzésének maximális késleltetése –28.5 min
).Topic Alias Maximum
az10
.Response Information
nem támogatott;CONNACK
tulajdonságot akkor sem ad visszaResponse Information
, haCONNECT
tulajdonságot tartalmazRequest Response Information
.Receive Maximum
(az engedélyezett ki nem fedezettPUBLISH
csomagok maximális száma (ügyfél-kiszolgáló irányban) a következővelQoS: 1
:16
.- Egyetlen ügyfél legfeljebb
50
előfizetéssel rendelkezhet. Ha egy ügyfél eléri az előfizetési korlátot,SUBACK
az előfizetések0x97
okkódját adja vissza (kvóta túllépve).
Kapcsolat életciklusa
Connection
Ha egy ügyfelet az IoT Hubhoz szeretne csatlakoztatni ezzel az API-val, hozzon létre kapcsolatot MQTT 5 specifikációnként.
Az ügyfélnek a sikeres TLS-kézfogás után 30 másodpercen belül el kell küldenie CONNECT
a csomagot, vagy a kiszolgáló bezárja a kapcsolatot.
Íme egy példa a csomagra CONNECT
:
-> CONNECT
Protocol_Version: 5
Clean_Start: 0
Client_Id: D1
Authentication_Method: SAS
Authentication_Data: {SAS bytes}
api-version: 2020-10-10
host: abc.azure-devices.net
sas-at: 1600987795320
sas-expiry: 1600987195320
client-agent: artisan;Linux
Authentication Method
tulajdonság szükséges, és azonosítja a használt hitelesítési módszert. A hitelesítési módszerről további információt a Hitelesítés című témakörben talál.Authentication Data
tulajdonságkezelés függ aAuthentication Method
. HaAuthentication Method
a beállításSAS
értéke , akkorAuthentication Data
kötelező megadni, és érvényes aláírást kell tartalmaznia. A hitelesítési adatokkal kapcsolatos további információkért lásd : Hitelesítés.api-version
tulajdonság megadása kötelező, és a specifikáció fejlécében megadott API-verzióértékre kell beállítani ahhoz, hogy a specifikáció alkalmazható legyen.host
tulajdonság határozza meg a bérlő gazdagépnevét. Erre csak akkor van szükség, ha A TLS-kézfogás során az SNI-bővítmény megjelenik a Client Hello rekordbansas-at
A kapcsolat idejét határozza meg.sas-expiry
A megadott SAS lejárati idejét határozza meg.client-agent
opcionálisan információkat közöl a kapcsolatot létrehozó ügyfélről.
Feljegyzés
Authentication Method
A nagy kezdőbetűs névvel ellátott specifikációban szereplő egyéb tulajdonságok az MQTT 5 első osztályú tulajdonságai – ezeket az MQTT 5 specifikációja ismerteti részletesen. api-version
és a dash-eset egyéb tulajdonságai az IoT Hub API-ra jellemző felhasználói tulajdonságok.
Az IoT Hub a hitelesítés befejezése után csomagokkal CONNACK
válaszol, és adatokat kér le a kapcsolat támogatásához. Ha a kapcsolat sikeresen létrejött, CONNACK
a következőképpen néz ki:
<- CONNACK
Session_Present: 1
Reason_Code: 0x00
Session_Expiry_Interval: 0xFFFFFFFF # included only if CONNECT specified value less than 0xFFFFFFFF and more than 0x00
Receive_Maximum: 16
Maximum_QoS: 1
Retain_Available: 0
Maximum_Packet_Size: 262144
Topic_Alias_Maximum: 10
Subscription_Identifiers_Available: 0
Shared_Subscriptions_Available: 0
Server_Keep_Alive: 1140 # included only if client did not specify Keep Alive or if it specified a bigger value
Ezek a CONNACK
csomagtulajdonságok az MQTT 5 specifikációját követik. Ezek tükrözik az IoT Hub képességeit.
Hitelesítés
Az Authentication Method
ügyfél tulajdonsága CONNECT
határozza meg, hogy milyen típusú hitelesítést használ ehhez a kapcsolathoz:
SAS
- A közös hozzáférésű jogosultságkód a "tulajdonságábanCONNECT
"Authentication Data
van megadva,X509
- az ügyfél ügyféltanúsítvány-hitelesítésre támaszkodik.
A hitelesítés meghiúsul, ha a hitelesítési módszer nem egyezik az ügyfél által az IoT Hubban konfigurált metódusával.
Feljegyzés
Ennek az API-nak a Authentication Method
tulajdonságát csomagban CONNECT
kell beállítani. Ha Authentication Method
a tulajdonság nincs megadva, a kapcsolat válaszsal Bad Request
meghiúsul.
A korábbi API-verziókban használt felhasználónév-jelszó hitelesítés nem támogatott.
SAS
SAS-alapú hitelesítés esetén az ügyfélnek meg kell adnia a kapcsolati környezet aláírását. Az aláírás igazolja az MQTT-kapcsolat hitelességét. Az aláírásnak az IoT Hubban az ügyfél konfigurációjában szereplő két hitelesítési kulcs egyikén kell alapulnia. Vagy egy megosztott hozzáférési szabályzat két közös hozzáférési kulcsának egyikén kell alapulnia.
A aláírandó sztringnek a következőképpen kell alakulnia:
{host name}\n
{Client Id}\n
{sas-policy}\n
{sas-at}\n
{sas-expiry}\n
host name
az SNI-bővítményből származik (amelyet az ügyfél a TLS-kézfogás során a Client Hello rekordban mutat be) vagyhost
a csomag felhasználói tulajdonságábólCONNECT
.Client Id
az ügyfélazonosító a csomagbanCONNECT
.sas-policy
- ha van ilyen, meghatározza a hitelesítéshez használt IoT Hub hozzáférési szabályzatot. A csomag felhasználói tulajdonságakéntCONNECT
van kódolva. Nem kötelező: A kihagyás azt jelenti, hogy az eszközregisztrációs adatbázis hitelesítési beállításait használja a rendszer.sas-at
- ha van ilyen, a kapcsolat idejét adja meg – aktuális időpontot. A csomagtípusCONNECT
felhasználói tulajdonságakénttime
van kódolva.sas-expiry
A hitelesítés lejárati idejét határozza meg. Ez egytime
-typed user tulajdonság a csomagonCONNECT
. Ez a tulajdonság kötelező.
Ha nem adja meg az opcionális paramétereket, az üres sztringet kell használni a sztringben az aláíráshoz.
A HMAC-SHA256 a sztring kivonatolására szolgál az eszköz szimmetrikus kulcsainak egyike alapján. A kivonat értéke ezután a tulajdonság értékeként Authentication Data
lesz beállítva.
X509
Ha Authentication Method
a tulajdonság értéke X509
, az IoT Hub a megadott ügyféltanúsítvány alapján hitelesíti a kapcsolatot.
Újrahitelesítés
SAS-alapú hitelesítés használata esetén javasoljuk a rövid élettartamú hitelesítési jogkivonatok használatát. A kapcsolat hitelesítésének megőrzése és a leválasztás megakadályozása a lejárat miatt, az ügyfélnek újrahitelesítenie kell a AUTH
csomagokat (újrahitelesítéssel Reason Code: 0x19
):
-> AUTH
Reason_Code: 0x19
Authentication_Method: SAS
Authentication_Data: {SAS bytes}
sas-at: {current time}
sas-expiry: {SAS expiry time}
Szabályok:
Authentication Method
meg kell egyeznie a kezdeti hitelesítéshez használtval- ha a kapcsolatot eredetileg sas használatával hitelesítették a megosztott hozzáférési szabályzat alapján, az újrahitelesítéshez használt aláírásnak ugyanazon szabályzaton kell alapulnia.
Ha az újrahitelesítés sikeres, az IoT Hub a (sikeres) csomagokat Reason Code: 0x00
küldi AUTH
el. Ellenkező esetben az IoT Hub csomagokat Reason Code: 0x87
küld DISCONNECT
(nincs engedélyezve), és bezárja a kapcsolatot.
Lekapcsolás
A kiszolgáló több okból is leválaszthatja az ügyfelet, például:
- az ügyfél olyan módon helytelenül viselkedik, amelyre nem lehet közvetlenül negatív visszaigazolással (vagy válaszsal) reagálni,
- a kiszolgáló nem tudja naprakészen tartani a kapcsolat állapotát,
- egy másik ügyfél ugyanazzal az identitással csatlakozik.
A kiszolgáló az MQTT 5.0 specifikációban meghatározott bármilyen okkóddal megszakadhat. Említésre méltó említések:
135
(Nincs engedélyezve) ha az újrahitelesítés meghiúsul, az aktuális SAS-jogkivonat lejár, vagy az eszköz hitelesítő adatai módosulnak.142
(Átvett munkamenet) az azonos ügyfélidentitású új kapcsolat megnyitásakor.159
(A csatlakozási sebesség túllépve), ha az IoT Hub csatlakozási sebessége meghaladja a korlátot.131
(Implementációspecifikus hiba) az API-ban definiált egyéni hibákhoz használatos.status
ésreason
a tulajdonságok segítségével további részleteket közölhet a leválasztás okáról (részletekért lásd a Választ ).
Üzemeltetés
Az API minden funkciója műveletként van kifejezve. Íme egy példa a Telemetria küldése műveletre:
-> PUBLISH
QoS: 1
Packet_Id: 3
Topic: $iothub/telemetry
Payload: Hello
<- PUBACK
Packet_Id: 3
Reason_Code: 0
Az API műveleteinek teljes specifikációját lásd: IoT Hub adatsík MQTT 5 API-referencia.
Feljegyzés
Az ebben a specifikációban szereplő összes minta az ügyfél szempontjából jelenik meg. Az aláírás ->
azt jelenti, hogy az ügyfél csomagokat küld, <-
- fogadást.
Üzenettémakörök és előfizetések
Az API műveleti üzeneteiben használt témakörök a következővel $iothub/
kezdődnek: .
Az MQTT-közvetítő szemantikája nem vonatkozik ezekre a műveletekre (részletekért tekintse meg a "$-val kezdődő témakörök" című témakört).
$iothub/
Az API-ban nem definiált témakörök nem támogatottak:
- A nem definiált témakörbe küldött üzenetek válaszként
Not Found
jelennek meg (a részletekért lásd a Választ ), - A nem definiált témakörre való feliratkozás eredménye
SUBACK
Reason Code: 0x8F
a következő: (Érvénytelen témakörszűrő).
A témakörnevek és a tulajdonságnevek megkülönböztetik a kis- és nagybetűket, és pontos egyezésnek kell lenniük. Például nem támogatott, $iothub/telemetry/
amíg $iothub/telemetry
van.
Feljegyzés
Az előfizetések helyettesítő karakterei $iothub/..
nem támogatottak. Vagyis az ügyfél nem tud előfizetni vagy $iothub/+
$iothub/#
. Ha megkísérli ezt megtenni, az eredmény a SUBACK
Reason Code: 0xA2
következő lesz: (A helyettesítő karakterekre vonatkozó előfizetések nem támogatottak). Csak az egyszegmensű helyettesítő karakterek (+
) támogatottak a témakör neve szerinti elérésiút-paraméterek helyett az őket tartalmazó műveletek esetében.
Interakciós típusok
Az API minden művelete két interakciótípus egyikén alapul:
- Nem kötelező nyugtázást tartalmazó üzenet (MessageAck)
- Kérelem-válasz (ReqRep)
A műveletek irányonként is változnak (a kezdeti üzenet iránya határozza meg a csere során):
- Ügyfél–kiszolgáló (c2s)
- Kiszolgálóról ügyfélre (s2c)
A Telemetriai adatok küldése például "Üzenet nyugtával" típusú ügyfél–kiszolgáló művelet, míg a Közvetlen kezelés metódus a kérés-válasz típusú kiszolgáló–ügyfél művelet.
Üzenet-nyugtázási interakciók
Az opcionális nyugtázási (MessageAck) interakcióval rendelkező üzenetek az MQTT-ben történő adatcserét és PUBACK
csomagcserét PUBLISH
fejezik ki. A nyugtázás nem kötelező, és a feladó dönthet úgy, hogy nem kéri azt a csomag elküldésével PUBLISH
a következővel QoS: 0
: .
Feljegyzés
Ha a csomagok tulajdonságait PUBACK
csonkítani kell az ügyfél által deklaráltak miatt Maximum Packet Size
, az IoT Hub annyi felhasználói tulajdonságot őriz meg, amennyit a megadott korláton belül el tud férni. A felsorolt felhasználói tulajdonságok nagyobb eséllyel lesznek elküldve, mint a későbbiek; Reason String
tulajdonság a legkevésbé prioritással rendelkezik.
Példa egyszerű MessageAck-interakcióra
Üzenet:
PUBLISH
QoS: 1
Packet_Id: 34
Topic: $iothub/{request.path}
Payload: <any>
Nyugtázás (siker):
PUBACK
Packet_Id: 34
Reason_Code: 0
Kérelem-válasz interakciók
A Kérés-válasz (ReqRep) interakciókban a Kérés és a Válasz egyaránt a következő csomagokat QoS: 0
fordítja lePUBLISH
: .
Correlation Data
tulajdonságot mindkettőben be kell állítani, és a válaszcsomag kérési csomaghoz való egyeztetésére szolgál.
Ez az API egyetlen választémakört $iothub/responses
használ az összes ReqRep-művelethez. Az ügyfél-kiszolgáló műveletekhez nem szükséges a témakörre való feliratkozás/leiratkozás – a kiszolgáló feltételezi, hogy az összes ügyfél előfizethető.
Példa az egyszerű ReqRep-interakcióra
Kérés:
PUBLISH
QoS: 0
Topic: $iothub/{request.path}
Correlation_Data: 0x01 0xFA
Payload: ...
Válasz (siker):
PUBLISH
QoS: 0
Topic: $iothub/responses
Correlation_Data: 0x01 0xFA
Payload: ...
A ReqRep-interakciók nem támogatják PUBLISH
a kérésként vagy válaszüzenetként küldött QoS: 1
csomagokat. A kérés PUBLISH
küldése válaszra ad Bad Request
választ.
A tulajdonságban Correlation Data
támogatott maximális hossz 16 bájt. Ha Correlation Data
a PUBLISH
csomag tulajdonsága 16 bájtnál hosszabb értékre van állítva, az IoT Hub kimenetellel Bad Request
küld, DISCONNECT
és bezárja a kapcsolatot. Ez a viselkedés csak az API-on belül kicserélt csomagokra vonatkozik.
Feljegyzés
A korrelációs adatok tetszőleges bájtsorrendek, például nem garantáltan UTF-8 sztringek.
A ReqRep előre definiált témaköröket használ válaszként; A Kérelemcsomag PUBLISH
választéma tulajdonsága (ha a feladó állítja be) figyelmen kívül lesz hagyva.
Az IoT Hub automatikusan előfizeti az ügyfelet az összes ügyfél–kiszolgáló ReqRep-műveletre vonatkozó választémakörökre. Még ha az ügyfél kifejezetten le is iratkozik a választémakörről, az IoT Hub automatikusan visszaállítja az előfizetést. A kiszolgálók közötti ReqRep-interakciók esetén az eszköznek továbbra is elő kell fizetnie.
Üzenet tulajdonságai
A műveleti tulajdonságok – rendszer vagy felhasználó által definiált – az MQTT 5 csomagtulajdonságaiként vannak kifejezve.
A felhasználónevek megkülönböztetik a kis- és nagybetűket, és pontosan a megadott módon kell írni őket. Például nem támogatott, Trace-ID
amíg trace-id
van.
A specifikáción kívül, előtag @
nélküli felhasználói tulajdonságokkal rendelkező kérések hibát eredményeznek.
A rendszertulajdonságok első osztályú tulajdonságokként (például Content Type
) vagy felhasználói tulajdonságokként vannak kódolva. A specifikáció a támogatott rendszertulajdonságok teljes listáját tartalmazza.
A rendszer figyelmen kívül hagyja az első osztály összes tulajdonságát, kivéve, ha a specifikáció explicit módon nem támogatja őket.
Ha a felhasználó által definiált tulajdonságok engedélyezettek, a nevüknek a formátumot @{property name}
kell követnie. A felhasználó által definiált tulajdonságok csak az érvényes UTF-8 sztringértékeket támogatják. Az értékeket 15
tartalmazó tulajdonságot például MyProperty1
névvel @MyProperty
és értékkel 15
rendelkező felhasználói tulajdonságként kell kódolni.
Ha az IoT Hub nem ismeri fel a felhasználói tulajdonságot, az hibaüzenetnek minősül, és az IoT Hub (implementációspecifikus hiba) és status: 0100
(hibás kérés) választ PUBACK
Reason Code: 0x83
ad. Ha nem kérték a visszaigazolást (QoS: 0), DISCONNECT
a rendszer visszaküldi az azonos hibát tartalmazó csomagot, és megszakad a kapcsolat.
Ez az API a következő adattípusokat string
határozza meg:
time
: ezredmásodperc óta1970-01-01T00:00:00.000Z
. például:1600987195320
2020-09-24T22:39:55.320Z
u32
: aláíratlan 32 bites egész szám,u64
: aláíratlan 64 bites egész szám,i32
: aláírt 32 bites egész szám.
Válasz
Az interakciók különböző eredményeket eredményezhetnek: Success
, Bad Request
, Not Found
és mások.
Az eredményeket a felhasználói tulajdonság különbözteti status
meg egymástól. Reason Code
a csomagokban PUBACK
(a MessageAck-interakciók esetében) a lehetőség szerint egyezik status
.
Feljegyzés
Ha az ügyfél a CONNECT-csomagban van megadva Request Problem Information: 0
, a rendszer nem küld felhasználói tulajdonságokat a csomagokon PUBACK
, hogy megfeleljenek az MQTT 5 specifikációnak, beleértve a tulajdonságot is status
. Ebben az esetben az ügyfél továbbra is támaszkodhat Reason Code
annak meghatározására, hogy a nyugtázás pozitív vagy negatív-e.
Minden interakciónak van alapértelmezett (vagy sikeres) értéke. Rendelkezik Reason Code
a 0
"nincs beállítva" tulajdonságával és status
tulajdonságával. Egyébként:
- A MessageAck-interakciók
PUBACK
esetében a 0x0 (sikeres) kivételével.Reason Code
status
tulajdonság jelen lehet az eredmény további tisztázása érdekében. - ReqRep-interakciók esetén a Válasz
PUBLISH
tulajdonságkészletet kapstatus
. - Mivel a MessageAck-interakciókra
QoS: 0
nem lehet közvetlenül válaszolni,DISCONNECT
a csomagokat a rendszer válaszinformációkkal, majd a kapcsolat bontásával küldi el.
Példák:
Hibás kérés (MessageAck):
PUBACK
Reason_Code: 131
status: 0100
reason: Unknown property `test`
Nincs engedélyezve (MessageAck):
PUBACK
Reason_Code: 135
status: 0101
Nincs engedélyezve (ReqRep):
PUBLISH
QoS: 0
Topic: $iothub/responses
Correlation_Data: ...
status: 0101
Szükség esetén az IoT Hub a következő felhasználói tulajdonságokat állítja be:
status
- Az IoT Hub kiterjesztett kódja a művelet állapotához. Ez a kód az eredmények megkülönböztetésére használható.trace-id
– a művelet nyomkövetési azonosítója; Az IoT Hub további diagnosztikát tarthat a belső vizsgálathoz használható művelettel kapcsolatban.reason
- ember által olvasható üzenet, amely további információt nyújt arról, hogy a művelet miért került a tulajdonság általstatus
megjelölt állapotba.
Feljegyzés
Ha az ügyfél a CONNECT-csomag tulajdonságát nagyon kis értékre állítja Maximum Packet Size
be, előfordulhat, hogy nem minden felhasználói tulajdonság fér el, és nem jelenik meg a csomagban.
reason
csak személyek számára készült, és nem használható az ügyféllogikában. Ez az API lehetővé teszi, hogy az üzenetek bármikor megváltozjanak figyelmeztetés vagy verziómódosítás nélkül.
Ha az ügyfél CONNECT-csomagban küld, RequestProblemInformation: 0
az MQTT 5 specifikációnkénti nyugtázások nem tartalmazzák a felhasználói tulajdonságokat.
Állapotkód
status
tulajdonság a művelet állapotkódját hordozza. A gépi olvasási hatékonyságra van optimalizálva.
Két bájtból álló, nem aláírt egész számból áll, amely hexaként van kódolva a sztringben, például 0501
.
Kódstruktúra (bittérkép):
7 6 5 4 3 2 1 0 | 7 6 5 4 3 2 1 0
0 0 0 0 0 R T T | C C C C C C C C
Az első bájt a jelzőkhöz használatos:
- A 0. és az 1. bit az eredmények típusát jelzi:
00
-siker01
- ügyfélhiba10
- kiszolgálóhiba
- 2. bit:
1
azt jelzi, hogy a hiba újrapróbálkozható - a 3–7. bitek fenntartottak, és a
0
A második bájt tényleges eltérő válaszkódot tartalmaz. A különböző jelzőkkel rendelkező hibakódok második bájtértékkel rendelkezhetnek. Lehetnek például 0001
0101
0201
0301
különböző jelentéssel rendelkező hibakódok.
Például Too Many Requests
egy ügyfél, újrapróbálkozható hiba a saját kódjával 1
. Értéke vagy 0000 0101 0000 0001
0x0501
.
Az ügyfelek típusbitekkel azonosíthatják, hogy a művelet sikeresen befejeződött-e. Az ügyfelek újrapróbálkozási bitet is használhatnak annak eldöntéséhez, hogy érdemes-e újrapróbálkozási műveletet végrehajtani.
Ajánlások
Munkamenet-kezelés
CONNACK
a packet carrie tulajdonság Session Present
jelzi, hogy a kiszolgáló visszaállította-e a korábban létrehozott munkamenetet. Ezzel a tulajdonságkal megtudhatja, hogy feliratkozik-e a témakörökre, vagy kihagyja a feliratkozást, mivel az előfizetés korábban megtörtént.
A támaszkodáshoz Session Present
az ügyfélnek nyomon kell követnie az általa készített előfizetéseket (azaz az elküldött SUBSCRIBE
csomagokat és a sikeres okkóddal kapott SUBACK
előfizetéseket), vagy mindenképpen elő kell fizetnie az összes témakörre egyetlen SUBSCRIBE
/SUBACK
exchange-ben. Ellenkező esetben, ha az ügyfél két SUBSCRIBE
csomagot küld, és a kiszolgáló csak az egyiket dolgozza fel sikeresen, a kiszolgáló kommunikál CONNACK
Session Present: 1
, miközben az ügyfél előfizetéseinek csak egy részét fogadja el.
Ha meg szeretné akadályozni, hogy az ügyfél régebbi verziója ne iratkozzon fel az összes témakörre, érdemes feltétel nélkül előfizetni az ügyfél viselkedésének változásakor (például a belső vezérlőprogram-frissítés részeként). Emellett annak biztosítása érdekében, hogy ne maradjon elavult előfizetés (a maximálisan engedélyezett számú előfizetést figyelembe véve), kifejezetten leiratkozhat a már nem használt előfizetésekről.
Kötegelés
Nincs speciális formátum az üzenetek kötegének küldéséhez. A TLS-ben és a hálózatkezelésben végzett erőforrás-igényes műveletek többletterhelésének csökkentése érdekében csomagolja össze a csomagokat (PUBLISH
és PUBACK
SUBSCRIBE
így nem), mielőtt átadja őket a mögöttes TLS-/TCP-veremnek. Emellett az ügyfél egyszerűbbé teheti a témakör aliasát a "kötegben":
- Adja meg a teljes témakörnevet a kapcsolat első
PUBLISH
csomagjában, és társítsa hozzá a témakör aliasát, - Helyezze el a következő csomagokat ugyanahhoz a témakörhöz üres témakörnévvel és témaköralias tulajdonsággal.
Migrálás
Ez a szakasz az API korábbi MQTT-támogatáshoz viszonyított változásait sorolja fel.
- A transport protokoll az MQTT 5. Korábban - MQTT 3.1.1.
- Az SAS-hitelesítés környezeti információi közvetlenül a csomagokban
CONNECT
találhatók, nem pedig az aláírással együtt. - A hitelesítési módszer a használt hitelesítési módszer jelzésére szolgál.
- A közös hozzáférésű jogosultságkód a Hitelesítési adatok tulajdonságba kerül. Korábban Jelszó mezőt használtunk.
- A műveletek témakörei eltérőek:
- Telemetria:
$iothub/telemetry
ahelyett, hogydevices/{Client Id}/messages/events
- Parancsok:
$iothub/commands
helyett ,devices/{Client Id}/messages/devicebound
- Patch Twin Reported:
$iothub/twin/patch/reported
ahelyett$iothub/twin/PATCH/properties/reported
, hogy - Az ikerpéldány kívánt állapotának módosítása:
$iothub/twin/patch/desired
helyett.$iothub/twin/PATCH/properties/desired
- Telemetria:
- Az ügyfél-kiszolgáló kérés-válasz műveletek választémaköréhez nincs szükség előfizetésre.
- A felhasználói tulajdonságokat a rendszer a témakörnévszegmensben lévő tulajdonságok kódolása helyett használja.
- A tulajdonságnevek a "dash-case" elnevezési konvencióban vannak megírva a speciális előtaggal rendelkező rövidítések helyett. A felhasználó által definiált tulajdonságokhoz mostantól előtag szükséges. Például, most
message-id
,$.mid
mígmyProperty1
lesz@myProperty1
. - A Korrelációs adatok tulajdonság a témakörbe kódolt tulajdonság helyett a kérés-válasz műveletek kérés- és válaszüzeneteinek
$rid
korrelációjára szolgál. iothub-connection-auth-method
tulajdonság már nem lesz telemetriai eseményekre bélyegzve.- A C2D-parancsok nem törlődnek előfizetés hiányában az eszközről. A várólistán maradnak, amíg az eszköz elő nem iratkozhat, vagy le nem járnak.
Példák
Telemetria küldése
Üzenet:
-> PUBLISH
QoS: 1
Packet_Id: 31
Topic: $iothub/telemetry
@myProperty1: My String Value # optional
creation-time: 1600987195320 # optional
@ No_Rules-ForUser-PROPERTIES: Any UTF-8 string value # optional
Payload: <data>
Elismerés:
<- PUBACK
Packet_Id: 31
Reason_Code: 0
Alternatív nyugtázás (szabályozott):
<- PUBACK
Packet_Id: 31
Reason_Code: 151
status: 0501
Ikerpéldány állapotának elküldése
Kérés:
-> PUBLISH
QoS: 0
Topic: $iothub/twin/get
Correlation_Data: 0x01 0xFA
Payload: <empty>
Válasz (siker):
<- PUBLISH
QoS: 0
Topic: $iothub/responses
Correlation_Data: 0x01 0xFA
Payload: <twin/desired state>
Válasz (nem engedélyezett):
<- PUBLISH
QoS: 0
Topic: $iothub/responses
Correlation_Data: 0x01 0xFA
status: 0102
reason: Operation not allowed for `B2` SKU
Payload: <empty>
Közvetlen metódushívás kezelése
Kérés:
<- PUBLISH
QoS: 0
Topic: $iothub/methods/abc
Correlation_Data: 0x0A 0x10
Payload: <data>
Válasz (siker):
-> PUBLISH
QoS: 0
Topic: $iothub/responses
Correlation_Data: 0x0A 0x10
response-code: 200 # user defined response code
Payload: <data>
Feljegyzés
status
nincs beállítva – ez egy sikeres válasz.
Eszköz nem érhető el válasz:
-> PUBLISH
QoS: 0
Topic: $iothub/responses
Correlation_Data: 0x0A 0x10
status: 0603
Hiba a QoS 0 használata közben, 1. rész
Kérés:
-> PUBLISH
QoS: 0
Topic: $iothub/twin/gett # misspelled topic name - server won't recognize it as Request-Response interaction
Correlation_Data: 0x0A 0x10
Payload: <data>
Válasz:
<- DISCONNECT
Reason_Code: 144
reason: "Unsupported topic: `$iothub/twin/gett`"
Hiba a QoS 0 használata közben, 2. rész
Kérés:
-> PUBLISH # missing Correlation Data
QoS: 0
Topic: $iothub/twin/get
Payload: <data>
Válasz:
<- DISCONNECT
Reason_Code: 131
status: 0100
reason: "`Correlation Data` property is missing"
Következő lépések
- Az MQTT 5 előzetes api-referencia áttekintéséhez tekintse meg az IoT Hub adatsík MQTT 5 API-referencia (előzetes verzió) című témakörét.
- C#-minta követéséhez tekintse meg a GitHub-mintaadattárat.