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 IoT Hub-Tarifen „Basic“ und „Standard/Free“ finden Sie unter Wählen des richtigen IoT Hub-Tarifs für Ihre Lösung.
IoT Hub implementiert das D2C-Messaging anhand eines Streaming-Messagingmusters. Die Gerät-zu-Cloud-Nachrichten von IoT Hub sind eher mit Event Hubs-Ereignissen vergleichbar als mit Service Bus-Nachrichten, da der Dienst von einem größeren Volumen von Ereignissen durchlaufen wird, die von mehreren Lesern gelesen werden 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 für Entwickler finden Sie im MQTT-Protokollleitfaden und im AMQP-Protokollleitfaden.
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.
D2C-Nachrichten dürfen maximal 256 KB groß sein. Sie können in Batches gruppiert werden, um den Sendevorgang 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 in Verwalten des Zugriffs auf IoT Hub erläutert, ermöglicht IoT Hub Authentifizierung und Zugriffssteuerung auf Gerätebasis.
Sie können Nachrichten mit Informationen stempeln, die in die Anwendungseigenschaften aufgenommen. Weitere Informationen finden Sie unter Nachrichtenanreicherungen bei Gerät-zu-Cloud-IoT Hub-Nachrichten.
Hinweis
Jedes IoT Hub-Protokoll stellt eine Eigenschaft für den Nachrichteninhaltstyp bereit, die beim Routing von Daten an benutzerdefinierte Endpunkte berücksichtigt wird. Damit Ihre Daten am Ziel ordnungsgemäß behandelt werden (z. B. JSON, die als analysierbare Zeichenfolge anstelle von Base64-codierten Binärdaten behandelt wird), stellen Sie den entsprechenden Inhaltstyp und Zeichensatz für die Nachricht bereit.
Um Ihren Nachrichtentext in einer IoT Hub-Routingabfrage zu verwenden, geben Sie ein gültiges JSON-Objekt für die Nachricht an, und legen Sie die Inhaltstypeigenschaft der Nachricht auf application/json;charset=utf-8.
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 | Benutzerdefinierbar? | 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 | messageId |
| iothub-enqueuedtime | Datum und Uhrzeit des Empfangs der D2C-Nachricht durch IoT Hub. | Nein | enqueuedTime |
| user-id | Eine ID zum Festlegen des Ursprungs von Nachrichten. | Ja | userId |
| iothub-connection-device-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 | connectionDeviceId |
| 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 | connectionModuleId |
| 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-connection-auth-method | 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 | connectionAuthMethod |
| iothub-app-iothub-creation-time-utc | Ermöglicht dem Gerät das Senden der Ereigniserstellungszeit beim Senden von Daten in einem Batch. | Yes | creation-time-utc |
| iothub-creation-time-utc | Ermöglicht dem Gerät das Senden der Ereigniserstellungszeit, wenn jeweils eine Nachricht gleichzeitig gesendet wird. | Yes | creation-time-utc |
| dt-dataschema | Dieser Wert wird von IoT Hub für Gerät-zu-Cloud-Nachrichten festgelegt. 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-subject |
Anwendungseigenschaften von Gerät-zu-Cloud-Nachrichten
Anwendungseigenschaften werden häufig verwendet, um mithilfe der Eigenschaft iothub-creation-time-utc einen Zeitstempel vom Gerät zu senden. So wird aufgezeichnet, wann die Nachricht vom Gerät gesendet wurde. 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 |
| sequence-number | Eine Nummer (für jede Gerätewarteschlange eindeutig), die jeder C2D-Nachricht von IoT Hub zugewiesen wird | Nein |
| zu | Ein Ziel, das in C2D -Nachrichten angegeben wird. | Nein |
| absolute-expiry-time | 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 |
| user-id | Eine ID zum Festlegen des Ursprungs von Nachrichten. Wenn Nachrichten von IoT Hub generiert werden, entspricht die Benutzer-ID dem Namen des IoT-Hubs. | 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 | Event Hubs | Azure Storage | Service Bus | Event Grid |
|---|---|---|---|---|
| Meldungs-ID | message-id | messageId | MessageId | message-id |
| Benutzer-ID | user-id | userId | UserId | user-id |
| Verbindungsgeräte-ID | iothub-connection-device-id | connectionDeviceId | iothub-connection-device-id | iothub-connection-device-id |
| Verbindungsmodul-ID | iothub-connection-module-id | connectionModuleId | iothub-connection-module-id | iothub-connection-module-id |
| ID der Verbindungsauthentifizierungsgenerierung | iothub-connection-auth-generation-id | connectionDeviceGenerationId | iothub-connection-auth-generation-id | iothub-connection-auth-generation-id |
| Verbindungsauthentifizierungsmethode | iothub-connection-auth-method | connectionAuthMethod | iothub-connection-auth-method | iothub-connection-auth-method |
| contentType | content-type | contentType | ContentType | iothub-content-type |
| contentEncoding | content-encoding | contentEncoding | ContentEncoding | iothub-content-encoding |
| iothub-enqueuedtime | iothub-enqueuedtime | enqueuedTime | – | iothub-enqueuedtime |
| CorrelationId | correlation-id | correlationId | CorrelationId | correlation-id |
| dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema |
| dt-subject | dt-subject | dt-subject | dt-subject | 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
- Informationen zu Größenbeschränkungen für Nachrichten in IoT Hub finden Sie unter IoT Hub-Kontingente und -Drosselung.
- Informationen zum Erstellen und Lesen von IoT Hub-Nachrichten in verschiedenen Programmiersprachen finden Sie in den Schnellstartanleitungen.
- Informationen zur Struktur von nicht telemetriebezogenen Ereignissen, die von IoT Hub generiert werden, finden Sie unter IoT Hub non-telemetry event schemas (Schemas von IoT Hub für nicht telemetriebezogene Ereignisse).