Megosztás a következőn keresztül:


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 az 1.
  • 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 Alive19 min legfeljebb (az élőség ellenőrzésének maximális késleltetése – 28.5 min).
  • Topic Alias Maximum az 10.
  • Response Information nem támogatott; CONNACK tulajdonságot akkor sem ad vissza Response Information , ha CONNECT tulajdonságot tartalmaz Request Response Information .
  • Receive Maximum (az engedélyezett ki nem fedezett PUBLISH csomagok maximális száma (ügyfél-kiszolgáló irányban) a következővel QoS: 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ések 0x97 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 a Authentication Method. Ha Authentication Method a beállítás SASértéke , akkor Authentication 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 rekordban
  • sas-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ában CONNECT" 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) vagy host a csomag felhasználói tulajdonságából CONNECT .
  • Client Id az ügyfélazonosító a csomagban CONNECT .
  • 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ént CONNECT 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ípus CONNECT felhasználói tulajdonságaként time van kódolva.
  • sas-expiry A hitelesítés lejárati idejét határozza meg. Ez egy time-typed user tulajdonság a csomagon CONNECT . 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 és reason 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: 0fordí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 15rendelkező 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 stringhatározza meg:

  • time: ezredmásodperc óta 1970-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 kap status .
  • 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 által status 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 -siker
    • 01 - ügyfélhiba
    • 10 - 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 0001010102010301 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 Presentaz ü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 PUBACKSUBSCRIBEí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, hogy devices/{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
  • 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, mostmessage-id, $.mid míg myProperty1 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