Delen via

Ondersteuning voor IoT Hub MQTT 5 (afgeschaft)

Versie: 2.0 api-versie: 2020-10-01-preview

In dit document wordt de IoT Hub-gegevensvlak-API gedefinieerd via het MQTT-protocol van versie 5.0. Zie API-naslaginformatie voor volledige definities in deze API.

Notitie

MQTT 5-ondersteuning in IoT Hub is afgeschaft en IoT Hub heeft beperkte functieondersteuning voor MQTT. Als voor uw oplossing MQTT v3.1.1- of v5-ondersteuning nodig is, wordt MQTT-ondersteuning aanbevolen in Azure Event Grid. Zie MQTT-ondersteuning vergelijken in IoT Hub en Event Grid voor meer informatie.

Benodigdheden

Niveau van ondersteuning en beperkingen

IoT Hub-ondersteuning voor MQTT 5 is in preview en beperkt op de volgende manieren (aan de client doorgegeven via CONNACK eigenschappen, tenzij expliciet anders vermeld):

  • Er worden nog geen officiële Sdk's voor Azure IoT-apparaten ondersteund.
  • Abonnements-id's worden niet ondersteund.
  • Gedeelde abonnementen worden niet ondersteund.
  • RETAIN wordt niet ondersteund.
  • Maximum QoS is 1.
  • Maximum Packet Size is 256 KiB (onderhevig aan verdere beperkingen per operatie).
  • Toegewezen client-id's worden niet ondersteund.
  • Keep Alive is beperkt tot 19 min (maximale vertraging voor levendigheidscontrole – 28.5 min).
  • Topic Alias Maximum is 10.
  • Response Information wordt niet ondersteund; CONNACK retourneert geen Response Information eigenschap, zelfs niet als CONNECT deze eigenschap bevat Request Response Information .
  • Receive Maximum (maximum aantal toegestane niet-bevestigde PUBLISH pakketten (in de client-server-richting) met QoS: 1) is 16.
  • Eén client mag niet meer dan 50 abonnementen hebben. Als een client de abonnementsgrens bereikt, retourneert SUBACK0x97 de redencode voor abonnementen (Quotum overschreden).

Verbindingslevenscyclus

Verbinding

Als u een client wilt verbinden met IoT Hub met behulp van deze API, maakt u een verbinding per MQTT 5-specificatie. De client moet het pakket binnen 30 seconden verzenden CONNECT na geslaagde TLS-handshake of de server sluit de verbinding. Hier volgt een voorbeeld van een CONNECT-pakket:

-> 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 eigenschap is vereist en identificeert welke verificatiemethode wordt gebruikt. Zie Verificatie voor meer informatie over de verificatiemethode.
  • Authentication Data verwerking van eigenschappen hangt af van Authentication Method. Als Authentication Method is ingesteld op SAS, dan is Authentication Data vereist en moet het een geldige handtekening bevatten. Zie Verificatie voor meer informatie over verificatiegegevens.
  • api-version eigenschap is vereist en moet worden ingesteld op API-versiewaarde die is opgegeven in de header van deze specificatie om deze specificatie toe te passen.
  • host de eigenschap definieert de hostnaam van de tenant. Dit is vereist tenzij de SNI-extensie is gepresenteerd in de Client Hello-record tijdens de TLS-handshake.
  • sas-at definieert de tijd van de verbinding.
  • sas-expiry definieert de verlooptijd voor de opgegeven SAS.
  • client-agent optioneel communiceert informatie over de client die de verbinding maakt.

Notitie

Authentication Method en andere eigenschappen in de specificatie met hoofdletters zijn eersteklas eigenschappen in MQTT 5- ze worden beschreven in details in MQTT 5-specificatie. api-version en andere eigenschappen in dash case zijn gebruikerseigenschappen die specifiek zijn voor ioT Hub-API.

IoT Hub reageert met CONNACK pakket zodra het is voltooid met verificatie en het ophalen van gegevens ter ondersteuning van de verbinding. Als de verbinding tot stand is gebracht, CONNACK ziet er als volgt uit:

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

Deze CONNACK pakketeigenschappen volgen de MQTT 5-specificatie. Ze weerspiegelen de mogelijkheden van IoT Hub.

Authenticatie

De Authentication Method eigenschap op CONNECT de client definieert welk type verificatie wordt gebruikt voor deze verbinding:

  • SAS - Shared Access Signature wordt verstrekt in de CONNECT eigenschap van Authentication Data.
  • X509 - client vertrouwt op authenticatie met cliëntcertificaten.

Verificatie mislukt als de verificatiemethode niet overeenkomt met de geconfigureerde methode van de client in IoT Hub.

Notitie

Voor deze API moet Authentication Method de eigenschap in CONNECT het pakket worden ingesteld. Als de eigenschap Authentication Method niet is opgegeven, mislukt de verbinding met de Bad Request respons.

Verificatie van gebruikersnaam/wachtwoord die in eerdere API-versies wordt gebruikt, wordt niet ondersteund.

SAS

Met verificatie op basis van SAS moet een client de handtekening van de verbindingscontext opgeven. De handtekening bewijst echtheid van de MQTT-verbinding. De handtekening moet zijn gebaseerd op een van de twee verificatiesleutels in de configuratie van de client in IoT Hub. Of deze moet zijn gebaseerd op een van de twee gedeelde toegangssleutels van een beleid voor gedeelde toegang.

De te ondertekenen tekenreeks moet als volgt worden gevormd:

{host name}\n
{Client Id}\n
{sas-policy}\n
{sas-at}\n
{sas-expiry}\n
  • host name wordt afgeleid van de SNI-extensie (gepresenteerd door de client in het Client Hello-record tijdens de TLS-handshake) of de host gebruikerseigenschap in het CONNECT pakket.
  • Client Id is een client-ID in CONNECT pakket.
  • sas-policy - indien aanwezig, definieert u ioT Hub-toegangsbeleid dat wordt gebruikt voor verificatie. Het wordt gecodeerd als gebruikerseigenschap op CONNECT pakket. Optioneel: als u dit weglaat, worden in plaats daarvan verificatie-instellingen in het apparaatregister gebruikt.
  • sas-at - indien aanwezig, geeft u de tijd van de verbinding - huidige tijd. Het is gecodeerd als een gebruikerseigenschap van type time op pakket CONNECT.
  • sas-expiry definieert de verlooptijd voor de verificatie. Het is een time-getypt gebruikerskenmerk op CONNECT pakket. Deze eigenschap is vereist.

Als u optionele parameters weglaat, moet in plaats daarvan een lege tekenreeks worden gebruikt om te ondertekenen.

HMAC-SHA256 wordt gebruikt om de tekenreeks te hashen op basis van een van de symmetrische sleutels van het apparaat. Hash-waarde wordt vervolgens ingesteld als waarde van Authentication Data eigenschap.

X509

Als Authentication Method de eigenschap is ingesteld op X509, verifieert IoT Hub de verbinding op basis van het opgegeven clientcertificaat.

Verificatie opnieuw

Als verificatie op basis van SAS wordt gebruikt, raden we u aan om kortdurende verificatietokens te gebruiken. Om de verbinding geverifieerd te houden en te voorkomen dat de verbinding wordt verbroken vanwege de vervaldatum, moet de client opnieuw verifiëren door een pakket te verzenden AUTH met Reason Code: 0x19 (verificatie opnieuw):

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

Regels:

  • Authentication Method moet hetzelfde zijn als degene die wordt gebruikt voor de eerste verificatie
  • als de verbinding oorspronkelijk is geverifieerd met sas op basis van beleid voor gedeelde toegang, moet de handtekening die wordt gebruikt bij opnieuw verifiëren, zijn gebaseerd op hetzelfde beleid.

Als herauthenticatie slaagt, verzendt IoT Hub AUTH pakket met Reason Code: 0x00 (succes). Anders verstuurt IoT Hub een DISCONNECT pakket met Reason Code: 0x87 (niet geautoriseerd) en sluit de verbinding.

Onderbreking

De server kan de verbinding met de client verbreken om enkele redenen, waaronder:

  • Cliënt heeft zich zodanig misdragen dat er niet direct kan worden gereageerd met een negatieve ontkenning (of reactie).
  • server kan de status van de verbinding niet up-to-date houden,
  • een andere client maakt verbinding met dezelfde identiteit.

De server kan de verbinding verbreken met een redencode die is gedefinieerd in de MQTT 5.0-specificatie. Belangrijke vermeldingen:

  • 135 (Niet geautoriseerd) wanneer opnieuw verificatie mislukt, verloopt het huidige SAS-token of worden de referenties van het apparaat gewijzigd.
  • 142 (Sessie overgenomen) wanneer er een nieuwe verbinding met dezelfde clientidentiteit is geopend.
  • 159 (Verbindingssnelheid overschreden) wanneer de verbindingssnelheid voor de IoT-hub de limiet overschrijdt.
  • 131 (Implementatiespecifieke fout) wordt gebruikt voor aangepaste fouten die in deze API zijn gedefinieerd. status en reason eigenschappen worden gebruikt om meer informatie over de oorzaak van de verbinding te communiceren (zie Antwoord voor meer informatie).

Bedrijfsactiviteiten

Alle functionaliteiten in deze API worden uitgedrukt als bewerkingen. Hier volgt een voorbeeld van de bewerking Telemetrie verzenden:

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

<- PUBACK
    Packet_Id: 3
    Reason_Code: 0

Voor de volledige specificatie van bewerkingen in deze API, zie IoT Hub-gegevensvlak MQTT 5 API-verwijzing.

Notitie

Alle voorbeelden in deze specificatie worden vanuit het perspectief van de client weergegeven. Symbool -> betekent dat de client een pakket verzendt, <- betekent dat er een pakket wordt ontvangen.

Berichtonderwerpen en abonnementen

Onderwerpen die in de berichten van bewerkingen in deze API worden gebruikt, beginnen met $iothub/. Semantiek van MQTT-broker is niet van toepassing op deze bewerkingen (zie Onderwerpen die beginnen met $) voor meer informatie. Onderwerpen die beginnen met $iothub/ die niet zijn gedefinieerd in deze API, worden niet ondersteund:

  • Berichten verzenden naar niet-gedefinieerde onderwerpresultaten in Not Found antwoord (zie Antwoord voor meer informatie)
  • Abonneren op niet-gedefinieerde onderwerpresultaten SUBACK met Reason Code: 0x8F (onderwerpfilter ongeldig).

Onderwerpnamen en eigenschapsnamen zijn hoofdlettergevoelig en moeten exact overeenkomen met elkaar. Bijvoorbeeld, $iothub/telemetry/ wordt niet ondersteund terwijl $iothub/telemetry wel wordt ondersteund.

Notitie

Jokertekens in abonnementen onder $iothub/.. worden niet ondersteund. Dat wil gezegd, een client kan zich niet abonneren op $iothub/+ of $iothub/#. Als u dit probeert, leidt dit tot SUBACK met Reason Code: 0xA2 (jokertekenabonnementen worden niet ondersteund). Alleen jokertekens met één segment (+) worden ondersteund in plaats van padparameters in de onderwerpnaam voor bewerkingen die deze bevatten.

Interactietypen

Alle bewerkingen in deze API zijn gebaseerd op een van de twee interactietypen:

  • Bericht met optionele ontvangstbevestiging (MessageAck)
  • Request-Response (ReqRep) - Verzoek-Antwoord

Bewerkingen variëren ook per richting (afhankelijk van de richting van het eerste bericht in exchange):

  • Client-naar-server (c2s)
  • Server - naar - client (s2c)

Verzenden van Telemetrie is bijvoorbeeld een client-server-bewerking van het type Bericht met Bevestiging, terwijl Directe Methode Verwerken een server-client-bewerking van het aanvraag-antwoordtype is.

Interacties bij ontvangstbevestiging van berichten

Bericht met optionele bevestigingsinteractie (MessageAck) wordt uitgedrukt als een uitwisseling van PUBLISH en PUBACK pakketten in MQTT. Bevestiging is optioneel en afzender kan ervoor kiezen om het niet aan te vragen door pakket te verzenden PUBLISH met QoS: 0.

Notitie

Als eigenschappen in PUBACK-pakket moeten worden afgekort vanwege Maximum Packet Size zoals opgegeven door de client, zal IoT Hub zoveel gebruiker-eigenschappen behouden als er binnen de opgegeven limiet passen. Gebruikerseigenschappen die eerst worden vermeld, hebben een hogere kans om te worden verzonden dan die later worden vermeld; Reason String eigenschap heeft de minste prioriteit.

Voorbeeld van eenvoudige MessageAck-interactie

Bericht:

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

Succesmelding (geslaagd)

PUBACK
    Packet_Id: 34
    Reason_Code: 0

Interacties tussen aanvragen en antwoorden

In ReqRep-interacties (Request-Response) worden zowel Request als Response omgezet in PUBLISH pakketten met QoS: 0.

Correlation Data de eigenschap moet worden ingesteld in beide en wordt gebruikt om het antwoordpakket aan het aanvraagpakket te koppelen.

Deze API maakt gebruik van één antwoordonderwerp $iothub/responses voor alle ReqRep-bewerkingen. Abonneren op/afmelden bij dit onderwerp voor client-naar-server-bewerkingen is niet vereist. Op de server wordt ervan uitgegaan dat alle clients zijn geabonneerd.

Voorbeeld van eenvoudige ReqRep-interactie

Aanvraag:

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

Antwoord (geslaagd):

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

ReqRep-interacties bieden geen ondersteuning voor PUBLISH pakketten met QoS: 1 als aanvraag- of antwoordberichten. Het versturen van aanvraag PUBLISH resulteert in een Bad Request antwoord.

De maximale lengte die in Correlation Data de eigenschap wordt ondersteund, is 16 bytes. Als de eigenschap Correlation Data op het pakket is ingesteld op een waarde die langer is dan 16 bytes, verzendt IoT Hub PUBLISH met als resultaat DISCONNECT en sluit de verbinding. Dit gedrag is alleen van toepassing op pakketten die binnen deze API worden uitgewisseld.

Notitie

Correlatiegegevens zijn een willekeurige bytereeks, bijvoorbeeld is er geen garantie dat het een UTF-8-tekenreeks is.

ReqRep gebruikt vooraf gedefinieerde onderwerpen voor antwoord; De eigenschap Antwoordonderwerp in aanvraagpakket PUBLISH (indien ingesteld door de afzender) wordt genegeerd.

IoT Hub abonneert de client automatisch op antwoordtopics voor alle client-naar-server ReqRep-bewerkingen. Zelfs als de client zich expliciet afmeldt voor het antwoordonderwerp, wordt het abonnement automatisch hersteld door IoT Hub. Voor reqRep-interacties tussen servers is het nog steeds nodig dat het apparaat zich abonneert.

Eigenschappen van berichten

Bewerkingseigenschappen - door het systeem of door de gebruiker gedefinieerd - worden uitgedrukt als pakketeigenschappen in MQTT 5.

Namen van gebruikerseigenschappen zijn hoofdlettergevoelig en moeten exact zoals gedefinieerd worden gespeld. Bijvoorbeeld, Trace-ID wordt niet ondersteund terwijl trace-id wel wordt ondersteund.

Aanvragen met gebruikerseigenschappen buiten specificatie en zonder voorvoegsel @ resulteren in een fout.

Systeemeigenschappen worden gecodeerd als eigenschappen van de eerste klasse (bijvoorbeeld Content Type) of als gebruikerseigenschappen. Specificatie biedt een uitgebreide lijst met ondersteunde systeemeigenschappen. Alle eigenschappen van de eerste klasse worden genegeerd, tenzij ondersteuning voor deze eigenschappen expliciet wordt vermeld in de specificatie.

Wanneer door de gebruiker gedefinieerde eigenschappen zijn toegestaan, moeten hun namen de notatie @{property name}volgen. Door de gebruiker gedefinieerde eigenschappen ondersteunen alleen geldige UTF-8-tekenreekswaarden. De eigenschap MyProperty1 met waarde 15 moet bijvoorbeeld worden gecodeerd als Gebruikerseigenschap met de naam @MyProperty en waarde 15.

Als de eigenschap Gebruiker niet wordt herkend in IoT Hub, wordt deze beschouwd als een fout en reageert IoT Hub met PUBACKReason Code: 0x83 (implementatiespecifieke fout) en status: 0100 (ongeldige aanvraag). Als bevestiging niet is aangevraagd (QoS: 0), DISCONNECT wordt het pakket met dezelfde fout teruggestuurd en wordt de verbinding beëindigd.

Deze API definieert naast stringde volgende gegevenstypen:

  • time: aantal milliseconden sinds 1970-01-01T00:00:00.000Z. bijvoorbeeld, 1600987195320 voor 2020-09-24T22:39:55.320Z,
  • u32: niet-ondertekend 32-bits geheel getal,
  • u64: ongetekend 64-bits geheel getal,
  • i32: ondertekend 32-bits geheel getal.

Reactie

Interacties kunnen verschillende resultaten opleveren: Success, Bad Request, Not Founden andere. Resultaten onderscheiden zich van elkaar door status de gebruikerseigenschap. Reason Code in PUBACK pakketten (voor MessageAck-interacties) komt, waar mogelijk, qua betekenis overeen met status.

Notitie

Als de client in CONNECT-pakket opgeeft Request Problem Information: 0 , worden er geen gebruikerseigenschappen verzonden op PUBACK pakketten om te voldoen aan de MQTT 5-specificatie, inclusief status eigenschap. In dit geval kan de client nog steeds op Reason Code vertrouwen om te bepalen of de bevestiging positief of negatief is.

Elke interactie heeft een standaardinstelling (of succes). Het heeft Reason Code van 0 en eigenschap status die 'niet ingesteld' is. Anders:

  • Voor MessageAck-interacties krijgt PUBACK een waarde anders dan 0x0 (Geslaagd) Reason Code. status eigenschap kan aanwezig zijn om het resultaat nog duidelijker te maken.
  • Voor interacties met ReqRep krijgt Response PUBLISH de eigenschap status ingesteld.
  • Omdat er geen manier is om rechtstreeks te reageren op interacties van QoS: 0 MessageAck, wordt het DISCONNECT-pakket verzonden met reactie-informatie, waarna de verbinding wordt verbroken.

Voorbeelden:

Ongeldig verzoek (MessageAck)

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

Niet geautoriseerd (MessageAck):

PUBACK
    Reason_Code: 135
    status: 0101

Niet geautoriseerd (ReqRep):

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

Indien nodig stelt IoT Hub de volgende gebruikerseigenschappen in:

  • status - De uitgebreide code van IoT Hub voor de status van een bewerking. Deze code kan worden gebruikt om resultaten te onderscheiden.
  • trace-id – tracerings-id voor de bewerking; IoT Hub kan meer diagnostische gegevens bewaren over de bewerking die kan worden gebruikt voor intern onderzoek.
  • reason - door mensen leesbare berichten die meer informatie geven over waarom de bewerking is geëindigd in een staat die wordt aangegeven door status eigenschap.

Notitie

Als de client de eigenschap in CONNECT-pakket instelt Maximum Packet Size op een zeer kleine waarde, kunnen niet alle gebruikerseigenschappen passen en worden ze niet weergegeven in het pakket.

reason is alleen bedoeld voor personen en mag niet worden gebruikt in clientlogica. Met deze API kunnen berichten op elk moment worden gewijzigd zonder waarschuwing of wijziging van de versie.

Als de client in CONNECT-pakket verzendt RequestProblemInformation: 0 , worden gebruikerseigenschappen niet opgenomen in bevestigingen per MQTT 5-specificatie.

Statuscode

status eigenschap draagt de statuscode voor de bewerking. Het is geoptimaliseerd voor machineleesefficiëntie. Het bestaat uit een ongelijk getal met twee bytes dat als hex is gecodeerd in een tekenreeks, zoals 0501. Codestructuur (bitkaart):

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

Eerste byte wordt gebruikt voor vlaggen:

  • bits 0 en 1 geven het type resultaten aan:
    • 00 - succes
    • 01 - clientfout
    • 10 - servererror
  • bit 2: 1 geeft aan dat de fout opnieuw kan worden geprobeerd
  • bits 3 tot en met 7 zijn gereserveerd en moeten worden ingesteld op 0

Second byte bevat werkelijke afzonderlijke antwoordcode. Foutcodes met verschillende vlaggen kunnen dezelfde tweede bytewaarde hebben. Er kunnen bijvoorbeeld foutcodes 000101010201 zijn 0301die een afzonderlijke betekenis hebben.

Een voorbeeld is Too Many Requests, een client, een herstelbare fout met een eigen code van 1. De waarde is 0000 0101 0000 0001 of 0x0501.

Clients kunnen type bits gebruiken om te bepalen of de bewerking is voltooid. Clients kunnen ook het bit voor herhaalbare pogingen gebruiken om te bepalen of het verstandig is om de bewerking opnieuw uit te voeren.

Aanbevelingen

Sessiebeheer

CONNACK pakket bevat Session Present eigenschap die aangeeft of de eerder gemaakte sessie door de server is hersteld. Gebruik deze eigenschap om erachter te komen of u zich wilt abonneren op onderwerpen of om het abonneren over te slaan sinds het abonnement eerder is uitgevoerd.

Om te kunnen Session Presentafhankelijk zijn van, moet de client de abonnementen bijhouden die het heeft aangemaakt (dat wil zeggen, SUBSCRIBE pakket verstuurd en SUBACK ontvangen met een succesvolle redencode), of ervoor zorgen dat de client zich op alle onderwerpen abonneert in een enkele SUBSCRIBE/SUBACK transactie. Als de client twee SUBSCRIBE pakketten verzendt en de server slechts één daarvan succesvol verwerkt, communiceert de server Session Present: 1 in CONNACK terwijl slechts een deel van de abonnementen van de client is geaccepteerd.

Om te voorkomen dat een oudere versie van de client zich niet heeft geabonneerd op alle onderwerpen, kunt u zich beter onvoorwaardelijke abonneren wanneer het gedrag van de client verandert (bijvoorbeeld als onderdeel van de firmware-update). Om ervoor te zorgen dat er geen verlopen abonnementen achterblijven (van maximaal toegestaan aantal abonnementen), moet u zich expliciet afmelden voor abonnementen die niet meer in gebruik zijn.

Batchverwerking

Er is geen speciale indeling om een batch berichten te verzenden. Om de overhead van resource-intensieve bewerkingen in TLS en netwerken te verminderen, bundelt u pakketten (PUBLISH, PUBACKSUBSCRIBEen dus nee) samen voordat u ze overgeeft aan de onderliggende TLS/TCP-stack. Client kan ook onderwerpalias eenvoudiger maken binnen de 'batch':

  • Plaats de volledige onderwerpnaam in het eerste PUBLISH pakket voor de verbinding en koppel de onderwerpalias eraan.
  • Plaats de volgende pakketten voor hetzelfde onderwerp met een lege onderwerpnaam en de onderwerpalias-eigenschap.

Migratie

Deze sectie bevat de wijzigingen in de API vergeleken met eerdere MQTT-ondersteuning.

  • Transportprotocol is MQTT 5. Eerder - MQTT 3.1.1.
  • Contextinformatie voor SAS-verificatie is rechtstreeks in CONNECT pakket opgenomen in plaats van te worden gecodeerd samen met handtekening.
  • Verificatiemethode wordt gebruikt om de gebruikte verificatiemethode aan te geven.
  • Shared Access Signature wordt in de eigenschap Verificatiegegevens geplaatst. Het veld Wachtwoord is eerder gebruikt.
  • Onderwerpen voor bewerkingen zijn verschillend:
    • Telemetrie: $iothub/telemetry in plaats van devices/{Client Id}/messages/events,
    • Opdrachten: $iothub/commands in plaats van devices/{Client Id}/messages/devicebound,
    • Dubbele patch gerapporteerd: $iothub/twin/patch/reported in plaats van $iothub/twin/PATCH/properties/reported,
    • Meld Twin Gewenste Staat Veranderd: $iothub/twin/patch/desired in plaats van $iothub/twin/PATCH/properties/desired.
  • Een abonnement op het onderwerp van antwoorden op client-server-verzoek-antwoordoperaties is niet vereist.
  • Gebruikerseigenschappen worden gebruikt in plaats van coderingseigenschappen in onderwerpnaamsegment.
  • Eigenschapsnamen worden gespeld volgens de 'dash-case' naamgevingsconventie in plaats van afkortingen met een speciaal voorvoegsel. Door de gebruiker gedefinieerde eigenschappen vereisen nu een voorvoegsel. $.mid is nu message-id, terwijl myProperty1@myProperty1 wordt.
  • De eigenschap Correlatiegegevens wordt gebruikt om aanvraag- en antwoordberichten te correleren voor aanvraag-antwoordbewerkingen in plaats van $rid eigenschap gecodeerd in onderwerp.
  • iothub-connection-auth-method eigenschap wordt niet langer toegepast op telemetriegebeurtenissen.
  • C2D-opdrachten worden niet verwijderd bij afwezigheid van een abonnement van het apparaat. Ze blijven in de wachtrij totdat het apparaat zich abonneert of totdat ze verlopen.

Voorbeelden

Telemetrie verzenden

Bericht:

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

Erkenning:

<- PUBACK
    Packet_Id: 31
    Reason_Code: 0

Alternatieve erkenning (beperkt):

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

De status van de tweeling ophalen en verzenden

Aanvraag:

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

Antwoord (geslaagd):

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

Antwoord (niet toegestaan):

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

Directe methode-aanroep afhandelen

Aanvraag:

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

Antwoord (geslaagd):

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

Notitie

status is niet ingesteld - het is een succesvolle reactie.

Antwoord van apparaat niet beschikbaar:

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

Fout bij het gebruik van QoS 0, deel 1

Aanvraag:

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

Respons:

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

Fout bij het gebruik van QoS 0, deel 2

Aanvraag:

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

Respons:

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

Volgende stappen