IoT Hub-dataplanetS MQTT 5 API-referens (inaktuell)

Det här dokumentet definierar åtgärder som är tillgängliga i version 2.0 (api-version: 2020-10-01-preview) av API för IoT Hub-dataplan.

Kommentar

MQTT 5-stöd i IoT Hub är inaktuellt och IoT Hub har begränsat funktionsstöd för MQTT. Om din lösning behöver stöd för MQTT v3.1.1 eller v5 rekommenderar vi MQTT-stöd i Azure Event Grid. Mer information finns i Jämför MQTT-stöd i IoT Hub och Event Grid.

Operations

Hämta tvilling

Hämta tvillingtillstånd

Förfrågan

Ämnesnamn: $iothub/twin/get

Egenskaper: ingen

Nyttolast: tom

Svar om lyckad åtgärd

Egenskaper: ingen

Nyttolast: Tvilling

Alternativa svar

Status	Name	beskrivning
0100	Felaktig förfrågan	Åtgärdsmeddelandet är felaktigt och kan inte bearbetas.
0101	Saknar behörighet	Klienten har inte behörighet att utföra åtgärden.
0102	Ej tillåtet	Åtgärden är inte tillåten.
0501	Begränsad	begärandefrekvensen är för hög per SKU
0502	Kvoten har överskridits	den dagliga kvoten per aktuell SKU överskrids
0601	Serverfel	internt serverfel
0602	Timeout	tidsgränsen för åtgärden innan den kunde slutföras
0603	Servern är upptagen	servern är upptagen

Exempel på pseudokod

-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/get
<- PUBLISH
    QoS: 0
    Topic: $iothub/responses

Korrigeringstvilling rapporterad

Patch Twins rapporterade tillstånd

Förfrågan

Ämnesnamn: $iothub/twin/patch/reported

Egenskaper:

Namn	Typ	Obligatoriskt	Beskrivning
if-version	u64	nej

Nyttolast: TwinState

Svar om lyckad åtgärd

Egenskaper:

Namn	Typ	Obligatoriskt	Beskrivning
version	u64	ja	Version av rapporterat tillstånd efter att korrigeringen har tillämpats

Nyttolast: tom

Alternativa svar

Status	Name	beskrivning
0104	Förhandsvillkoret misslyckades	förutsättningen inte uppfylldes, vilket ledde till att begäran avbröts
0100	Felaktig förfrågan	Åtgärdsmeddelandet är felaktigt och kan inte bearbetas.
0101	Saknar behörighet	Klienten har inte behörighet att utföra åtgärden.
0102	Ej tillåtet	Åtgärden är inte tillåten.
0501	Begränsad	begärandefrekvensen är för hög per SKU
0502	Kvoten har överskridits	den dagliga kvoten per aktuell SKU överskrids
0601	Serverfel	internt serverfel
0602	Timeout	tidsgränsen för åtgärden innan den kunde slutföras
0603	Servern är upptagen	servern är upptagen

Exempel på pseudokod

-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/patch/reported
    [if-version: <u64>]
<- PUBLISH
    QoS: 0
    Topic: $iothub/responses

Ta emot kommandon

Ta emot och hantera kommandon

Meddelande

Ämnesnamn: $iothub/commands

Egenskaper:

Namn	Typ	Obligatoriskt	Beskrivning
sequence-no	u64	ja	Sekvensnummer för meddelandet
enqueued-time	time	ja	Tidsstämpel för när meddelandet kom in i systemet
leveransantal	u32	ja	Antal gånger som meddelandeleveransen gjordes
creation-time	time	nej	Tidsstämpel för när meddelandet skapades (tillhandahålls av avsändaren)
message-id	sträng	nej	Meddelandeidentitet (tillhandahålls av avsändaren)
användar-ID	sträng	nej	Användaridentitet (tillhandahålls av avsändaren)
korrelations-ID	sträng	nej	Korrelationsidentitet (tillhandahålls av avsändaren)
Innehållstyp	sträng	nej	avgör nyttolastens innehållstyp
content-encoding	sträng	nej	avgör innehållskodning av nyttolasten

Nyttolast: alla bytesekvenser

Bekräftelse av lyckad

Anger att kommandot accepterades för hantering av klienten

Egenskaper: ingen

Nyttolast: tom

Alternativa bekräftelser

Orsakskod	Status	Name	beskrivning
131	0603	Lämna	Anger att kommandot inte bearbetas just nu och bör levereras på nytt i framtiden.
131	0100	Avvisa	Anger att klienten avvisade kommandot och att det inte ska försökas igen.

Exempel på pseudokod

-> SUBSCRIBE
    - Topic: $iothub/commands
      QoS: 1
<- PUBLISH
    QoS: 1
    Topic: $iothub/commands
    sequence-no: <u64>enqueued-time: <time>delivery-count: <u32>[creation-time: <time>][message-id: <string>][user-id: <string>][correlation-id: <string>][Content Type: <string>][content-encoding: <string>]
    Payload: ...

-> PUBACK

Ta emot direktmetoder

Ta emot och hantera direktmetodanrop

Förfrågan

Ämnesnamn: $iothub/methods/{name}

Egenskaper: ingen

Nyttolast: alla bytesekvenser

Svar om lyckad åtgärd

Egenskaper:

Namn	Typ	Obligatoriskt	Beskrivning
svarskod	u32	ja

Nyttolast: alla bytesekvenser

Alternativa svar

Status	Name	beskrivning
06A0	Inte tillgänglig	Anger att klienten inte kan nås via den här anslutningen.

Exempel på pseudokod

-> SUBSCRIBE
    - Topic: methods/{name}
      QoS: 0
<- SUBACK
<- PUBLISH
    QoS: 0
    Topic: $iothub/methods/{name}
-> PUBLISH
    QoS: 0
    Topic: $iothub/responses

Ta emot önskade tillståndsändringar för tvilling

Ta emot uppdateringar av tvillingens önskade tillstånd

Meddelande

Ämnesnamn: $iothub/twin/patch/desired

Egenskaper:

Namn	Typ	Obligatoriskt	Beskrivning
version	u64	ja	Version av önskat tillstånd som matchar den här uppdateringen

Nyttolast: TwinState

Exempel på pseudokod

-> SUBSCRIBE
    - Topic: $iothub/twin/patch/desired
      QoS: 0
<- PUBLISH
    QoS: 0
    Topic: $iothub/twin/patch/desired
    version: <u64>
    Payload: ...

Skicka telemetri

Skicka meddelande till telemetrikanalen – Event Hubs som standard eller annan slutpunkt via routningskonfiguration.

Meddelande

Ämnesnamn: $iothub/telemetry

Egenskaper:

Namn	Typ	Obligatoriskt	Beskrivning
Innehållstyp	sträng	nej	översätts till content-type systemegenskap vid publicerat meddelande
content-encoding	sträng	nej	översätts till content-encoding systemegenskap vid publicerat meddelande
message-id	sträng	nej	översätts till message-id systemegenskap vid publicerat meddelande
användar-ID	sträng	nej	översätts till user-id systemegenskap vid publicerat meddelande
korrelations-ID	sträng	nej	översätts till correlation-id systemegenskap vid publicerat meddelande
creation-time	time	nej	översätts till iothub-creation-time-utc egenskap vid publicerat meddelande

Dricks

Formatet creation-time för måste vara UTC utan tidszonsinformation. Är till exempel 2021-04-21T11:30:16Z giltigt, 2021-04-21T11:30:16-07:00 är ogiltigt.

Nyttolast: alla bytesekvenser

Bekräftelse av lyckad

Meddelandet har publicerats till telemetrikanalen

Egenskaper: ingen

Nyttolast: tom

Alternativa bekräftelser

Orsakskod	Status	Name	beskrivning
131	0100	Felaktig förfrågan	Åtgärdsmeddelandet är felaktigt och kan inte bearbetas.
135	0101	Saknar behörighet	Klienten har inte behörighet att utföra åtgärden.
131	0102	Ej tillåtet	Åtgärden är inte tillåten.
131	0601	Serverfel	internt serverfel
151	0501	Begränsad	begärandefrekvensen är för hög per SKU
151	0502	Kvoten har överskridits	den dagliga kvoten per aktuell SKU överskrids
131	0602	Timeout	tidsgränsen för åtgärden innan den kunde slutföras
131	0603	Servern är upptagen	servern är upptagen

Exempel på pseudokod

-> PUBLISH
    QoS: 1
    Topic: $iothub/telemetry
    [Content Type: <string>]
    [content-encoding: <string>]
    [message-id: <string>]
    [user-id: <string>]
    [correlation-id: <string>]
    [creation-time: <time>]

<- PUBACK

Svar

Felaktig förfrågan

Åtgärdsmeddelandet är felaktigt och kan inte bearbetas.

Orsakskod: 131

Status: 0100

Egenskaper:

Namn	Typ	Obligatoriskt	Beskrivning
orsak	sträng	nej	innehåller information om vad som specifikt inte är giltigt för meddelandet

Nyttolast: tom

Konflikt

Åtgärden står i konflikt med en annan pågående åtgärd.

Orsakskod: 131

Status: 0103

Egenskaper:

Namn	Typ	Obligatoriskt	Beskrivning
spårnings-ID	sträng	nej	spårnings-ID för korrelation med annan diagnostik för felet
orsak	sträng	nej	innehåller information om vad som specifikt inte är giltigt för meddelandet

Nyttolast: tom

Ej tillåtet

Åtgärden är inte tillåten.

Orsakskod: 131

Status: 0102

Egenskaper:

Namn	Typ	Obligatoriskt	Beskrivning
orsak	sträng	nej	innehåller information om vad som specifikt inte är giltigt för meddelandet

Nyttolast: tom

Saknar behörighet

Klienten har inte behörighet att utföra åtgärden.

Orsakskod: 135

Status: 0101

Egenskaper:

Namn	Typ	Obligatoriskt	Beskrivning
spårnings-ID	sträng	nej	spårnings-ID för korrelation med annan diagnostik för felet

Nyttolast: tom

Hittades inte

begärd resurs finns inte

Orsakskod: 131

Status: 0504

Egenskaper:

Namn	Typ	Obligatoriskt	Beskrivning
orsak	sträng	nej	innehåller information om vad som specifikt inte är giltigt för meddelandet

Nyttolast: tom

Har inte ändrats

Resursen ändrades inte baserat på den angivna förhandsvillkoret.

Orsakskod: 0

Status: 0001

Egenskaper: ingen

Nyttolast: tom

Förhandsvillkoret misslyckades

Förhandsvillkoret uppfylldes inte, vilket ledde till att begäran avbröts

Orsakskod: 131

Status: 0104

Egenskaper: ingen

Nyttolast: tom

Kvoten har överskridits

den dagliga kvoten per aktuell SKU överskrids

Orsakskod: 151

Status: 0502

Egenskaper: ingen

Nyttolast: tom

Resursen är uttömd

resursen har ingen kapacitet för att slutföra åtgärden

Orsakskod: 131

Status: 0503

Egenskaper:

Namn	Typ	Obligatoriskt	Beskrivning
orsak	sträng	nej	innehåller information om vad som specifikt inte är giltigt för meddelandet

Nyttolast: tom

Servern är upptagen

servern är upptagen

Orsakskod: 131

Status: 0603

Egenskaper:

Namn	Typ	Obligatoriskt	Beskrivning
spårnings-ID	sträng	nej	spårnings-ID för korrelation med annan diagnostik för felet

Nyttolast: tom

Serverfel

internt serverfel

Orsakskod: 131

Status: 0601

Egenskaper:

Namn	Typ	Obligatoriskt	Beskrivning
spårnings-ID	sträng	nej	spårnings-ID för korrelation med annan diagnostik för felet

Nyttolast: tom

Målet misslyckades

Målet svarade men svaret var ogiltigt eller felaktigt

Orsakskod: 131

Status: 06A2

Egenskaper:

Namn	Typ	Obligatoriskt	Beskrivning
orsak	sträng	nej	innehåller information om vad som specifikt inte är giltigt för meddelandet

Nyttolast: tom

Tidsgräns för mål

timeout väntar på att målet ska slutföra begäran

Orsakskod: 131

Status: 06A1

Egenskaper:

Namn	Typ	Obligatoriskt	Beskrivning
spårnings-ID	sträng	nej	spårnings-ID för korrelation med annan diagnostik för felet
orsak	sträng	nej	innehåller information om vad som specifikt inte är giltigt för meddelandet

Nyttolast: tom

Målet är inte tillgängligt

Målet kan inte nås för att slutföra begäran

Orsakskod: 131

Status: 06A0

Egenskaper: ingen

Nyttolast: tom

Begränsad

begärandefrekvensen är för hög per SKU

Orsakskod: 151

Status: 0501

Egenskaper: ingen

Nyttolast: tom

Timeout

tidsgränsen för åtgärden innan den kunde slutföras

Orsakskod: 131

Status: 0602

Egenskaper:

Namn	Typ	Obligatoriskt	Beskrivning
spårnings-ID	sträng	nej	spårnings-ID för korrelation med annan diagnostik för felet

Nyttolast: tom