You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/iot-hub/iot-hub-message-enrichments-overview.md
+13-13Lines changed: 13 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,11 +8,11 @@ services: iot-hub
8
8
ms.topic: conceptual
9
9
ms.date: 03/16/2022
10
10
ms.author: kgremban
11
-
#Customer intent: As a developer, I want to be able to add information to messages sent from a device to my IoT Hub, based on the destination endpoint.
11
+
#Customer intent: As a developer, I want to be able to add information to messages sent from a device to my IoT hub, based on the destination endpoint.
12
12
---
13
13
# Message enrichments for device-to-cloud IoT Hub messages
14
14
15
-
*Message enrichments* is the ability of the IoT Hub to *stamp* messages with additional information before the messages are sent to the designated endpoint. One reason to use message enrichments is to include data that can be used to simplify downstream processing. For example, enriching device telemetry messages with a device twin tag can reduce load on customers to make device twin API calls for this information.
15
+
*Message enrichments* is the ability of an IoT hub to *stamp* messages with additional information before the messages are sent to the designated endpoint. One reason to use message enrichments is to include data that can be used to simplify downstream processing. For example, enriching device telemetry messages with a device twin tag can reduce load on customers to make device twin API calls for this information.
@@ -47,13 +47,13 @@ The messages can come from any data source supported by [IoT Hub message routing
47
47
* device twin change notifications -- changes in the device twin
48
48
* device life-cycle events, such as when the device is created or deleted
49
49
50
-
You can add enrichments to messages that are going to the built-in endpoint of an IoT Hub, or messages that are being routed to custom endpoints such as Azure Blob storage, a Service Bus queue, or a Service Bus topic.
50
+
You can add enrichments to messages that are going to the built-in endpoint of an IoT hub, or to messages that are being routed to custom endpoints such as Azure Blob storage, a Service Bus queue, or a Service Bus topic.
51
51
52
52
You can also add enrichments to messages that are being published to Event Grid by first creating an event grid subscription with the device telemetry message type. Based on this subscription, we will create a default route in Azure IoT Hub for the telemetry. This single route can handle all of your Event Grid subscriptions. You can then configure enrichments for the endpoint by using the **Enrich messages** tab of the IoT Hub **Message routing** section. For information about reacting to events by using Event Grid, see [Iot Hub and Event Grid](iot-hub-event-grid.md).
53
53
54
54
Enrichments are applied per endpoint. If you specify five enrichments to be stamped for a specific endpoint, all messages going to that endpoint are stamped with the same five enrichments.
55
55
56
-
Enrichments can be configured using the the following methods:
56
+
Enrichments can be configured using the following methods:
57
57
58
58
|**Method**|**Command**|
59
59
| ----- | -----|
@@ -67,33 +67,33 @@ To try out message enrichments, see the [message enrichments tutorial](tutorial-
67
67
68
68
## Limitations
69
69
70
-
* You can add up to 10 enrichments per IoT Hub for those hubs in the standard or basic tier. For IoT Hubs in the free tier, you can add up to 2 enrichments.
70
+
* You can add up to 10 enrichments per IoT hub for those hubs in the standard or basic tier. For IoT hubs in the free tier, you can add up to 2 enrichments.
71
71
72
-
* In some cases, if you're applying an enrichment with a value set to a tag or property in the device twin, the value will be stamped with the specified device twin path. For example, if an enrichment value is set to $twin.tags.field, the messages will be stamped with the string "$twin.tags.field", rather than the value of that field from the twin. This happens in the following cases:
72
+
* In some cases, if you're applying an enrichment with a value set to a tag or property in the device twin, the value will be stamped with the specified device twin path. For example, if an enrichment value is set to $twin.tags.field, the messages will be stamped with the string "$twin.tags.field", rather than the value of that field from the twin. This behavior happens in the following cases:
73
73
74
-
* Your IoT Hub is in the basic tier. Basic tier IoT hubs do not support device twins.
74
+
* Your IoT hub is in the basic tier. Basic tier IoT hubs do not support device twins.
75
75
76
-
* Your IoT Hub is in the standard tier, but the device sending the message has no device twin.
76
+
* Your IoT hub is in the standard tier, but the device sending the message has no device twin.
77
77
78
-
* Your IoT Hub is in the standard tier, but the device twin path used for the value of the enrichment does not exist. For example, if the enrichment value is set to $twin.tags.location, and the device twin does not have a location property under tags, the message is stamped with the string "$twin.tags.location".
78
+
* Your IoT hub is in the standard tier, but the device twin path used for the value of the enrichment does not exist. For example, if the enrichment value is set to $twin.tags.location, and the device twin does not have a location property under tags, the message is stamped with the string "$twin.tags.location".
79
79
80
-
* Your IoT Hub is in the standard tier, but the device twin path used for the value of the enrichment resolves to an object, rather than a simple property. For example, if the enrichment value is set to $twin.tags.location, and the location property under tags is an object that contains child properties like `{"building": 43, "room": 503}`, the message is stamped with the string "$twin.tags.location".
80
+
* Your IoT hub is in the standard tier, but the device twin path used for the value of the enrichment resolves to an object, rather than a simple property. For example, if the enrichment value is set to $twin.tags.location, and the location property under tags is an object that contains child properties like `{"building": 43, "room": 503}`, the message is stamped with the string "$twin.tags.location".
81
81
82
82
* Updates to a device twin can take up to five minutes to be reflected in the corresponding enrichment value.
83
83
84
-
* The total message size, including the enrichments, can't exceed 256 KB. If a message size exceeds 256 KB, the IoT Hub will drop the message. You can use [IoT Hub metrics](monitor-iot-hub-reference.md#metrics) to identify and debug errors when messages are dropped. For example, you can monitor the *telemetry messages incompatible* (*d2c.telemetry.egress.invalid*) metric in the [routing metrics](monitor-iot-hub-reference.md#routing-metrics). To learn more, see [Monitor IoT Hub](monitor-iot-hub.md).
84
+
* The total message size, including the enrichments, can't exceed 256 KB. If a message size exceeds 256 KB, the IoT hub will drop the message. You can use [IoT Hub metrics](monitor-iot-hub-reference.md#metrics) to identify and debug errors when messages are dropped. For example, you can monitor the *telemetry messages incompatible* (*d2c.telemetry.egress.invalid*) metric in the [routing metrics](monitor-iot-hub-reference.md#routing-metrics). To learn more, see [Monitor IoT Hub](monitor-iot-hub.md).
85
85
86
86
* Message enrichments don't apply to digital twin change events.
87
87
88
88
* Modules do not inherit twin tags from their corresponding devices. Enrichments for messages originating from device modules (for example from IoT Edge modules) must use the twin tags that are set on the module twin.
89
89
90
90
## Pricing
91
91
92
-
Message enrichments are available for no additional charge. Currently, you are charged when you send a message to an IoT Hub. You are only charged once for that message, even if the message goes to multiple endpoints.
92
+
Message enrichments are available for no additional charge. Currently, you are charged when you send a message to an IoT hub. You are only charged once for that message, even if the message goes to multiple endpoints.
93
93
94
94
## Next steps
95
95
96
-
Check out these articles for more information about routing messages to an IoT Hub:
96
+
Check out these articles for more information about routing messages to an IoT hub:
Copy file name to clipboardExpand all lines: articles/iot-hub/tutorial-message-enrichments.md
+7-5Lines changed: 7 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -321,16 +321,18 @@ One of the message enrichments configured on your IoT hub specifies a key of Dev
321
321
322
322
Follow these steps to add a location tag to your device's twin with the portal.
323
323
324
-
1. Go to your IoT hub by selecting **Resource groups**. Then select the resource group set up for this tutorial (**ContosoResourcesMsgEn**). Find the IoT hub in the list, and select it. Select **Devices** on the left-pane of your IoT hub, then select your device (**Contoso-Test-Device**).
324
+
1. Go to your IoT hub by selecting **Resource groups**. Then select the resource group set up for this tutorial (**ContosoResourcesMsgEn**). Find the IoT hub in the list, and select it. Select **Devices** on the left-pane of the IoT hub, then select your device (**Contoso-Test-Device**).
325
325
326
326
1. Select the **Device twin** tab at the top of the device page and add the following line just before the closing brace at the bottom of the device twin. Then select **Save**.
327
327
328
-
```json
329
-
, "tags": {"location": "Plant 43"}
328
+
```json
329
+
, "tags": {"location": "Plant 43"}
330
330
331
-
```
331
+
```
332
332
333
-
:::image type="content" source="./media/tutorial-message-enrichments/add-location-tag-to-device-twin.png" alt-text="Screenshot of adding location tag to device twin in Azure portal":::
333
+
:::image type="content" source="./media/tutorial-message-enrichments/add-location-tag-to-device-twin.png" alt-text="Screenshot of adding location tag to device twin in Azure portal":::
334
+
335
+
1. Wait about five minutes before continuing to the next section. It can take that long for updates to the device twin to be reflected in the message enrichment value.
334
336
335
337
To learn more about how device twin paths are handled with message enrichments, see [Message enrichments limitations](iot-hub-message-enrichments-overview.md#limitations). To learn more about device twins, see [Understand and use device twins in IoT Hub](iot-hub-devguide-device-twins.md).
0 commit comments