Freigeben über

Erstellen und Lesen von IoT Hub-Nachrichten

Zur Unterstützung der protokollübergreifenden Interoperabilität definiert IoT Hub eine Gruppe von Messagingfeatures, die in allen gerätebezogenen Protokollen verfügbar sind. Diese Features können sowohl für Gerät-zu-Cloud-Nachrichten als auch für Cloud-zu-Gerät-Nachrichten verwendet werden.

Hinweis

Einige der in diesem Artikel erwähnten Features (wie Cloud-zu-Gerät-Messaging, Gerätezwillinge und Geräteverwaltung) stehen nur im Standard-Tarif von IoT Hub zur Verfügung. Weitere Informationen zu den grundlegenden und standardmäßigen/kostenlosen IoT Hub-Ebenen finden Sie unter Auswählen der richtigen IoT Hub-Ebene und -Größe für Ihre Lösung.

IoT Hub implementiert das D2C-Messaging anhand eines Streaming-Messagingmusters. IoT Hubs Geräte-zu-Cloud-Nachrichten ähneln Event Hubs-Ereignissen mehr als ServiceBus-Nachrichten, da es eine hohe Anzahl von Ereignissen gibt, die den Dienst durchlaufen, den mehrere Leser lesen können.

Eine IoT Hub-Nachricht enthält Folgendes:

  • Vordefinierter Satz von Systemeigenschaften (wie später in diesem Artikel beschrieben)

  • Einen Satz an Anwendungseigenschaften. Ein Wörterbuch mit Zeichenfolgeneigenschaften. Die Anwendung kann diese definieren und darauf zugreifen, ohne den Nachrichtentext deserialisieren zu müssen. IoT Hub ändert diese Eigenschaften nie.

  • Einen Nachrichtentext, der jede beliebige Art von Daten sein kann.

Jedes Geräteprotokoll implementiert Einstellungseigenschaften auf unterschiedliche Weise. Weitere Informationen finden Sie unter Kommunizieren mit einem IoT-Hub mithilfe des MQTT-Protokolls und Kommunizieren mit Ihrem IoT-Hub mithilfe des AMQP-Protokolls.

Wenn Sie Gerät-zu-Cloud-Nachrichten mithilfe des HTTPS-Protokolls oder Cloud-zu-Gerät-Nachrichten senden, können Eigenschaftsnamen und -werte nur alphanumerische ASCII-Zeichen und ! # $ % & ' * + - . ^ _ ` | ~ enthalten.

D2C-Messaging mit IoT Hub weist folgende Merkmale auf:

  • D2C-Nachrichten sind dauerhafter Art und werden bis zu sieben Tage lang auf dem Standardendpunkt der IoT Hub-Instanz (messages/events) aufbewahrt.

  • Geräte-zu-Cloud-Nachrichten können höchstens 256 KB groß sein und in Batches gruppiert werden, um Sendesendungen zu optimieren. Die Batches können maximal 256 KB groß sein.

  • IoT Hub erlaubt keine beliebige Partitionierung. D2C-Nachrichten werden gemäß ihrer ursprünglichen deviceIdpartitioniert.

  • Wie im Abschnitt "Steuern des Zugriffs auf IoT Hub" mithilfe der Microsoft Entra-ID erläutert, ermöglicht IoT Hub die gerätespezifische Authentifizierung und Zugriffssteuerung.

  • Sie können Nachrichten mit Informationen stempeln, die in die Anwendungseigenschaften aufgenommen. Weitere Informationen finden Sie unter Nachrichtenanreicherungen für Gerät-zu-Cloud-IoT-Hub-Nachrichten.

Hinweis

Jedes IoT Hub-Protokoll stellt eine Nachrichteninhaltstypeigenschaft bereit, die beim Weiterleiten von Daten an benutzerdefinierte Endpunkte berücksichtigt wird. Damit Ihre Daten am Ziel ordnungsgemäß verarbeitet werden (z. B. JSON, das als analysierbare Zeichenfolge statt als Base64-codierte Binärdaten behandelt wird), stellen Sie den entsprechenden Inhaltstyp und den Zeichensatz für die Nachricht bereit.

Um Ihren Nachrichtentext in einer IoT Hub-Routingabfrage verwenden zu können, stellen Sie ein gültiges JSON-Objekt für die Nachricht bereit und legen Sie deren Inhaltstypeigenschaft auf application/json;charset=utf-8 fest.

Das folgende Beispiel zeigt einen gültigen, routingfähigen Nachrichtentext:

{
    "timestamp": "2022-02-08T20:10:46Z",
    "tag_name": "spindle_speed",
    "tag_value": 100
}

Systemeigenschaften von Gerät-zu-Cloud-Nachrichten

Eigenschaft BESCHREIBUNG Kann der Benutzer festgelegt werden? Schlüsselwort für
Routingabfrage
message-id Eine vom Benutzer festgelegte Kennung für die Nachricht; wird für Anforderung-Antwort-Muster verwendet. Format: Zeichenfolge, bei der die Groß- und Kleinschreibung beachtet wird (bis zu 128 Zeichen lang) und die aus alphanumerischen ASCII-Zeichen (7 Bit) und - : . + % _ # * ? ! ( ) , = @ ; $ ' besteht. Ja Nachrichten-ID
iothub-Warteschlangenzeit Datum und Uhrzeit, zu der IoT Hub die Geräte-zu-Cloud-Nachricht empfängt. Nein enqueuedTime
Benutzer-ID Eine ID zum Festlegen des Ursprungs von Nachrichten. Ja Benutzer-ID
iothub-Verbindungs-Geräte-ID Eine ID, die von IoT Hub für D2C-Nachrichten festgelegt wird. Diese Eigenschaft enthält die deviceId des Geräts, das die Nachricht sendet. Nein Verbindungsgerät-ID
iothub-connection-module-id Eine ID, die von IoT Hub für D2C-Nachrichten festgelegt wird. Sie enthält die moduleId des Geräts, das die Nachricht sendet. Nein VerbindungsModulID
iothub-connection-auth-generation-id Eine ID, die von IoT Hub für D2C-Nachrichten festgelegt wird. Sie enthält die connectionDeviceGenerationId (gemäß Geräteidentitätseigenschaften) des Geräts, das die Nachricht gesendet hat. Nein connectionDeviceGenerationId
iothub-Verbindungs-Authentifizierungsmethode Eine von IoT Hub für D2C-Nachrichten festgelegte Authentifizierungsmethode. Diese Eigenschaft enthält Informationen zu der Methode, die zum Authentifizieren des Geräts verwendet wird, das die Nachricht sendet. Nein Verbindungsauthentifizierungsmethode
iothub-app-iothub-creation-time-utc Ermöglicht dem Gerät das Senden der Ereigniserstellungszeit beim Senden von Daten in einem Batch. Ja Erstellungszeit-UTC
iothub-Erstellungszeit-UTC Ermöglicht dem Gerät das Senden der Ereigniserstellungszeit, wenn jeweils eine Nachricht gleichzeitig gesendet wird Ja Erstellungszeit-UTC
dt-dataschema Der IoT-Hub legt diesen Wert auf Geräte-zu-Cloud-Nachrichten fest. Er enthält die in der Geräteverbindung festgelegte Gerätemodell-ID. Nein $dt-dataschema
dt-subject Der Name der Komponente, die die Gerät-zu-Cloud-Nachrichten sendet. Ja $dt-Thema

Anwendungseigenschaften von Gerät-zu-Cloud-Nachrichten

Eine häufige Verwendung von Anwendungseigenschaften ist das Senden eines Zeitstempels vom Gerät mithilfe der iothub-creation-time-utc Eigenschaft zum Aufzeichnen, wenn das Gerät die Nachricht sendet. Das Format dieses Zeitstempels muss UTC ohne Zeitzoneninformationen sein. Beispiel: 2021-04-21T11:30:16Z ist gültig, 2021-04-21T11:30:16-07:00 jedoch ungültig.

{
  "applicationId":"00001111-aaaa-2222-bbbb-3333cccc4444",
  "messageSource":"telemetry",
  "deviceId":"sample-device-01",
  "schema":"default@v1",
  "templateId":"urn:modelDefinition:mkuyqxzgea:e14m1ukpn",
  "enqueuedTime":"2021-01-29T16:45:39.143Z",
  "telemetry":{
    "temperature":8.341033560421833
  },
  "messageProperties":{
    "iothub-creation-time-utc":"2021-01-29T16:45:39.021Z"
  },
  "enrichments":{}
}

Systemeigenschaften von Cloud-zu-Gerät-Nachrichten

Eigenschaft BESCHREIBUNG Kann der Benutzer festgelegt werden?
message-id Eine vom Benutzer festgelegte Kennung für die Nachricht; wird für Anforderung-Antwort-Muster verwendet. Format: Zeichenfolge, bei der die Groß- und Kleinschreibung beachtet wird (bis zu 128 Zeichen lang) und die aus alphanumerischen ASCII-Zeichen (7 Bit) und - : . + % _ # * ? ! ( ) , = @ ; $ ' besteht. Ja
Sequenznummer Eine Nummer (für jede Gerätewarteschlange eindeutig), die jeder C2D-Nachricht von IoT Hub zugewiesen wird Nein
zu Ein in Cloud-zu-Gerät-Nachrichten angegebenes Ziel. Nein
absolute Ablaufzeit Datum und Uhrzeit des Nachrichtenablaufs. Ja
correlation-id Eine Zeichenfolgeneigenschaft in einer Antwortnachricht, die normalerweise die Nachrichten-ID der Anforderung im Anforderung-Antwort-Muster enthält. Ja
Benutzer-ID Eine ID zum Festlegen des Ursprungs von Nachrichten. Wenn IoT Hub Nachrichten generiert, ist die Benutzer-ID der IoT-Hubname. Ja
iothub-ack Ein Feedbacknachrichtengenerator. Diese Eigenschaft wird in C2D-Nachrichten verwendet, um IoT Hub anzuweisen, als Ergebnis der Nachrichtenverarbeitung durch das Gerät Feedbacknachrichten zu generieren. Mögliche Werte: Kein (Standardeinstellung): Es wird keine Feedbacknachricht generiert. Positiv: Es wird eine Feedbacknachricht empfangen, wenn die Nachricht abgeschlossen wurde. Negativ: Es wird eine Feedbacknachricht empfangen, wenn die Nachricht ohne vollständige Verarbeitung durch das Gerät abgelaufen ist (oder die maximale Anzahl von Zustellversuchen erreicht wurde). Voll: Feedback wird sowohl bei erfolgreicher als auch nicht erfolgreicher Nachrichtenverarbeitung generiert. Ja

Namen von Systemeigenschaften

Die Namen von Systemeigenschaften variieren je nach dem Endpunkt, an den die Nachrichten weitergeleitet werden.

Name der Systemeigenschaft Ereignis-Hubs Azure Storage Dienstbus Ereignisraster
Meldungs-ID message-id Nachrichten-ID Nachrichten-ID message-id
Benutzer-ID Benutzer-ID Benutzer-ID Benutzer-ID Benutzer-ID
Verbindungsgeräte-ID iothub-Verbindungs-Geräte-ID Verbindungsgerät-ID iothub-Verbindungs-Geräte-ID iothub-Verbindungs-Geräte-ID
Verbindungsmodul-ID iothub-connection-module-id VerbindungsmodulId iothub-verbindung-modul-id iothub-connection-module-id
ID der Verbindungsauthentifizierungsgenerierung iothub-Verbindung-Auth-Generierungs-ID connectionDeviceGenerationId iothub-connection-auth-generation-id iothub-connection-auth-generation-id
Verbindungsauthentifizierungsmethode iothub-Verbindungs-Authentifizierungsmethode Verbindungsauthentifizierungsmethode iothub-Verbindungsauthentifizierungsmethode iothub-Verbindung-Authentifizierungsmethode
Inhaltstyp Inhaltstyp Inhaltstyp Inhaltstyp iothub-content-type
Inhaltscodierung Inhaltscodierung Inhaltscodierung ContentEncoding iothub-content-encoding
iothub-enqueuedtime iothub-enqueuedtime enqueuedTime – iothub-enqueuedtime
CorrelationId correlation-id correlationId CorrelationId correlation-id
dt-dataschema dt-Datenschema dt-Datenschema dt-Datenschema dt-dataschema
dt-Betreff dt-subject dt-subject dt-Thema dt-subject

Nachrichtengröße

IoT Hub misst die Nachrichtengröße auf „protokollagnostische“ Weise, indem nur die tatsächliche Nutzlast berücksichtigt wird. Die Größe in Byte wird als Summe der folgenden Werte berechnet:

  • Text in Byte
  • Größe aller Werte der Nachrichtensystemeigenschaften in Byte
  • Größe aller Benutzereigenschaftsnamen und -werte in Byte

Die Eigenschaftennamen und -werte sind auf ASCII-Zeichen beschränkt, sodass die Länge der Zeichenfolgen der Größe in Byte entspricht.

Eigenschaften zum Schutz vor Spoofing

Um ein Gerätespoofing beim D2C-Messaging zu verhindern, versieht IoT Hub alle Nachrichten mit den folgenden Eigenschaften:

  • iothub-connection-device-id
  • iothub-connection-auth-generation-id
  • iothub-connection-auth-method

Die ersten beiden Eigenschaften enthalten die Werte für deviceId und generationId des ursprünglichen Geräts, wie unter Geräteidentitätseigenschaften beschrieben.

Die Eigenschaft iothub-connection-auth-method enthält ein serialisiertes JSON-Objekt mit folgenden Eigenschaften:

{
  "scope": "{ hub | device | module }",
  "type": "{ symkey | sas | x509 }",
  "issuer": "iothub"
}

Nächste Schritte

  • Last updated on