Dela via

Meddelandeberikningar för IoT Hub från enhet till moln

Meddelandeberikningar är möjligheten för en IoT-hubb att stämpla meddelanden med ytterligare information innan meddelandena skickas till den angivna 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 behöva göra API-anrop till enhetstvillingar för denna information.

Flöde för meddelandeberikningar

En meddelandeberikning har tre viktiga element:

  • Berikningsnamn eller nyckel

  • Ett värde

  • En eller flera slutpunkter som berikningen ska tillämpas för.

Den nyckeln är en sträng. En nyckel får bara innehålla alfanumeriska tecken eller dessa specialtecken: bindestreck (-), understreck (_) och punkt (.).

Det 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 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.

    Anmärkning

    För närvarande är endast $iothubname, $twin.tags, $twin.properties.desiredoch $twin.properties.reported variabler som stöds 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 i 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:

  • telemetri för enheten, till exempel temperatur eller tryck
  • Meddelanden om ändring av enhetstvilling – ändringar i enhetstvillingen
  • Händelser under 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, till exempel 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 berikningar för slutpunkten med hjälp av fliken Enrich-meddelanden i avsnittet IoT Hub Meddelandedirigering. Information om hur du reagerar på händelser med hjälp av Event Grid finns i IoT Hub och Event Grid.

Förbättringar tillämpas per slutpunkt. Om du anger fem berikningar som ska appliceras på en specifik slutpunkt, appliceras samma fem förbättringar på alla meddelanden som går till den slutpunkten.

Förbättringar kan ställas in med hjälp av följande metoder:

Metod Kommando
Portal Azure-portalen Se självstudien om meddelandeberikning
Azure CLI (kommandoradsgränssnittet för Azure) az iot hub meddelandeberikning
Azure PowerShell Add-AzIotHubMessageEnrichment

Att lägga till meddelandeberikningar orsakar ingen fördröjning i meddelanderoutningen.

Information om hur du provar meddelandeberikningar finns i självstudien om meddelandeberikningar

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 berikningar.

  • I vissa fall, om du berikar ett meddelande med ett värde som är inställt på en tagg eller egenskap i enhetstvillingen, stämplas värdet med den angivna sökvägen till enhetstvillingen. Om ett berikningsvärde till exempel ä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 fältet från tvillingen. Det här beteendet inträffar i följande fall:

    • Din IoT-hubb är på basic-nivån. IoT-hubbar på grundläggande nivå stöder inte enhetstvillingar.

    • Din IoT-hubb är i standardnivån, men den enhetstvillingsökväg som används för värdet av berikningen existerar inte. Om berikningsvärdet till exempel är inställt på $twin.tags.location och enhetstvillingen inte har någon location egenskap under taggar stämplas meddelandet med strängen "$twin.tags.location".

    • Din IoT-hubb finns på standardnivå, men sökvägen för enhetstvillingen som används för värdet för berikningen löses upp till ett objekt i stället för en enkel egenskap. Om berikningsvärdet till exempel är inställt på $twin.tags.location och location egenskapen under tags är ett objekt som innehåller underordnade egenskaper som {"building": 43, "room": 503}, stämplas meddelandet med strängen "$twin.tags.location".

  • Ändringar i enhetstvillingen kan ta upp till fem minuter innan de reflekteras i det motsvarande berikningsvärdet.

  • Den totala meddelandestorleken, inklusive berikningarna, får inte överstiga 256 KB. Om en meddelandestorlek överskrider 256 kB tar IoT-hubben bort 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 måttet inkompatibla telemetrimeddelanden (d2c.telemetry.egress.invalid) i routningsmåtten. Mer information finns i Övervaka IoT Hub.

  • Meddelandeanpassningar gäller inte för ändringshändelser för digitala tvillingar.

  • Moduler ärver inte tvillingtaggar från motsvarande enheter. För att berika meddelanden från enhetsmoduler (som exempelvis IoT Edge-moduler) måste tvillingtaggarna på modultvillingen användas.

Prissättning

Meddelandeberikning är tillgänglig 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 meddelandet, även om meddelandet går till flera slutpunkter.

Nästa steg

Läs de här artiklarna om du vill ha mer information om hur du dirigerar meddelanden till en IoT-hubb: