IoT Hub-berichten maken en lezen
IoT Hub definieert een gemeenschappelijke set berichtenfuncties die beschikbaar zijn in alle apparaatgerichte protocollen om interoperabiliteit tussen protocollen te ondersteunen. Deze functies kunnen worden gebruikt in zowel apparaat-naar-cloud-berichten 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 meerdere lezers kunnen lezen.
Een IoT Hub-bericht bestaat uit:
Een vooraf bepaalde set systeemeigenschappen , zoals verderop in dit artikel wordt beschreven.
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. Zie de handleiding voor MQTT-protocollen en ontwikkelaarshandleidingen voor AMQP-protocollen voor meer informatie.
Wanneer u apparaat-naar-cloud-berichten verzendt met behulp van het HTTPS-protocol of cloud-naar-apparaat-berichten verzendt, kunnen eigenschapsnamen en -waarden alleen alfanumerieke ASCII-tekens bevatten, plus ! # $ % & ' * + - . ^ _ ` | ~ .
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 geen willekeurige partitionering 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.
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), geeft u het juiste inhoudstype en tekenset voor het bericht op.
Als u de berichttekst in een IoT Hub-routeringsquery wilt gebruiken, geeft u een geldig JSON-object voor het bericht op en stelt u de eigenschap van het inhoudstype van het bericht in op application/json;charset=utf-8.
In het volgende voorbeeld ziet u een geldige, routeerbare berichttekst:
{
"timestamp": "2022-02-08T20:10:46Z",
"tag_name": "spindle_speed",
"tag_value": 100
}
Systeemeigenschappen van apparaat-naar-cloud-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 plus - : . + % _ # * ? ! ( ) , = @ ; $ '. |
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. | 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 apparaat-naar-cloud-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, maar 2021-04-21T11:30:16-07:00 is ongeldig.
{
"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":{}
}
Systeemeigenschappen van cloud-naar-apparaat-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 plus - : . + % _ # * ? ! ( ) , = @ ; $ '. |
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, is de gebruikers-id de naam van de IoT-hub. | 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.
| 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.