Stöd för IoT Hub MQTT 5 (inaktuell)

Version: 2.0 api-version: 2020-10-01-preview

Det här dokumentet definierar IoT Hub-dataplans-API:et över MQTT version 5.0-protokollet. Se API-referens för fullständiga definitioner i det här API:et.

Förutsättningar

• Skapa en helt ny IoT-hubb med förhandsgranskningsläget aktiverat. MQTT 5 är bara tillgängligt i förhandsgranskningsläge och du kan inte växla en befintlig IoT-hubb till förhandsgranskningsläge. Mer information finns i Aktivera förhandsgranskningsläge
• Förkunskaper om MQTT 5-specifikation.

Stödnivå och begränsningar

IoT Hub-stöd för MQTT 5 är i förhandsversion och begränsat på följande sätt (förmedlas till klienten via CONNACK egenskaper om inget annat uttryckligen anges):

• Inget officiellt stöd för Azure IoT-enhets-SDK:er ännu.
• Prenumerationsidentifierare stöds inte.
• Delade prenumerationer stöds inte.
• RETAIN stöds inte.
• Maximum QoS är 1.
• Maximum Packet Size är 256 KiB (omfattas av ytterligare begränsningar per åtgärd).
• Tilldelade klient-ID:t stöds inte.
• Keep Alive är begränsad till 19 min (maximal fördröjning för liveness check – 28.5 min).
• Topic Alias Maximum är 10.
• Response Information stöds inte. CONNACK returnerar Response Information inte egenskapen även om CONNECT den innehåller Request Response Information egenskapen.
• Receive Maximum (det maximala antalet tillåtna utestående obemärkta PUBLISH paket (i klient-server-riktning) med QoS: 1) är 16.
• En enskild klient får inte ha fler än 50 prenumerationer. Om en klient når prenumerationsgränsen SUBACK returnerar 0x97 orsakskoden (Kvoten har överskridits) för prenumerationer.

Anslutningslivscykel

Connection

Om du vill ansluta en klient till IoT Hub med hjälp av det här API:et upprättar du en anslutning enligt MQTT 5-specifikationen. Klienten måste skicka CONNECT paket inom 30 sekunder efter lyckad TLS-handskakning, eller så stänger servern anslutningen. Här är ett exempel på CONNECT paket:

-> 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 -egenskapen krävs och identifierar vilken autentiseringsmetod som används. Mer information om autentiseringsmetod finns i Autentisering.
• Authentication Data egenskapshantering beror på Authentication Method. Om Authentication Method är inställt på SASAuthentication Data krävs och måste innehålla en giltig signatur. Mer information om autentiseringsdata finns i Autentisering.
• api-version egenskapen krävs och måste anges till API-versionsvärdet som anges i den här specifikationens huvud för att den här specifikationen ska gälla.
• host egenskapen definierar klientorganisationens värdnamn. Det krävs om inte SNI-tillägget presenterades i Client Hello-posten under TLS-handskakning
• sas-at definierar tiden för anslutningen.
• sas-expiry definierar förfallotid för den angivna SAS:en.
• client-agent om du vill kommunicera information om klienten som skapar anslutningen.

IoT Hub svarar med CONNACK paket när det har slutförts med autentisering och hämtar data för att stödja anslutningen. Om anslutningen har upprättats CONNACK ser det ut så här:

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

Dessa CONNACK paketegenskaper följer MQTT 5-specifikationen. De återspeglar IoT Hubs funktioner.

Autentisering

Egenskapen Authentication Method på CONNECT klienten definierar vilken typ av autentisering den använder för den här anslutningen:

• SAS - Signatur för delad åtkomst anges i CONNECTegenskapen ' s Authentication Data ,
• X509 – klienten förlitar sig på klientcertifikatautentisering.

Autentiseringen misslyckas om autentiseringsmetoden inte matchar klientens konfigurerade metod i IoT Hub.

Autentisering med användarnamn och lösenord som används i tidigare API-versioner stöds inte.

SAS

Med SAS-baserad autentisering måste en klient ange anslutningskontextens signatur. Signaturen visar att MQTT-anslutningen är äkta. Signaturen måste baseras på en av två autentiseringsnycklar i klientens konfiguration i IoT Hub. Eller så måste den baseras på en av två nycklar för delad åtkomst i en princip för delad åtkomst.

Den sträng som ska signeras måste skapas på följande sätt:

{host name}\n
{Client Id}\n
{sas-policy}\n
{sas-at}\n
{sas-expiry}\n

• host name härleds antingen från SNI-tillägget (presenteras av klienten i Client Hello-posten under TLS-handskakning) eller host användaregenskapen i CONNECT paketet.
• Client Id är klientidentifierare i CONNECT paket.
• sas-policy – om det finns definierar IoT Hub-åtkomstprincipen som används för autentisering. Den kodas som användaregenskap för CONNECT paket. Valfritt: om du utelämnar det innebär det att autentiseringsinställningar i enhetsregistret används i stället.
• sas-at – om det finns anger tidpunkten för anslutningen – aktuell tid. Den kodas som användaregenskap av time typen på CONNECT paket.
• sas-expiry definierar förfallotid för autentiseringen. Det är en time-typad användaregenskap för CONNECT paket. Egenskapen krävs.

För valfria parametrar, om utelämnas, måste den tomma strängen användas i stället i strängen för att signera.

HMAC-SHA256 används för att hash-strängen baserat på en av enhetens symmetriska nycklar. Hash-värdet anges sedan som egenskapsvärde Authentication Data .

X509

Om Authentication Method egenskapen är inställd X509på autentiserar IoT Hub anslutningen baserat på det angivna klientcertifikatet.

Autentisering igen

Om SAS-baserad autentisering används rekommenderar vi att du använder kortlivade autentiseringstoken. Om du vill behålla anslutningen autentiserad och förhindra frånkoppling på grund av förfallodatum måste klienten autentisera igen genom att skicka AUTH paket med Reason Code: 0x19 (omautentisering):

-> AUTH
    Reason_Code: 0x19
    Authentication_Method: SAS
    Authentication_Data: {SAS bytes}
    sas-at: {current time}
    sas-expiry: {SAS expiry time}

Regler:

• Authentication Method måste vara samma som för den första autentiseringen
• Om anslutningen ursprungligen autentiserades med SAS baserat på principen för delad åtkomst måste signaturen som används i omautentisering baseras på samma princip.

Om omautentiseringen lyckas skickar AUTH IoT Hub paket med Reason Code: 0x00 (lyckades). Annars skickar DISCONNECT IoT Hub paket med Reason Code: 0x87 (inte auktoriserad) och stänger anslutningen.

Frånkoppling

Servern kan koppla från klienten av några orsaker, bland annat:

• klienten beter sig felaktigt på ett sätt som är omöjligt att svara på med negativ bekräftelse (eller svar) direkt,
• servern kan inte hålla anslutningens tillstånd uppdaterat,
• en annan klient ansluter med samma identitet.

Servern kan koppla från med all orsakskod som definierats i MQTT 5.0-specifikationen. Anmärkningsvärda omnämnanden:

• 135 (Inte auktoriserad) när omautentiseringen misslyckas, den aktuella SAS-token upphör att gälla eller enhetens autentiseringsuppgifter ändras.
• 142 (Sessionen övertogs) när en ny anslutning med samma klientidentitet har öppnats.
• 159 (Anslutningshastigheten överskreds) när anslutningsfrekvensen för IoT-hubben överskrider gränsen.
• 131 (Implementeringsspecifikt fel) används för alla anpassade fel som definierats i det här API:et. status och reason egenskaper används för att förmedla ytterligare information om orsaken till frånkoppling (se Svar för mer information).

Operations

Alla funktioner i det här API:et uttrycks som åtgärder. Här är ett exempel på åtgärden Skicka telemetri:

-> PUBLISH
    QoS: 1
    Packet_Id: 3
    Topic: $iothub/telemetry
    Payload: Hello

<- PUBACK
    Packet_Id: 3
    Reason_Code: 0

Fullständig specifikation av åtgärder i det här API :et finns i API-referensen för IoT Hub-dataplanet MQTT 5.

Meddelandeämnen och prenumerationer

Ämnen som används i åtgärders meddelanden i det här API:et börjar med $iothub/. MQTT Broker-semantik gäller inte för dessa åtgärder (se "Ämnen som börjar med $" för mer information). Ämnen som börjar med $iothub/ som inte har definierats i det här API:et stöds inte:

• Skicka meddelanden till odefinierat ämne resulterar i Not Found svar (se Svar för mer information),
• Att prenumerera på odefinierat ämne resulterar i SUBACK Reason Code: 0x8F (ämnesfiltret är ogiltigt).

Ämnesnamn och egenskapsnamn är skiftlägeskänsliga och måste överensstämma exakt. Till exempel $iothub/telemetry/ stöds inte när $iothub/telemetry är.

Interaktionstyper

Alla åtgärder i det här API:et baseras på en av två interaktionstyper:

• Meddelande med valfri bekräftelse (MessageAck)
• Begärandesvar (ReqRep)

Åtgärderna varierar också beroende på riktning (bestäms av riktningen för det inledande meddelandet i utbyte):

• Klient-till-server (c2s)
• Server-till-klient (s2c)

Till exempel är Send Telemetry en klient-till-server-åtgärd av typen "Meddelande med bekräftelse", medan Hantera direktmetod är server-till-klient-åtgärd av typen Request-Response.

Interaktion med meddelandebekrästning

Meddelande med valfri bekräftelseinteraktion (MessageAck) uttrycks som ett utbyte av PUBLISH och PUBACK paket i MQTT. Bekräftelse är valfritt och avsändaren kan välja att inte begära det genom att skicka PUBLISH paket med QoS: 0.

Exempel på enkel MessageAck-interaktion

Meddelande:

PUBLISH
    QoS: 1
    Packet_Id: 34
    Topic: $iothub/{request.path}
    Payload: <any>

Bekräftelse (lyckad):

PUBACK
    Packet_Id: 34
    Reason_Code: 0

Interaktioner med begärandesvar

I ReqRep-interaktioner (Request-Response) översätts både Begäran och Svar till PUBLISH paket med QoS: 0.

Correlation Data egenskapen måste anges i båda och används för att matcha svarspaket med begärandepaket.

Det här API:et använder ett enda svarsavsnitt $iothub/responses för alla ReqRep-åtgärder. Prenumeration på/avprenumerering från det här avsnittet för klient-till-server-åtgärder krävs inte – servern förutsätter att alla klienter prenumererar.

Exempel på enkel ReqRep-interaktion

Begäran:

PUBLISH
    QoS: 0
    Topic: $iothub/{request.path}
    Correlation_Data: 0x01 0xFA
    Payload: ...

Svar (lyckades):

PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: 0x01 0xFA
    Payload: ...

ReqRep-interaktioner stöder PUBLISH inte paket med QoS: 1 som begärande- eller svarsmeddelanden. Skicka begäranderesultat PUBLISH som Bad Request svar.

Maximal längd som stöds i Correlation Data egenskapen är 16 byte. Om Correlation Data egenskapen för PUBLISH paket har angetts till ett värde som är längre än 16 byte skickar DISCONNECT IoT Hub utfallet Bad Request och stänger anslutningen. Det här beteendet gäller endast paket som utbyts i det här API:et.

IoT Hub prenumererar automatiskt på klient till svarsämnen för alla ReqRep-åtgärder från klient till server. Även om klienten uttryckligen avregistrerar sig från svarsämnet återställer IoT Hub prenumerationen automatiskt. För reqRep-interaktioner från server till klient är det fortfarande nödvändigt att enheten prenumererar.

Meddelandeegenskaper

Åtgärdsegenskaper – system eller användardefinierade – uttrycks som paketegenskaper i MQTT 5.

Namn på användaregenskaper är skiftlägeskänsliga och måste stavas exakt enligt definitionen. Till exempel Trace-ID stöds inte när trace-id är.

Begäranden med användaregenskaper utanför specifikationen och utan prefix @ resulterar i fel.

Systemegenskaper kodas antingen som förstklassiga egenskaper (till exempel Content Type) eller som användaregenskaper. Specifikationen innehåller en fullständig lista över systemegenskaper som stöds. Alla förstklassiga egenskaper ignoreras om inte stöd för dem uttryckligen anges i specifikationen.

Där användardefinierade egenskaper tillåts måste deras namn följa formatet @{property name}. Användardefinierade egenskaper stöder endast giltiga UTF-8-strängvärden. Till exempel MyProperty1 måste egenskapen med värdet 15 kodas som Användaregenskap med namn @MyProperty och värde 15.

Om IoT Hub inte känner igen användaregenskapen anses det vara ett fel och IoT Hub svarar med PUBACK Reason Code: 0x83 (implementeringsspecifikt fel) och status: 0100 (felaktig begäran). Om bekräftelse inte begärdes (QoS: 0) DISCONNECT skickas paket med samma fel tillbaka och anslutningen avslutas.

Det här API:et definierar följande datatyper förutom string:

• time: antal millisekunder sedan 1970-01-01T00:00:00.000Z. till exempel 1600987195320 för 2020-09-24T22:39:55.320Z,
• u32: osignerat 32-bitars heltalsnummer,
• u64: osignerat 64-bitars heltalsnummer,
• i32: signerat 32-bitars heltalsnummer.

Response

Interaktioner kan resultera i olika resultat: Success, Bad Request, Not Foundoch andra. Utfall skiljer sig från varandra efter status användaregenskap. Reason Code i PUBACK paket (för MessageAck-interaktioner) matchar status i den mening där det är möjligt.

Varje interaktion har en standard (eller lyckades). Den har Reason Code 0 egenskapen och status för "not set". Annars:

• För MessageAck-interaktioner PUBACK hämtar Reason Code andra än 0x0 (lyckades). status egendom kan finnas för att ytterligare klargöra resultatet.
• För ReqRep-interaktioner hämtar status Response PUBLISH egenskapsuppsättning.
• Eftersom det inte finns något sätt att svara på MessageAck-interaktioner med QoS: 0 direkt DISCONNECT skickas paketet i stället med svarsinformation följt av frånkoppling.

Exempel:

Felaktig begäran (MessageAck):

PUBACK
    Reason_Code: 131
    status: 0100
    reason: Unknown property `test`

Ej auktoriserad (MessageAck):

PUBACK
    Reason_Code: 135
    status: 0101

Ej auktoriserad (ReqRep):

PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: ...
    status: 0101

Vid behov anger IoT Hub följande användaregenskaper:

• status – IoT Hubs utökade kod för åtgärdens status. Den här koden kan användas för att särskilja utfall.
• trace-id – spårnings-ID för åtgärden. IoT Hub kan behålla mer diagnostik om den åtgärd som kan användas för intern undersökning.
• reason - Mänskligt läsbart meddelande som ger ytterligare information om varför åtgärden hamnade i ett tillstånd som anges av status egenskapen.

Statuskod

status egenskapen har statuskod för åtgärden. Den är optimerad för maskinläsningseffektivitet. Den består av ett osignerat heltal med två byte kodat som hex i sträng som 0501. Kodstruktur (bitkarta):

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

Första byte används för flaggor:

• bits 0 och 1 anger typ av utfall:
  • 00 -framgång
  • 01 – klientfel
  • 10 – serverfel
• bit 2: 1 anger att felet kan försökas igen
• bitar 3 till 7 är reserverade och måste anges till 0

Andra byte innehåller faktisk distinkt svarskod. Felkoder med olika flaggor kan ha samma andra bytevärde. Det kan till exempel finnas 0001, 0101, 0201, 0301 felkoder som har en distinkt betydelse.

Är till exempel Too Many Requests en klient, ett nytt försöksfel med egen kod för 1. Dess värde är 0000 0101 0000 0001 eller 0x0501.

Klienter kan använda typbitar för att identifiera om åtgärden har slutförts. Klienter kan också använda återförsöksbar bit för att avgöra om det är lämpligt att försöka igen.

Rekommendationer

Sessionshantering

CONNACK packet carries Session Present property för att ange om servern har återställts tidigare skapad session. Använd den här egenskapen för att ta reda på om du vill prenumerera på ämnen eller hoppa över prenumerationen sedan prenumerationen gjordes tidigare.

Om du vill förlita dig på måste klienten hålla reda på Session Presentprenumerationer som den har skapat (dvs. skickat SUBSCRIBE paket och tagits emot SUBACK med lyckad orsakskod) eller se till att prenumerera på alla ämnen i ett enda SUBSCRIBE/SUBACK utbyte. Annars, om klienten skickar två SUBSCRIBE paket och servern endast bearbetar ett av dem, kommunicerar Session Present: 1 servern in CONNACK samtidigt som endast en del av klientens prenumerationer accepteras.

För att förhindra att en äldre version av klienten inte prenumererar på alla ämnen är det bättre att prenumerera villkorslöst när klientbeteendet ändras (till exempel som en del av uppdateringen av inbyggd programvara). För att säkerställa att inga inaktuella prenumerationer lämnas kvar (från maximalt antal tillåtna prenumerationer) avbryter du uttryckligen prenumerationer som inte längre används.

Batchbearbetning

Det finns inget särskilt format för att skicka en batch med meddelanden. Om du vill minska kostnaderna för resursintensiva åtgärder i TLS och nätverk paketerar du paket (PUBLISH, PUBACK, SUBSCRIBEoch så nej) innan de överlämnas till den underliggande TLS/TCP-stacken. Klienten kan också göra ämnesalias enklare i "batchen":

• Placera fullständigt ämnesnamn i det första PUBLISH paketet för anslutningen och associera ämnesalias med det.
• Placera följande paket för samma ämne med tom ämnesnamn och ämnesaliasegenskap.

Migrering

I det här avsnittet visas ändringar i API:et jämfört med tidigare MQTT-stöd.

• Transportprotokollet är MQTT 5. Tidigare – MQTT 3.1.1.
• Kontextinformation för SAS-autentisering finns i paketet direkt i CONNECT stället för att kodas tillsammans med signaturen.
• Autentiseringsmetod används för att ange vilken autentiseringsmetod som används.
• Signatur för delad åtkomst placeras i egenskapen Autentiseringsdata. Tidigare användes fältet Lösenord.
• Ämnen för åtgärder skiljer sig åt:
  • Telemetri: $iothub/telemetry i stället devices/{Client Id}/messages/eventsför ,
  • Kommandon: $iothub/commands i stället devices/{Client Id}/messages/deviceboundför ,
  • Patch Twin Reported: $iothub/twin/patch/reported i stället $iothub/twin/PATCH/properties/reportedför ,
  • Meddela önskat tvillingtillstånd har ändrats: $iothub/twin/patch/desired i stället $iothub/twin/PATCH/properties/desiredför .
• Prenumeration för svarsämnet för klient-server-begäran-svar krävs inte.
• Användaregenskaper används i stället för att koda egenskaper i ämnesnamnssegmentet.
• egenskapsnamn stavas i namngivningskonventionen "dash-case" i stället för förkortningar med specialprefix. Användardefinierade egenskaper kräver nu prefix i stället. Till exempel $.mid är nu message-id, medan myProperty1 blir @myProperty1.
• Korrelationsdataegenskapen används för att korrelera begärande- och svarsmeddelanden för åtgärder för begärandesvar i stället för $rid egenskapen som kodas i ämnet.
• iothub-connection-auth-method egenskapen är inte längre stämplad på telemetrihändelser.
• C2D-kommandon rensas inte i avsaknad av prenumeration från enheten. De förblir i kö tills enheten prenumererar eller upphör att gälla.

Exempel

Skicka telemetri

Meddelande:

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

Bekräftelse:

<- PUBACK
    Packet_Id: 31
    Reason_Code: 0

Alternativ bekräftelse (begränsad):

<- PUBACK
    Packet_Id: 31
    Reason_Code: 151
    status: 0501

---

Skicka get twin's state

Begäran:

-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/get
    Correlation_Data: 0x01 0xFA
    Payload: <empty>

Svar (lyckades):

<- PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: 0x01 0xFA
    Payload: <twin/desired state>

Svar (tillåts inte):

<- PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: 0x01 0xFA
    status: 0102
    reason: Operation not allowed for `B2` SKU
    Payload: <empty>

---

Hantera direkt metodanrop

Begäran:

<- PUBLISH
    QoS: 0
    Topic: $iothub/methods/abc
    Correlation_Data: 0x0A 0x10
    Payload: <data>

Svar (lyckades):

-> PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: 0x0A 0x10
    response-code: 200 # user defined response code
    Payload: <data>

Svar om att enheten inte är tillgänglig:

-> PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: 0x0A 0x10
    status: 0603

---

Fel vid användning av QoS 0, del 1

Begäran:

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

Svar:

<- DISCONNECT
    Reason_Code: 144
    reason: "Unsupported topic: `$iothub/twin/gett`"

---

Fel vid användning av QoS 0, del 2

Begäran:

-> PUBLISH # missing Correlation Data
    QoS: 0
    Topic: $iothub/twin/get
    Payload: <data>

Svar:

<- DISCONNECT
    Reason_Code: 131
    status: 0100
    reason: "`Correlation Data` property is missing"

Nästa steg

• Om du vill granska API-referensen för förhandsversionen av MQTT 5 läser du IoT Hub-dataplanets MQTT 5 API-referens (förhandsversion).
• Om du vill följa ett C#-exempel läser du GitHub-exempellagringsplatsen.