Skapa och läsa IoT Hub-meddelanden
För att stödja samverkan mellan protokoll definierar IoT Hub en gemensam uppsättning meddelandefunktioner som är tillgängliga i alla enhetsriktade protokoll. Dessa funktioner kan användas i både enhet-till-moln-meddelanden och moln-till-enhet-meddelanden.
Kommentar
Några av de funktioner som nämns i den här artikeln, t.ex. moln till enhet-meddelanden, enhetstvillingar och enhetshantering, är bara tillgängliga på IoT Hubs standardnivå. Mer information om de grundläggande och standard-/kostnadsfria IoT Hub-nivåerna finns i Välj rätt IoT Hub-nivå för din lösning.
IoT Hub implementerar meddelanden från enhet till moln med hjälp av ett mönster för strömmande meddelanden. IoT Hubs enhets-till-moln-meddelanden är mer som Event Hubs-händelser än Service Bus-meddelanden i och med att det finns en stor mängd händelser som passerar genom tjänsten som flera läsare kan läsa.
Ett IoT Hub-meddelande består av:
En fördefinierad uppsättning systemegenskaper enligt beskrivningen senare i den här artikeln.
En uppsättning programegenskaper. En ordlista med strängegenskaper som programmet kan definiera och komma åt, utan att behöva deserialisera meddelandetexten. IoT Hub ändrar aldrig dessa egenskaper.
En meddelandetext, som kan vara vilken typ av data som helst.
Varje enhetsprotokoll implementerar inställningsegenskaper på olika sätt. Mer information finns i utvecklarguiden för MQTT-protokoll och AMQP-protokollguiden.
När du skickar meddelanden från enhet till moln med hjälp av HTTPS-protokollet eller skickar meddelanden från moln till enhet kan egenskapsnamn och värden endast innehålla alfanumeriska ASCII-tecken plus ! # $ % & ' * + - . ^ _ ` | ~ .
Meddelanden från enhet till moln med IoT Hub har följande egenskaper:
Meddelanden från enhet till moln är hållbara och behålls i en IoT-hubbs standardslutpunkt för meddelanden/händelser i upp till sju dagar.
Meddelanden från enhet till moln kan vara högst 256 kB och kan grupperas i batchar för att optimera sändningarna. Batchar kan vara högst 256 KB.
IoT Hub tillåter inte godtycklig partitionering. Meddelanden från enhet till moln partitioneras baserat på deras ursprungliga deviceId.
Som beskrivs i Kontrollera åtkomst till IoT Hub möjliggör IoT Hub autentisering och åtkomstkontroll per enhet.
Du kan stämpla meddelanden med information som går in i programegenskaperna. Mer information finns i meddelandeberikningar.
Kommentar
Varje IoT Hub-protokoll innehåller en egenskap för meddelandeinnehållstyp som respekteras när data dirigeras till anpassade slutpunkter. Om du vill att dina data ska hanteras korrekt på målet (till exempel JSON behandlas som en parsbar sträng i stället för Base64-kodade binära data) anger du lämplig innehållstyp och teckenuppsättning för meddelandet.
Om du vill använda meddelandetexten i en IoT Hub-routningsfråga anger du ett giltigt JSON-objekt för meddelandet och anger innehållets typegenskap till application/json;charset=utf-8.
I följande exempel visas en giltig, dirigerbar meddelandetext:
{
"timestamp": "2022-02-08T20:10:46Z",
"tag_name": "spindle_speed",
"tag_value": 100
}
Systemegenskaper för meddelanden från enhet till moln
| Property | beskrivning | Användarsättbar? | Nyckelord för routningsfråga |
|---|---|---|---|
| message-id | En användaruppsättningsbar identifierare för meddelandet som används för mönster för begäran-svar. Format: En skiftlägeskänslig sträng (upp till 128 tecken lång) med 7-bitars alfanumeriska ASCII-tecken plus - : . + % _ # * ? ! ( ) , = @ ; $ '. |
Ja | messageId |
| iothub-enqueuedtime | Datum och tid då meddelandet Enhet till moln togs emot av IoT Hub. | Nej | enqueuedTime |
| användar-ID | Ett ID som används för att ange ursprunget för meddelanden. | Ja | Användar-ID |
| iothub-connection-device-id | Ett ID som anges av IoT Hub för meddelanden från enhet till moln. Den innehåller deviceId för enheten som skickade meddelandet. | Nej | connectionDeviceId |
| iothub-connection-module-id | Ett ID som anges av IoT Hub för meddelanden från enhet till moln. Den innehåller moduleId för enheten som skickade meddelandet. | Nej | connectionModuleId |
| iothub-connection-auth-generation-id | Ett ID som anges av IoT Hub för meddelanden från enhet till moln. Den innehåller connectionDeviceGenerationId (enligt enhetsidentitetsegenskaper) för den enhet som skickade meddelandet. | Nej | connectionDeviceGenerationId |
| iothub-connection-auth-method | En autentiseringsmetod som anges av IoT Hub för meddelanden från enhet till moln. Den här egenskapen innehåller information om den autentiseringsmetod som används för att autentisera enheten som skickar meddelandet. | Nej | connectionAuthMethod |
| iothub-app-iothub-creation-time-utc | Tillåter att enheten skickar skapandetid för händelser när data skickas i en batch. | Ja | creation-time-utc |
| iothub-creation-time-utc | Tillåter att enheten skickar skapandetiden för händelser när ett meddelande skickas i taget. | Ja | creation-time-utc |
| dt-dataschema | Det här värdet anges av IoT Hub på meddelanden från enhet till moln. Den innehåller enhetsmodell-ID:t som angetts i enhetsanslutningen. | Nej | $dt-dataschema |
| dt-subject | Namnet på komponenten som skickar meddelanden från enhet till moln. | Ja | $dt ämne |
Programegenskaper för meddelanden från enhet till moln
En vanlig användning av programegenskaper är att skicka en tidsstämpel från enheten med hjälp av iothub-creation-time-utc egenskapen för att registrera när meddelandet skickades av enheten. Formatet för den här tidsstämpeln måste vara UTC utan tidszonsinformation. Är till exempel 2021-04-21T11:30:16Z giltigt, men 2021-04-21T11:30:16-07:00 är ogiltigt.
{
"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":{}
}
Systemegenskaper för meddelanden från moln till enhet
| Property | beskrivning | Användarsättbar? |
|---|---|---|
| message-id | En användaruppsättningsbar identifierare för meddelandet som används för mönster för begäran-svar. Format: En skiftlägeskänslig sträng (upp till 128 tecken lång) med 7-bitars alfanumeriska ASCII-tecken plus - : . + % _ # * ? ! ( ) , = @ ; $ '. |
Ja |
| sekvensnummer | Ett tal (unikt per enhetskö) som tilldelats av IoT Hub till varje meddelande från moln till enhet. | Nej |
| to | Ett mål som anges i meddelanden från moln till enhet . | Nej |
| absolut förfallotid | Datum och tid då meddelandet upphör att gälla. | Ja |
| korrelations-ID | En strängegenskap i ett svarsmeddelande som vanligtvis innehåller MessageId för begäran, i mönster för begäran-svar. | Ja |
| användar-ID | Ett ID som används för att ange ursprunget för meddelanden. När meddelanden genereras av IoT Hub är användar-ID:t IoT Hub-namnet. | Ja |
| iothub-ack | En generator för feedbackmeddelanden. Den här egenskapen används i meddelanden från moln till enhet för att begära att IoT Hub ska generera feedbackmeddelanden som ett resultat av enhetens användning av meddelandet. Möjliga värden: ingen (standard): inget feedbackmeddelande genereras, positiv: ta emot ett feedbackmeddelande om meddelandet har slutförts, negativt: ta emot ett feedbackmeddelande om meddelandet har upphört att gälla (eller maximalt antal leveranser har nåtts) utan att slutföras av enheten eller fullständig: både positiv och negativ. | Ja |
Namn på systemegenskap
Namnen på systemegenskapen varierar beroende på den slutpunkt som meddelandena dirigeras till.
| Namn på systemegenskap | Event Hubs | Azure Storage | Service Bus | Event Grid |
|---|---|---|---|---|
| Meddelande-ID | message-id | messageId | MessageId | message-id |
| Användar-ID | användar-ID | Användar-ID | AnvändarID | användar-ID |
| Enhets-ID för anslutning | iothub-connection-device-id | connectionDeviceId | iothub-connection-device-id | iothub-connection-device-id |
| Anslutningsmodul-ID | iothub-connection-module-id | connectionModuleId | iothub-connection-module-id | iothub-connection-module-id |
| Autentiseringsgenererings-ID för anslutning | iothub-connection-auth-generation-id | connectionDeviceGenerationId | iothub-connection-auth-generation-id | iothub-connection-auth-generation-id |
| Autentiseringsmetod för anslutning | iothub-connection-auth-method | connectionAuthMethod | iothub-connection-auth-method | iothub-connection-auth-method |
| contentType | innehållstyp | contentType | ContentType | iothub-content-type |
| contentEncoding | content-encoding | contentEncoding | ContentEncoding | iothub-content-encoding |
| iothub-enqueuedtime | iothub-enqueuedtime | enqueuedTime | Ej tillämpligt | iothub-enqueuedtime |
| CorrelationId | korrelations-ID | correlationId | CorrelationId | korrelations-ID |
| dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema |
| dt-subject | dt-subject | dt-subject | dt-subject | dt-subject |
Meddelandestorlek
IoT Hub mäter meddelandestorleken på ett protokolloberoende sätt med tanke på den faktiska nyttolasten. Storleken i byte beräknas som summan av följande värden:
- Kroppsstorleken i byte.
- Storleken i byte för alla värden för meddelandesystemets egenskaper.
- Storleken i byte för alla användaregenskapsnamn och värden.
Egenskapsnamn och värden är begränsade till ASCII-tecken, så längden på strängarna är lika med storleken i byte.
Egenskaper för skydd mot förfalskning
För att undvika enhetsförfalskning i meddelanden från enhet till moln stämplar IoT Hub alla meddelanden med följande egenskaper:
- iothub-connection-device-id
- iothub-connection-auth-generation-id
- iothub-connection-auth-method
De första två innehåller deviceId och generationId för den ursprungliga enheten, enligt egenskaper för enhetsidentitet.
Egenskapen iothub-connection-auth-method innehåller ett JSON-serialiserat objekt med följande egenskaper:
{
"scope": "{ hub | device | module }",
"type": "{ symkey | sas | x509 }",
"issuer": "iothub"
}
Nästa steg
- Information om gränser för meddelandestorlek i IoT Hub finns i IoT Hub-kvoter och begränsning.
- Information om hur du skapar och läser IoT Hub-meddelanden på olika programmeringsspråk finns i Snabbstarter.
- Mer information om strukturen för icke-telemetrihändelser som genereras av IoT Hub finns i Händelsescheman för icke-telemetri i IoT Hub.