Skapa och läsa IoT Hub-meddelanden

  • Artikel

För att stödja sömlös samverkan mellan protokoll definierar IoT Hub en gemensam uppsättning meddelandefunktioner som är tillgängliga i alla enhetsriktade protokoll. Dessa kan användas i både meddelandedirigering från enhet till moln och meddelanden från moln till enhet.

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 eftersom det finns en stor mängd händelser som passerar genom tjänsten som kan läsas av flera läsare.

Ett IoT Hub-meddelande består av:

  • En fördefinierad uppsättning systemegenskaper enligt listan nedan.

  • 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 relaterade utvecklarguider för MQTT och AMQP .

Egenskapsnamn och värden kan bara innehålla alfanumeriska ASCII-tecken, plus {'!', '#', '$', '%, '&', ''', '*', '+', '-', '.', '^', '_', '`', '|', '~'} när du skickar meddelanden från enhet till moln med hjälp av HTTPS-protokollet eller skickar meddelanden från molnet till enheten.

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 berikning av meddelanden.

Mer information om hur du kodar och avkodar meddelanden som skickas med olika protokoll finns i Azure IoT SDK:er.

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 att JSON behandlas som en parsbar sträng i stället för Base64-kodade binära data) måste du ange lämplig innehållstyp och teckenuppsättning för meddelandet.

Om du vill använda meddelandetexten i en IoT Hub-routningsfråga måste du ange ett giltigt JSON-objekt för meddelandet och ange egenskapen innehållstyp för meddelandet till application/json;charset=utf-8.

En giltig, dirigerbar meddelandetext kan se ut så här:

{
    "timestamp": "2022-02-08T20:10:46Z",
    "tag_name": "spindle_speed",
    "tag_value": 100
}

Systemegenskaper för D2C IoT Hub-meddelanden

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 + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. 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. När meddelanden genereras av IoT Hub är det inställt på {iot hub name}. 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 D2C IoT Hub-meddelanden

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, 2021-04-21T11:30:16-07:00 är ogiltigt:

{
  "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":{}
}

Systemegenskaper för C2D IoT Hub-meddelanden

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 + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. 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 det inställt på {iot hub name}. 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. Mer information om dessa namn finns i tabellen nedan.

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 Anslut ion iothub-connection-device-id connectionDeviceId iothub-connection-device-id iothub-connection-device-id
modul-ID för Anslut ion iothub-connection-module-id connectionModuleId iothub-connection-module-id iothub-connection-module-id
Anslut ion auth generation ID iothub-connection-auth-generation-id connectionDeviceGenerationId iothub-connection-auth-generation-id iothub-connection-auth-generation-id
Anslut ion auth-metod 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