Ondersteuning voor IoT Hub MQTT 5 (preview)

  • Artikel

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

IoT Hub biedt 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.

Vereisten

Niveau van ondersteuning en beperkingen

IoT Hub-ondersteuning voor MQTT 5 is in preview en beperkt op de volgende manieren (communiceren met de client 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 bewerking).
  • Toegewezen client-id's worden niet ondersteund.
  • Keep Alive is beperkt tot 19 min (maximale vertraging voor liveness check – 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-bekende PUBLISH pakketten (in client-serverrichting) met QoS: 1) is 16.
  • Eén client mag niet meer dan 50 abonnementen hebben. Als een client de abonnementslimiet 0x97 bereikt, SUBACK wordt de redencode voor abonnementen geretourneerd (quotum overschreden).

levenscyclus van Verbinding maken ion

Connection

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 CONNECT een 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 is afhankelijk Authentication Methodvan . Als Authentication Method dit is ingesteld SASop, Authentication Data is dit vereist en moet deze 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 client hello-record tijdens 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.

Verificatie

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

  • SAS - Shared Access Signature is opgegeven in CONNECTde Authentication Data eigenschap,
  • X509 - client is afhankelijk van verificatie van clientcertificaten.

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 Authentication Method de eigenschap niet is opgegeven, mislukt de verbinding met Bad Request het antwoord.

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.

Tekenreeks die moet worden ondertekend, moet als volgt worden gevormd:

{host name}\n
{Client Id}\n
{sas-policy}\n
{sas-at}\n
{sas-expiry}\n
  • host name is afgeleid van de SNI-extensie (gepresenteerd door client in Client Hello-record tijdens TLS-handshake) of host gebruikerseigenschap in CONNECT pakket.
  • Client Id is 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 wordt gecodeerd als gebruikerseigenschap van het time type op CONNECT pakket.
  • sas-expiry definieert de verlooptijd voor de verificatie. Het is een time-getypte gebruikerseigenschap 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 AUTH IoT Hub pakketten met Reason Code: 0x00 (geslaagd). Anders verzendt DISCONNECT IoT Hub pakketten met Reason Code: 0x87 (niet geautoriseerd) en sluit de verbinding.

Onderbreking

Server kan de client om een paar redenen verbreken, waaronder:

  • client heeft zich verkeerd gedragen op een manier waarop niet rechtstreeks kan worden gereageerd met negatieve bevestiging (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(Verbinding maken ionsnelheid 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).

Operations

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

Zie voor volledige specificatie van bewerkingen in deze API ioT Hub-gegevensvlak MQTT 5 API-verwijzing.

Notitie

Alle voorbeelden in deze specificatie worden vanuit het perspectief van de client weergegeven. Ondertekenen -> betekent dat client pakket verzendt, <- - 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. Dit wordt bijvoorbeeld $iothub/telemetry/ niet ondersteund.$iothub/telemetry

Notitie

Jokertekens in abonnementen worden $iothub/.. niet ondersteund. Dat wil gezegd, een client kan zich niet abonneren op $iothub/+ of $iothub/#. Als u dit probeert, resulteert dit in SUBACK ( 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 bevestiging (MessageAck)
  • Request-Response (ReqRep)

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 client-naar-server-bewerking van het type Bericht met bevestiging, terwijl De directe methode verwerken server-naar-client-bewerking van aanvraag-antwoordtype is.

Interacties tussen bevestiging 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 afgekapt vanwege Maximum Packet Size de opgegeven door de client, behoudt IoT Hub zoveel gebruikerseigenschappen als deze 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>

Bevestiging (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 verzenden van aanvraagresultaten PUBLISH in Bad Request antwoord.

De maximale lengte die in Correlation Data de eigenschap wordt ondersteund, is 16 bytes. Als Correlation Data eigenschap op pakket is ingesteld op PUBLISH een waarde die langer is dan 16 bytes, verzendt DISCONNECT IoT Hub met Bad Request resultaat 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 dat het geen 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 client automatisch op antwoordonderwerpen voor alle reqRep-bewerkingen van clients naar server. 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.

Berichteigenschappen

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. Dit wordt bijvoorbeeld Trace-ID niet ondersteund.trace-id

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 met waarde moet bijvoorbeeld MyProperty1 worden gecodeerd als de eigenschap Gebruiker met de naam @MyProperty en waarde15.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: niet-ondertekend 64-bits geheel getal,
  • i32: ondertekend 32-bits geheel getal.

Respons

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 overeen status met betekenis.

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 vertrouwen Reason Code om te bepalen of bevestiging positief of negatief is.

Elke interactie heeft een standaardinstelling (of geslaagd). Het heeft Reason Code van 0 en status eigenschap van "niet ingesteld". Anders:

  • Voor MessageAck-interacties PUBACK wordt anders dan 0x0 (Geslaagd) weergegeven Reason Code . status eigenschap kan aanwezig zijn om het resultaat verder te verduidelijken.
  • Voor interacties met ReqRep wordt status de eigenschap Response PUBLISH ingesteld.
  • Omdat er geen manier is om rechtstreeks te reageren op interacties van QoS: 0 MessageAck, DISCONNECT wordt het pakket verzonden met antwoordgegevens, gevolgd door de verbinding verbreken.

Voorbeelden:

Ongeldige aanvraag (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 - Uitgebreide code van IoT Hub voor de status van de 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 de eigenschap heeft de statuscode voor de bewerking. Het is geoptimaliseerd voor machineleesefficiëntie. Het bestaat uit een geheel getal met twee bytes dat is gecodeerd als hex in 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 - serverfout
  • 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 010102010301 zijn 0001die een afzonderlijke betekenis hebben.

Is bijvoorbeeld Too Many Requests een client, een fout die opnieuw kan worden geprobeerd 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 een bit met een nieuwe poging gebruiken om te bepalen of het verstandig is om de bewerking opnieuw uit te voeren.

Aanbevelingen

Sessiebeheer

CONNACK pakket bevat Session Present eigenschap om aan te geven of de server eerder gemaakte sessie 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.

Als u wilt Session Presentvertrouwen, moet de client abonnementen bijhouden die zijn gemaakt (dat wil gezegd, verzonden SUBSCRIBE pakket en ontvangen SUBACK met een geslaagde redencode) of ervoor zorgen dat de client zich abonneert op alle onderwerpen in één SUBSCRIBE/SUBACK uitwisseling. Als de client twee SUBSCRIBE pakketten verzendt en de server slechts één van deze pakketten verwerkt, communiceert Session Present: 1 de server terwijl CONNACK 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.

Batching

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 de eigenschap lege onderwerpnaam en onderwerpalias.

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,
    • Patchdubbel gerapporteerd: $iothub/twin/patch/reported in plaats van $iothub/twin/PATCH/properties/reported,
    • Meldingsdubbel Desired State Changed: $iothub/twin/patch/desired in plaats van $iothub/twin/PATCH/properties/desired.
  • Het antwoordonderwerp van client-serveraanvraag-antwoordbewerkingen is niet vereist.
  • Gebruikerseigenschappen worden gebruikt in plaats van coderingseigenschappen in onderwerpnaamsegment.
  • eigenschapsnamen worden gespeld in naamconventie 'dash-case' in plaats van afkortingen met speciaal voorvoegsel. Door de gebruiker gedefinieerde eigenschappen vereisen nu voorvoegsel. Is bijvoorbeeld nu message-id, $.mid terwijl myProperty1 het wordt @myProperty1.
  • 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 meer gestempeld voor telemetriegebeurtenissen.
  • C2D-opdrachten worden niet verwijderd als er geen abonnement van het apparaat is. Ze blijven in de wachtrij totdat het apparaat zich abonneert of verloopt.

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 bevestiging (beperkt):

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

De status van de dubbel 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 verwerken

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 geslaagd antwoord.

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