Berichtverrijkingen voor apparaat-naar-cloud-IoT Hub-berichten
Berichtverrijkingen is de mogelijkheid van een IoT-hub om berichten te stempelen met aanvullende informatie voordat de berichten naar het aangewezen eindpunt worden verzonden. Een reden om berichtverrijkingen te gebruiken, is om gegevens op te nemen die kunnen worden gebruikt om downstreamverwerking te vereenvoudigen. Het verrijken van telemetrieberichten van apparaten met een tag van een apparaatdubbel kan bijvoorbeeld de belasting voor klanten verminderen om API-aanroepen voor apparaatdubbels te maken voor deze informatie.
Een berichtverrijking heeft drie belangrijke elementen:
Verrijkingsnaam of -sleutel
Een waarde
Een of meer eindpunten waarop de verrijking moet worden toegepast.
De sleutel is een tekenreeks. Een sleutel mag alleen alfanumerieke tekens of deze speciale tekens bevatten: afbreekstreepje (-), onderstrepingsteken (_) en punt (.).
De waarde kan een van de volgende voorbeelden zijn:
Een statische tekenreeks. Dynamische waarden, zoals voorwaarden, logica, bewerkingen en functies, zijn niet toegestaan. Als u bijvoorbeeld een SaaS-toepassing ontwikkelt die door meerdere klanten wordt gebruikt, kunt u aan elke klant een id toewijzen en die id beschikbaar maken in de toepassing. Wanneer de toepassing wordt uitgevoerd, stempelt IoT Hub de telemetrieberichten van het apparaat af met de klant-id, zodat de berichten voor elke klant anders kunnen worden verwerkt.
De naam van de IoT-hub die het bericht verzendt. Deze waarde is $iothubname.
Informatie van de apparaatdubbel, zoals het pad. Voorbeelden zijn $twin.tags.field en $twin.tags.latitude.
Notitie
Op dit moment zijn alleen $iothubname, $twin.tags, $twin.properties.desired en $twin.properties.reported ondersteunde variabelen voor berichtverrijking. Bovendien worden alleen primitieve typen ondersteund voor verrijkingen. Berichten kunnen niet worden verrijkt met objecttypen.
Berichtverrijkingen worden toegevoegd als toepassingseigenschappen voor berichten die naar de gekozen eindpunten worden verzonden.
Verrijkingen toepassen
De berichten kunnen afkomstig zijn van elke gegevensbron die wordt ondersteund door IoT Hub berichtroutering, waaronder de volgende voorbeelden:
- apparaattelemetrie, zoals temperatuur of druk
- wijzigingsmeldingen voor apparaatdubbels - wijzigingen in de apparaatdubbel
- levenscyclusgebeurtenissen van apparaten, zoals wanneer het apparaat wordt gemaakt of verwijderd
U kunt verrijkingen toevoegen aan berichten die naar het ingebouwde eindpunt van een IoT-hub gaan, of aan berichten die worden doorgestuurd naar aangepaste eindpunten, zoals Azure Blob Storage, een Service Bus-wachtrij of een Service Bus-onderwerp.
U kunt ook verrijkingen toevoegen aan berichten die worden gepubliceerd naar Event Grid door eerst een Event Grid-abonnement te maken met het berichttype apparaattelemetrie. Op basis van dit abonnement maken we een standaardroute in Azure IoT Hub voor de telemetrie. Deze ene route kan al uw Event Grid-abonnementen verwerken. Vervolgens kunt u verrijkingen voor het eindpunt configureren met behulp van het tabblad Berichten verrijken van de sectie IoT Hub Berichtroutering. Zie IoT Hub en Event Grid voor informatie over het reageren op gebeurtenissen met behulp van Event Grid.
Verrijkingen worden per eindpunt toegepast. Als u vijf verrijkingen opgeeft die moeten worden gestempeld voor een specifiek eindpunt, worden alle berichten die naar dat eindpunt gaan, voorzien van dezelfde vijf verrijkingen.
Verrijkingen kunnen worden geconfigureerd met behulp van de volgende methoden:
| Methode | Opdracht |
|---|---|
| Portal | Azure Portal Zie de zelfstudie voor berichtverrijkingen |
| Azure CLI | az iot hub message-enrichment |
| Azure PowerShell | Add-AzIotHubMessageEnrichment |
Het toevoegen van berichtverrijkingen voegt geen latentie toe aan de berichtroutering.
Als u berichtverrijkingen wilt uitproberen, raadpleegt u de zelfstudie over berichtverrijkingen
Beperkingen
U kunt maximaal 10 verrijkingen per IoT-hub toevoegen voor deze hubs in de standard- of Basic-laag. Voor IoT-hubs in de gratis laag kunt u maximaal 2 verrijkingen toevoegen.
In sommige gevallen, als u een bericht verrijkt met een waarde die is ingesteld op een tag of eigenschap in de apparaatdubbel, wordt de waarde voorzien van het opgegeven pad naar de apparaatdubbel. Als bijvoorbeeld een verrijkingswaarde is ingesteld op $twin.tags.field, krijgen de berichten een stempel met de tekenreeks '$twin.tags.field' in plaats van de waarde van dat veld uit de dubbel. Dit gedrag treedt op in de volgende gevallen:
Uw IoT-hub bevindt zich in de Basic-laag. IoT-hubs in de Basic-laag bieden geen ondersteuning voor apparaatdubbels.
Uw IoT-hub bevindt zich in de standard-laag, maar het apparaatdubbelpad dat wordt gebruikt voor de waarde van de verrijking bestaat niet. Als de verrijkingswaarde bijvoorbeeld is ingesteld op $twin.tags.location en de apparaatdubbel geen locatie-eigenschap onder tags heeft, wordt het bericht voorzien van een stempel met de tekenreeks '$twin.tags.location'.
Uw IoT-hub bevindt zich in de standard-laag, maar het apparaatdubbelpad dat wordt gebruikt voor de waarde van de verrijking, wordt omgezet in een object in plaats van een eenvoudige eigenschap. Als de verrijkingswaarde bijvoorbeeld is ingesteld op $twin.tags.location en de eigenschap location onder tags een object is dat onderliggende eigenschappen bevat, zoals
{"building": 43, "room": 503}, wordt het bericht voorzien van een stempel '$twin.tags.location'.
het kan tot vijf minuten duren voordat Updates op een apparaatdubbel wordt weergegeven in de bijbehorende verrijkingswaarde.
De totale berichtgrootte, inclusief de verrijkingen, mag niet groter zijn dan 256 kB. Als een bericht groter is dan 256 kB, wordt het bericht verwijderd door de IoT-hub. U kunt IoT Hub metrische gegevens gebruiken om fouten te identificeren en op te sporen wanneer berichten worden verwijderd. U kunt bijvoorbeeld de metrische gegevens voor incompatibele telemetrieberichten (d2c.telemetry.egress.invalid) bewaken in de metrische gegevens voor routering. Zie Azure IoT Hub controleren voor meer informatie.
Berichtverrijkingen zijn niet van toepassing op wijzigingsevenementen voor digitale dubbels.
Modules nemen geen dubbeltags over van de bijbehorende apparaten. Verrijkingen voor berichten die afkomstig zijn van apparaatmodules (bijvoorbeeld van IoT Edge-modules) moeten de dubbeltags gebruiken die zijn ingesteld op de moduledubbel.
Prijzen
Berichtverrijkingen zijn beschikbaar zonder extra kosten. Op dit moment worden er kosten in rekening gebracht wanneer u een bericht naar een IoT-hub verzendt. Er worden slechts eenmaal kosten in rekening gebracht voor dat bericht, zelfs als het bericht naar meerdere eindpunten gaat.
Volgende stappen
Bekijk deze artikelen voor meer informatie over het routeren van berichten naar een IoT-hub: