IoT Hub-berichten maken en lezen
Om naadloze interoperabiliteit tussen protocollen te ondersteunen, definieert IoT Hub een algemene set berichtenfuncties die beschikbaar zijn in alle apparaatgerichte protocollen. Deze kunnen worden gebruikt in zowel apparaat-naar-cloud-berichtroutering als cloud-naar-apparaat-berichten.
Notitie
Sommige van de functies die in dit artikel worden genoemd, zoals cloud-naar-apparaat-berichten, apparaatdubbels en apparaatbeheer, zijn alleen beschikbaar in de standaardlaag van IoT Hub. Zie De juiste IoT Hub-laag voor uw oplossing kiezen voor meer informatie over de Basic- en Standard-/gratis IoT Hub-lagen.
IoT Hub implementeert apparaat-naar-cloud-berichten met behulp van een streamingberichtenpatroon. De apparaat-naar-cloud-berichten van IoT Hub lijken meer op Event Hubs-gebeurtenissen dan Service Bus-berichten omdat er een groot aantal gebeurtenissen is dat via de service wordt doorgegeven die door meerdere lezers kan worden gelezen.
Een IoT Hub-bericht bestaat uit:
Een vooraf bepaalde set systeemeigenschappen , zoals hieronder wordt vermeld.
Een set toepassingseigenschappen. Een woordenlijst met tekenreekseigenschappen die de toepassing kan definiëren en openen, zonder de hoofdtekst van het bericht te hoeven deserialiseren. IoT Hub wijzigt deze eigenschappen nooit.
Een berichttekst, die elk type gegevens kan zijn.
Elk apparaatprotocol implementeert instellingseigenschappen op verschillende manieren. Raadpleeg de gerelateerde MQTT - en AMQP-ontwikkelaarshandleidingen voor meer informatie.
Eigenschapsnamen en -waarden kunnen alleen alfanumerieke ASCII-tekens bevatten, plus {'!', '#', '$', '%, '&', ''', '*', '+', '-', '.', '^', '_', '`', '|', '~'} wanneer u apparaat-naar-cloud-berichten verzendt met behulp van het HTTPS-protocol of cloud-naar-apparaat-berichten verzendt.
Apparaat-naar-cloud-berichten met IoT Hub hebben de volgende kenmerken:
Apparaat-naar-cloud-berichten zijn duurzaam en worden gedurende maximaal zeven dagen bewaard in het standaardeindpunt voor berichten/gebeurtenissen van een IoT-hub.
Apparaat-naar-cloud-berichten kunnen maximaal 256 kB zijn en kunnen worden gegroepeerd in batches om verzendingen te optimaliseren. Batches kunnen maximaal 256 kB zijn.
IoT Hub staat willekeurige partitionering niet toe. Apparaat-naar-cloud-berichten worden gepartitioneerd op basis van hun oorspronkelijke deviceId.
Zoals uitgelegd in Toegang tot IoT Hub beheren, schakelt IoT Hub verificatie en toegangsbeheer per apparaat in.
U kunt berichten stempelen met informatie die in de eigenschappen van de toepassing wordt geplaatst. Zie berichtverrijkingen voor meer informatie.
Zie Azure IoT SDK's voor meer informatie over het coderen en decoderen van berichten die worden verzonden met behulp van verschillende protocollen.
Notitie
Elk IoT Hub-protocol biedt een eigenschap voor berichtinhoudstypen die wordt gerespecteerd bij het routeren van gegevens naar aangepaste eindpunten. Als u uw gegevens op de juiste manier wilt laten verwerken op de bestemming (bijvoorbeeld JSON die wordt behandeld als een tekenreeks die kan worden geparseerd in plaats van met Base64 gecodeerde binaire gegevens), moet u het juiste inhoudstype en tekenset voor het bericht opgeven.
Als u de berichttekst in een IoT Hub-routeringsquery wilt gebruiken, moet u een geldig JSON-object voor het bericht opgeven en de eigenschap van het inhoudstype van het bericht instellen op application/json;charset=utf-8.
Een geldige, routeerbare berichttekst kan er als volgt uitzien:
{
"timestamp": "2022-02-08T20:10:46Z",
"tag_name": "spindle_speed",
"tag_value": 100
}
Systeemeigenschappen van D2C IoT Hub-berichten
| Eigenschappen | Beschrijving | Gebruikerssettabel? | Trefwoord voor routeringsquery |
|---|---|---|---|
| message-id | Een door de gebruiker ingestelde id voor het bericht dat wordt gebruikt voor aanvraag-antwoordpatronen. Opmaak: Een hoofdlettergevoelige tekenreeks (maximaal 128 tekens lang) van ASCII 7-bits alfanumerieke tekens + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. |
Ja | messageId |
| iothub-enqueuedtime | De datum en tijd waarop het apparaat-naar-cloud-bericht is ontvangen door IoT Hub. | Nee | enqueuedTime |
| user-id | Een id die wordt gebruikt om de oorsprong van berichten op te geven. Wanneer berichten worden gegenereerd door IoT Hub, wordt deze ingesteld op {iot hub name}. |
Ja | userId |
| iothub-verbinding-apparaat-id | Een id die is ingesteld door IoT Hub op apparaat-naar-cloud-berichten. Het bevat de deviceId van het apparaat dat het bericht heeft verzonden. | Nee | connectionDeviceId |
| iothub-connection-module-id | Een id die is ingesteld door IoT Hub op apparaat-naar-cloud-berichten. Het bevat de moduleId van het apparaat dat het bericht heeft verzonden. | Nee | connectionModuleId |
| iothub-connection-auth-generation-id | Een id die is ingesteld door IoT Hub op apparaat-naar-cloud-berichten. Het bevat de connectionDeviceGenerationId (volgens apparaat-id-eigenschappen) van het apparaat dat het bericht heeft verzonden. | Nee | connectionDeviceGenerationId |
| iothub-connection-auth-method | Een verificatiemethode die is ingesteld door IoT Hub op apparaat-naar-cloud-berichten. Deze eigenschap bevat informatie over de verificatiemethode die wordt gebruikt om het apparaat te verifiëren dat het bericht verzendt. | Nee | connectionAuthMethod |
| iothub-app-iothub-creation-time-utc | Hiermee kan het apparaat de aanmaaktijd van gebeurtenissen verzenden bij het verzenden van gegevens in een batch. | Ja | aanmaaktijd-utc |
| iothub-creation-time-utc | Hiermee kan het apparaat de aanmaaktijd van gebeurtenissen verzenden wanneer er één bericht tegelijk wordt verzonden. | Ja | aanmaaktijd-utc |
| dt-dataschema | Deze waarde wordt ingesteld door IoT Hub op apparaat-naar-cloud-berichten. Het bevat de apparaatmodel-id die is ingesteld in de apparaatverbinding. | Nee | $dt-dataschema |
| dt-subject | De naam van het onderdeel dat de apparaat-naar-cloud-berichten verzendt. | Ja | $dt onderwerp |
Toepassingseigenschappen van D2C IoT Hub-berichten
Een veelvoorkomend gebruik van toepassingseigenschappen is het verzenden van een tijdstempel vanaf het apparaat met behulp van de iothub-creation-time-utc eigenschap om vast te leggen wanneer het bericht door het apparaat is verzonden. De notatie van deze tijdstempel moet UTC zijn zonder tijdzonegegevens. Is bijvoorbeeld 2021-04-21T11:30:16Z geldig, 2021-04-21T11:30:16-07:00 is ongeldig:
{
"applicationId":"5782ed70-b703-4f13-bda3-1f5f0f5c678e",
"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":{}
}
Systeemeigenschappen van C2D IoT Hub-berichten
| Eigenschappen | Beschrijving | Gebruikerssettabel? |
|---|---|---|
| message-id | Een door de gebruiker ingestelde id voor het bericht dat wordt gebruikt voor aanvraag-antwoordpatronen. Opmaak: Een hoofdlettergevoelige tekenreeks (maximaal 128 tekens lang) van ASCII 7-bits alfanumerieke tekens + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. |
Ja |
| reeksnummer | Een nummer (uniek per apparaatwachtrij) dat door IoT Hub is toegewezen aan elk cloud-naar-apparaat-bericht. | Nee |
| to | Een bestemming die is opgegeven in cloud-naar-apparaat-berichten . | Nee |
| absolute verlooptijd | De datum en tijd waarop het bericht verloopt. | Ja |
| correlatie-id | Een tekenreekseigenschap in een antwoordbericht dat doorgaans de MessageId van de aanvraag bevat, in aanvraag-antwoordpatronen. | Ja |
| user-id | Een id die wordt gebruikt om de oorsprong van berichten op te geven. Wanneer berichten worden gegenereerd door IoT Hub, wordt deze ingesteld op {iot hub name}. |
Ja |
| iothub-ack | Een generator voor feedbackberichten. Deze eigenschap wordt gebruikt in cloud-naar-apparaat-berichten om IoT Hub aan te vragen om feedbackberichten te genereren als gevolg van het verbruik van het bericht door het apparaat. Mogelijke waarden: geen (standaard): er wordt geen feedbackbericht gegenereerd, positief: ontvang een feedbackbericht als het bericht is voltooid, negatief: ontvang een feedbackbericht als het bericht is verlopen (of het maximum aantal bezorgingen is bereikt) zonder dat het apparaat is voltooid of volledig: zowel positief als negatief. | Ja |
Systeemeigenschapsnamen
De namen van de systeemeigenschappen variëren op basis van het eindpunt waarnaar de berichten worden gerouteerd. Zie de onderstaande tabel voor meer informatie over deze namen.
| Naam van systeemeigenschap | Event Hubs | Azure Storage | Service Bus | Event Grid |
|---|---|---|---|---|
| Bericht-id | message-id | messageId | MessageId | message-id |
| Gebruikers-id | user-id | userId | Gebruikers-id | user-id |
| Apparaat-id van verbinding | iothub-verbinding-apparaat-id | connectionDeviceId | iothub-verbinding-apparaat-id | iothub-verbinding-apparaat-id |
| Verbindingsmodule-id | iothub-connection-module-id | connectionModuleId | iothub-connection-module-id | iothub-connection-module-id |
| Generatie-id van verbindingsverificatie | iothub-connection-auth-generation-id | connectionDeviceGenerationId | iothub-connection-auth-generation-id | iothub-connection-auth-generation-id |
| Verificatiemethode voor verbinding | iothub-connection-auth-method | connectionAuthMethod | iothub-connection-auth-method | iothub-connection-auth-method |
| contentType | inhoudstype | contentType | ContentType | iothub-content-type |
| contentEncoding | inhoudscodering | contentEncoding | ContentEncoding | iothub-content-codering |
| iothub-enqueuedtime | iothub-enqueuedtime | enqueuedTime | N.v.t. | iothub-enqueuedtime |
| CorrelationId | correlatie-id | correlationId | CorrelationId | correlatie-id |
| dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema |
| dt-subject | dt-subject | dt-subject | dt-subject | dt-subject |
Berichtgrootte
IoT Hub meet de berichtgrootte op een protocolagnostische manier, waarbij alleen de werkelijke nettolading wordt overwogen. De grootte in bytes wordt berekend als de som van de volgende waarden:
- De grootte van de hoofdtekst in bytes.
- De grootte in bytes van alle waarden van de berichtsysteemeigenschappen.
- De grootte in bytes van alle namen en waarden van gebruikerseigenschappen.
Eigenschapsnamen en -waarden zijn beperkt tot ASCII-tekens, dus de lengte van de tekenreeksen is gelijk aan de grootte in bytes.
Anti-adresvervalsingseigenschappen
Om adresvervalsing van apparaten in apparaat-naar-cloud-berichten te voorkomen, worden alle berichten gestempeld met de volgende eigenschappen:
- iothub-connection-device-id
- iothub-connection-auth-generation-id
- iothub-connection-auth-method
De eerste twee bevatten de deviceId en generationId van het oorspronkelijke apparaat, volgens de eigenschappen van de apparaat-id.
De eigenschap iothub-connection-auth-method bevat een geserialiseerd JSON-object met de volgende eigenschappen:
{
"scope": "{ hub | device | module }",
"type": "{ symkey | sas | x509 }",
"issuer": "iothub"
}
Volgende stappen
- Zie Quota en beperking van IoT Hub voor informatie over berichtgroottelimieten in IoT Hub.
- Zie de quickstarts voor informatie over het maken en lezen van IoT Hub-berichten in verschillende programmeertalen.
- Zie gebeurtenisschema's voor niet-telemetrie die door IoT Hub worden gegenereerd voor meer informatie over de structuur van niet-telemetriegebeurtenissen die door IoT Hub worden gegenereerd.