Meddelandeberikanden för IoT Hub meddelanden från enhet till moln
Meddelande berikanden är möjligheten för en IoT-hubb att stämpla meddelanden med ytterligare information innan meddelandena skickas till den avsedda slutpunkten. En anledning till att använda meddelandeberikningar är att inkludera data som kan användas för att förenkla nedströmsbearbetning. Om du till exempel utökar enhetstelemetrimeddelanden med en tagg för enhetstvillingar kan du minska belastningen på kunderna för att göra anrop till enhetstvilling-API:et för den här informationen.
En meddelandeberikning har tre viktiga element:
Berikningsnamn eller nyckel
Ett värde
En eller flera slutpunkter för vilka berikningen ska tillämpas.
Nyckeln är en sträng. En nyckel kan bara innehålla alfanumeriska tecken eller dessa specialtecken: bindestreck (-), understreck (_) och punkt (.).
Värdet kan vara något av följande exempel:
Alla statiska strängar. Dynamiska värden som villkor, logik, åtgärder och funktioner tillåts inte. Om du till exempel utvecklar ett SaaS-program som används av flera kunder kan du tilldela en identifierare till varje kund och göra den identifieraren tillgänglig i programmet. När programmet körs stämplar IoT Hub enhetens telemetrimeddelanden med kundens identifierare, vilket gör det möjligt att bearbeta meddelandena på olika sätt för varje kund.
Namnet på den IoT-hubb som skickar meddelandet. Det här värdet är $iothubname.
Information från enhetstvillingen, till exempel dess sökväg. Exempel är $twin.tags.field och $twin.tags.latitude.
Anteckning
För närvarande stöds endast $iothubname, $twin.tags, $twin.properties.desired och $twin.properties.reported variabler för meddelandeberikning. Dessutom stöds endast primitiva typer för berikningar. Meddelanden kan inte utökas med objekttyper.
Meddelandeberikningar läggs till som programegenskaper för meddelanden som skickas till valda slutpunkter.
Tillämpa berikningar
Meddelandena kan komma från alla datakällor som stöds av IoT Hub meddelanderoutning, inklusive följande exempel:
- enhetstelemetri, till exempel temperatur eller tryck
- meddelanden om ändring av enhetstvilling – ändringar i enhetstvillingen
- händelser i enhetens livscykel, till exempel när enheten skapas eller tas bort
Du kan lägga till berikanden i meddelanden som går till den inbyggda slutpunkten för en IoT-hubb eller till meddelanden som dirigeras till anpassade slutpunkter som Azure Blob Storage, en Service Bus-kö eller ett Service Bus-ämne.
Du kan också lägga till berikanden i meddelanden som publiceras i Event Grid genom att först skapa en Event Grid-prenumeration med meddelandetypen enhetstelemetri. Baserat på den här prenumerationen skapar vi en standardväg i Azure IoT Hub för telemetrin. Den här enkla vägen kan hantera alla dina Event Grid-prenumerationer. Du kan sedan konfigurera berikanden för slutpunkten med hjälp av fliken Berika meddelanden i avsnittet IoT Hub Meddelanderoutning. Information om hur du reagerar på händelser med event grid finns i Iot Hub och Event Grid.
Berikningar tillämpas per slutpunkt. Om du anger fem berikanden som ska stämplas för en specifik slutpunkt stämplas alla meddelanden som går till slutpunkten med samma fem berikanden.
Berikningar kan konfigureras med hjälp av följande metoder:
| Metod | Kommando |
|---|---|
| Portalen | Azure Portal Se självstudien om meddelande berikanden |
| Azure CLI | az iot hub message-enrichment |
| Azure PowerShell | Add-AzIotHubMessageEnrichment |
Om du lägger till meddelandeberikningar läggs inte svarstiden till meddelanderoutningen.
Om du vill prova meddelandeberikningar kan du läsa självstudien om meddelande berikanden
Begränsningar
Du kan lägga till upp till 10 berikanden per IoT-hubb för dessa hubbar på standard- eller basic-nivån. För IoT-hubbar på den kostnadsfria nivån kan du lägga till upp till 2 berikanden.
Om du i vissa fall utökar ett meddelande med ett värde inställt på en tagg eller egenskap i enhetstvillingen stämplas värdet med den angivna sökvägen för enhetstvillingen. Om till exempel ett berikningsvärde är inställt på $twin.tags.field stämplas meddelandena med strängen "$twin.tags.field", i stället för värdet för det fältet från tvillingen. Det här beteendet inträffar i följande fall:
Din IoT-hubb ligger på den grundläggande nivån. IoT-hubbar på basic-nivå stöder inte enhetstvillingar.
Din IoT-hubb finns på standardnivån, men enhetstvillingsökvägen som används för värdet för berikningen finns inte. Om berikningsvärdet till exempel är inställt på $twin.tags.location och enhetstvillingen inte har någon platsegenskap under taggar, stämplas meddelandet med strängen "$twin.tags.location".
Din IoT-hubb finns på standardnivån, men enhetstvillingsökvägen som används för värdet för berikningen matchas till ett objekt i stället för en enkel egenskap. Om berikningsvärdet till exempel är inställt på $twin.tags.location, och platsegenskapen under taggar är ett objekt som innehåller underordnade egenskaper som
{"building": 43, "room": 503}, stämplas meddelandet med strängen "$twin.tags.location".
Uppdateringar till en enhetstvilling kan det ta upp till fem minuter att återspeglas i motsvarande berikningsvärde.
Den totala meddelandestorleken, inklusive berikningarna, får inte överstiga 256 kB. Om meddelandestorleken överskrider 256 kB släpper IoT-hubben meddelandet. Du kan använda IoT Hub mått för att identifiera och felsöka fel när meddelanden tas bort. Du kan till exempel övervaka telemetrimeddelandenas inkompatibla mått (d2c.telemetry.egress.invalid) i routningsmåtten. Mer information finns i Övervaka IoT Hub.
Meddelandeberikningar gäller inte för ändringshändelser för digitala tvillingar.
Moduler ärver inte tvillingtaggar från motsvarande enheter. Berikningar för meddelanden som kommer från enhetsmoduler (till exempel från IoT Edge moduler) måste använda tvillingtaggar som anges på modultvillingen.
Prissättning
Meddelandeberikanden är tillgängliga utan extra kostnad. För närvarande debiteras du när du skickar ett meddelande till en IoT-hubb. Du debiteras bara en gång för det meddelandet, även om meddelandet går till flera slutpunkter.
Nästa steg
Mer information om hur du dirigerar meddelanden till en IoT-hubb finns i de här artiklarna: