Freigeben über

IoT Hub Data Plane MQTT 5 API-Referenz (veraltet)

  • Artikel

In diesem Dokument werden die verfügbaren Vorgänge in Version 2.0 (API-Version: 2020-10-01-preview) der API auf IoT Hub-Datenebene definiert.

Hinweis

MQTT 5-Unterstützung in IoT Hub ist veraltet, und IoT Hub bietet nur eingeschränkte Featureunterstützung für MQTT. Wenn Ihre Lösung MQTT v3.1.1 oder v5 Unterstützung benötigt, empfehlen wir MQTT Unterstützung in Azure Event Grid. Weitere Informationen finden Sie unter Vergleichen der MQTT-Unterstützung in IoT Hub und Event Grid.

Operations

Get Twin

Abrufen des Zwillingsstatus

Anfordern

Themenname: $iothub/twin/get

Eigenschaften: keine

Payload: leer

Antwort bei Erfolg

Eigenschaften: keine

Nutzlast: Zwilling

Alternative Antworten

Status Name BESCHREIBUNG
0100 Ungültige Anforderung Die Vorgangsnachricht ist falsch formatiert und kann nicht verarbeitet werden.
0101 Nicht autorisiert Der Client ist nicht zum Ausführen des Vorgangs autorisiert.
0102 Nicht zulässig Vorgang ist nicht zulässig.
0501 Gedrosselt Die Anforderungsrate ist für die SKU zu hoch.
0502 Quote überschritten Das tägliche Kontingent der aktuellen SKU wurde überschritten.
0601 Serverfehler Interner Serverfehler
0602 Timeout Beim Vorgang ist vor dem Abschluss ein Timeout aufgetreten.
0603 Server ausgelastet Der Server ist ausgelastet.

Pseudobeispielcode


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

Gemeldete Patchzwillinge

Status der gemeldeten Patchzwillinge

Anfordern

Themenname: $iothub/twin/patch/reported

Eigenschaften:

Name Type Erforderlich BESCHREIBUNG
if-version u64 nein

Nutzlast: TwinState

Antwort bei Erfolg

Eigenschaften:

Name Type Erforderlich Beschreibung
version u64 ja Version des gemeldeten Status nach dem Anwenden des Patches

Payload: leer

Alternative Antworten

Status Name BESCHREIBUNG
0104 Vorbedingung nicht erfüllt Anforderung wurde abgebrochen, da die Vorbedingung nicht erfüllt war.
0100 Ungültige Anforderung Die Vorgangsnachricht ist falsch formatiert und kann nicht verarbeitet werden.
0101 Nicht autorisiert Der Client ist nicht zum Ausführen des Vorgangs autorisiert.
0102 Nicht zulässig Vorgang ist nicht zulässig.
0501 Gedrosselt Die Anforderungsrate ist für die SKU zu hoch.
0502 Quote überschritten Das tägliche Kontingent der aktuellen SKU wurde überschritten.
0601 Serverfehler Interner Serverfehler
0602 Timeout Beim Vorgang ist vor dem Abschluss ein Timeout aufgetreten.
0603 Server ausgelastet Der Server ist ausgelastet.

Pseudobeispielcode


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

Empfangen von Befehlen

Empfangen und Verarbeiten von Befehlen

`Message`

Themenname: $iothub/commands

Eigenschaften:

Name Type Erforderlich BESCHREIBUNG
sequence-no u64 ja Sequenznummer der Nachricht
enqueued-time time ja Zeitstempel des Zeitpunkts, zu dem die Nachricht in das System gelangt ist
delivery-count u32 ja Häufigkeit, mit der die Nachrichtenübermittlung versucht wurde
creation-time time nein Zeitstempel des Zeitpunkts, zu dem die Nachricht erstellt wurde (vom Absender bereitgestellt)
message-id Zeichenfolge nein Nachrichtenidentität (vom Absender bereitgestellt)
user-id Zeichenfolge nein Benutzeridentität (vom Absender bereitgestellt)
correlation-id Zeichenfolge nein Korrelationsidentität (vom Absender bereitgestellt)
Inhaltstyp Zeichenfolge nein Gibt den Inhaltstyp der Payload an
content-encoding Zeichenfolge nein Gibt die Inhaltscodierung der Payload an

Payload: beliebige Bytesequenz

Bestätigung bei Erfolg

Gibt an, dass der Befehl für die Verarbeitung durch den Client akzeptiert wurde

Eigenschaften: keine

Payload: leer

Alternative Bestätigungen

Ursachencode Status Name BESCHREIBUNG
131 0603 Abandon Gibt an, dass der Befehl zu diesem Zeitpunkt nicht verarbeitet wird und in der Zukunft erneut übermittelt werden sollte.
131 0100 Reject Gibt an, dass der Client den Befehl abgelehnt hat, und er sollte nicht erneut versucht werden.

Pseudobeispielcode


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

Empfangen von direkten Methoden

Empfangen und Verarbeiten von Aufrufen direkter Methoden

Anfordern

Themenname: $iothub/methods/{name}

Eigenschaften: keine

Payload: beliebige Bytesequenz

Antwort bei Erfolg

Eigenschaften:

Name Type Erforderlich BESCHREIBUNG
response-code u32 ja

Payload: beliebige Bytesequenz

Alternative Antworten

Status Name BESCHREIBUNG
06A0 Nicht verfügbar Gibt an, dass der Client über diese Verbindung nicht erreichbar ist.

Pseudobeispielcode


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

Empfangen von Änderungen am gewünschten Status von Zwillingen

Empfangen von Updates am gewünschten Zustand des Zwillings

`Message`

Themenname: $iothub/twin/patch/desired

Eigenschaften:

Name Type Erforderlich Beschreibung
version u64 ja Version des gewünschten Status zu diesem Update

Nutzlast: TwinState

Pseudobeispielcode


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

Senden von Telemetriedaten

Senden Sie eine Nachricht an den Telemetriekanal. Standardmäßig ist dies Event Hubs, Sie können aber über die Routingkonfiguration einen anderen Endpunkt festlegen.

`Message`

Themenname: $iothub/telemetry

Eigenschaften:

Name Type Erforderlich BESCHREIBUNG
Inhaltstyp Zeichenfolge nein Wird in der übermittelten Nachricht in eine content-type-Systemeigenschaft übersetzt
content-encoding Zeichenfolge nein Wird in der übermittelten Nachricht in eine content-encoding-Systemeigenschaft übersetzt
message-id Zeichenfolge nein Wird in der übermittelten Nachricht in eine message-id-Systemeigenschaft übersetzt
user-id Zeichenfolge nein Wird in der übermittelten Nachricht in eine user-id-Systemeigenschaft übersetzt
correlation-id Zeichenfolge nein Wird in der übermittelten Nachricht in eine correlation-id-Systemeigenschaft übersetzt
creation-time time nein Wird in der übermittelten Nachricht in eine iothub-creation-time-utc-Eigenschaft übersetzt

Tipp

Das Format von creation-time muss UTC ohne Zeitzoneninformationen sein. Beispiel: 2021-04-21T11:30:16Z ist gültig, 2021-04-21T11:30:16-07:00 ist ungültig.

Payload: beliebige Bytesequenz

Bestätigung bei Erfolg

Die Nachricht wurde an den Telemetriekanal übermittelt.

Eigenschaften: keine

Payload: leer

Alternative Bestätigungen

Ursachencode Status Name BESCHREIBUNG
131 0100 Ungültige Anforderung Die Vorgangsnachricht ist falsch formatiert und kann nicht verarbeitet werden.
135 0101 Nicht autorisiert Der Client ist nicht zum Ausführen des Vorgangs autorisiert.
131 0102 Nicht zulässig Vorgang ist nicht zulässig.
131 0601 Serverfehler Interner Serverfehler
151 0501 Gedrosselt Die Anforderungsrate ist für die SKU zu hoch.
151 0502 Quote überschritten Das tägliche Kontingent der aktuellen SKU wurde überschritten.
131 0602 Timeout Beim Vorgang ist vor dem Abschluss ein Timeout aufgetreten.
131 0603 Server ausgelastet Der Server ist ausgelastet.

Pseudobeispielcode

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

Antworten

Ungültige Anforderung

Die Vorgangsnachricht ist falsch formatiert und kann nicht verarbeitet werden.

Ursachencode: 131

Status: 0100

Eigenschaften:

Name Type Erforderlich BESCHREIBUNG
reason Zeichenfolge Nein enthält Informationen darüber, was speziell an dieser Nachricht nicht gültig ist

Payload: leer

Konflikt:

Der Vorgang steht im Konflikt mit einem anderen laufenden Vorgang.

Ursachencode: 131

Status: 0103

Eigenschaften:

Name Type Erforderlich BESCHREIBUNG
trace-id Zeichenfolge Nein Ablaufverfolgungs-ID für die Korrelation mit weiteren Diagnoseinformationen zum Fehler
reason Zeichenfolge Nein enthält Informationen darüber, was speziell an dieser Nachricht nicht gültig ist

Payload: leer

Nicht zulässig

Vorgang ist nicht zulässig.

Ursachencode: 131

Status: 0102

Eigenschaften:

Name Type Erforderlich BESCHREIBUNG
reason Zeichenfolge Nein enthält Informationen darüber, was speziell an dieser Nachricht nicht gültig ist

Payload: leer

Nicht autorisiert

Der Client ist nicht zum Ausführen des Vorgangs autorisiert.

Ursachencode: 135

Status: 0101

Eigenschaften:

Name Type Erforderlich BESCHREIBUNG
trace-id Zeichenfolge Nein Ablaufverfolgungs-ID für die Korrelation mit weiteren Diagnoseinformationen zum Fehler

Payload: leer

Nicht gefunden

Die angeforderte Ressource ist nicht vorhanden.

Ursachencode: 131

Status: 0504

Eigenschaften:

Name Type Erforderlich BESCHREIBUNG
reason Zeichenfolge Nein enthält Informationen darüber, was speziell an dieser Nachricht nicht gültig ist

Payload: leer

Nicht geändert

Die Ressource wurde hinsichtlich der angegebenen Vorbedingung nicht geändert.

Ursachencode: 0

Status: 0001

Eigenschaften: keine

Payload: leer

Vorbedingung nicht erfüllt

Anforderung wurde abgebrochen, da die Vorbedingung nicht erfüllt war.

Ursachencode: 131

Status: 0104

Eigenschaften: keine

Payload: leer

Quote überschritten

Das tägliche Kontingent der aktuellen SKU wurde überschritten.

Ursachencode: 151

Status: 0502

Eigenschaften: keine

Payload: leer

Ressource erschöpft

Die Ressource verfügt nicht über die Kapazitäten zum Abschließen des Vorgangs.

Ursachencode: 131

Status: 0503

Eigenschaften:

Name Type Erforderlich BESCHREIBUNG
reason Zeichenfolge Nein enthält Informationen darüber, was speziell an dieser Nachricht nicht gültig ist

Payload: leer

Server ausgelastet

Der Server ist ausgelastet.

Ursachencode: 131

Status: 0603

Eigenschaften:

Name Type Erforderlich BESCHREIBUNG
trace-id Zeichenfolge Nein Ablaufverfolgungs-ID für die Korrelation mit weiteren Diagnoseinformationen zum Fehler

Payload: leer

Serverfehler

Interner Serverfehler

Ursachencode: 131

Status: 0601

Eigenschaften:

Name Type Erforderlich BESCHREIBUNG
trace-id Zeichenfolge Nein Ablaufverfolgungs-ID für die Korrelation mit weiteren Diagnoseinformationen zum Fehler

Payload: leer

Zielfehler

Das Ziel hat geantwortet, aber die Antwort war ungültig oder falsch formatiert.

Ursachencode: 131

Status: 06A2

Eigenschaften:

Name Type Erforderlich BESCHREIBUNG
reason Zeichenfolge Nein enthält Informationen darüber, was speziell an dieser Nachricht nicht gültig ist

Payload: leer

Timeout beim Ziel

Beim Warten auf den Abschluss der Anforderung durch das Ziel ist ein Timeout aufgetreten.

Ursachencode: 131

Status: 06A1

Eigenschaften:

Name Type Erforderlich BESCHREIBUNG
trace-id Zeichenfolge Nein Ablaufverfolgungs-ID für die Korrelation mit weiteren Diagnoseinformationen zum Fehler
reason Zeichenfolge Nein enthält Informationen darüber, was speziell an dieser Nachricht nicht gültig ist

Payload: leer

Ziel nicht verfügbar

Das Ziel ist nicht erreichbar und kann die Anforderung nicht abschließen.

Ursachencode: 131

Status: 06A0

Eigenschaften: keine

Payload: leer

Gedrosselt

Die Anforderungsrate ist für die SKU zu hoch.

Ursachencode: 151

Status: 0501

Eigenschaften: keine

Payload: leer

Timeout

Beim Vorgang ist vor dem Abschluss ein Timeout aufgetreten.

Ursachencode: 131

Status: 0602

Eigenschaften:

Name Type Erforderlich BESCHREIBUNG
trace-id Zeichenfolge Nein Ablaufverfolgungs-ID für die Korrelation mit weiteren Diagnoseinformationen zum Fehler

Payload: leer