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.

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 soort gegevens kan bevatten.

Elk apparaatprotocol implementeert instellingseigenschappen op verschillende manieren. Zie Communiceren met een IoT-hub met behulp van het MQTT-protocol en communiceren met uw IoT-hub met behulp van het AMQP-protocol 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 met behulp van Microsoft Entra ID, maakt IoT Hub verificatie en toegangsbeheer per apparaat mogelijk.

• U kunt berichten stempelen met informatie die in de eigenschappen van de toepassing wordt geplaatst. Voor meer informatie, zie Berichtverrijkingen voor apparaat-naar-cloud IoT Hub-berichten.

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

Toepassingseigenschappen van apparaat-naar-cloud-berichten

Een veelvoorkomend gebruik van toepassingseigenschappen is het verzenden van een tijdstempel van het apparaat met behulp van de iothub-creation-time-utc eigenschap die moet worden vastgelegd wanneer het apparaat het bericht verzendt. 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

Systeemeigenschapsnamen

De namen van de systeemeigenschappen variëren op basis van het eindpunt waarnaar de berichten worden gerouteerd.

Berichtschema bij routeringseindpunten

Wanneer IoT Hub een apparaat-naar-cloud-bericht naar een aangepast eindpunt stuurt, levert het het bericht in drie delen:

• Body: De berichtbody wordt as-is (niet base64-gecodeerd) geleverd aan Event Hubs, Service Bus wachtrijen en Service Bus onderwerpen. Voor Azure Storage en Azure Cosmos DB hangt de codering af van het type bericht en de eigenschappen van het contentcoderingssysteem. Zie IoT Hub eindpunten voor meer informatie.

• Systeemeigenschappen: Systeemeigenschappen van IoT Hub verschijnen op het eindpunt door gebruik te maken van de bestemmingsspecifieke namen die in systeemeigenschapsnamen staan. Deze eigenschappen behouden de apparaatidentiteit en de metadata van berichten. Bijvoorbeeld iothub-connection-device-id identificeert het oorspronkelijke apparaat.

• Applicatie-eigenschappen: Applicatie-eigenschappen die het apparaat instelt of die je toevoegt via berichtverrijkingen worden ongewijzigd doorgegeven.

Het volgende voorbeeld toont een logische weergave van een telemetriebericht dat naar een Event Hubs-eindpunt wordt gerouteerd:

{
  "body": {
    "timestamp": "2022-02-08T20:10:46Z",
    "tag_name": "spindle_speed",
    "tag_value": 100
  },
  "systemProperties": {
    "message-id": "a1b2c3d4-0000-1111-2222-333344445555",
    "iothub-connection-device-id": "sample-device-01",
    "iothub-connection-auth-method": "{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\"}",
    "iothub-enqueuedtime": "2022-02-08T20:10:46.143Z",
    "content-type": "application/json",
    "content-encoding": "utf-8"
  },
  "applicationProperties": {
    "iothub-creation-time-utc": "2022-02-08T20:10:46.021Z"
  }
}

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 apparaatvervalsing in apparaat-naar-cloud-berichten te voorkomen, stempelt IoT Hub alle berichten met de volgende eigenschappen:

• iothub-connection-device-id
• iothub-connection-auth-generation-id
• iothub-connection-auth-method (authenticatiemethode voor iothub-verbinding)

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 zelfstudie: Telemetrie verzenden van een IoT Plug and Play-apparaat naar Azure IoT Hub voor meer informatie over het maken en lezen van IoT Hub-berichten in verschillende programmeertalen.
• Voor meer informatie over de structuur van niet-telemetriegebeurtenissen die zijn gegenereerd door IoT Hub, raadpleegt u azure IoT Hub niet-telemetriegebeurtenissenschema's.