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
To support seamless interoperability across protocols, IoT Hub defines a common set of messaging features that are available in all device-facing protocols. These can be used in both [device-to-cloud message routing](iot-hub-devguide-messages-d2c.md) and [cloud-to-device messages](iot-hub-devguide-messages-c2d.md).
16
+
To support interoperability across protocols, IoT Hub defines a common set of messaging features that are available in all device-facing protocols. These features can be used in both [device-to-cloud messages](iot-hub-devguide-messages-d2c.md) and [cloud-to-device messages](iot-hub-devguide-messages-c2d.md).
IoT Hub implements device-to-cloud messaging using a streaming messaging pattern. IoT Hub's device-to-cloud messages are more like [Event Hubs](../event-hubs/index.yml)*events* than [Service Bus](../service-bus-messaging/index.yml)*messages* in that there is a high volume of events passing through the service that can be read by multiple readers.
20
+
IoT Hub implements device-to-cloud messaging using a streaming messaging pattern. IoT Hub's device-to-cloud messages are more like [Event Hubs](../event-hubs/index.yml)*events* than [Service Bus](../service-bus-messaging/index.yml)*messages* in that there's a high volume of events passing through the service that multiple readers can read.
20
21
21
22
An IoT Hub message consists of:
22
23
23
-
* A predetermined set of *system properties* as listed below.
24
+
* A predetermined set of *system properties* as described later in this article.
24
25
25
26
* A set of *application properties*. A dictionary of string properties that the application can define and access, without needing to deserialize the message body. IoT Hub never modifies these properties.
26
27
27
28
* A message body, which can be any type of data.
28
29
29
-
Each device protocol implements setting properties in different ways. Please see the related [MQTT](../iot/iot-mqtt-connect-to-iot-hub.md) and [AMQP](./iot-hub-amqp-support.md) developer guides for details.
30
+
Each device protocol implements setting properties in different ways. For more information, see the [MQTT protocol guide](../iot/iot-mqtt-connect-to-iot-hub.md) and [AMQP protocol guide](./iot-hub-amqp-support.md) developer guides for details.
30
31
31
-
Property names and values can only contain ASCII alphanumeric characters, plus ``{'!', '#', '$', '%, '&', ''', '*', '+', '-', '.', '^', '_', '`', '|', '~'}``when you send device-to-cloud messages using the HTTPS protocol or send cloud-to-device messages.
32
+
When you send device-to-cloud messages using the HTTPS protocol or send cloud-to-device messages, property names and values can only contain ASCII alphanumeric characters, plus ``! # $ % & ' * + - . ^ _ ` | ~`` .
32
33
33
34
Device-to-cloud messaging with IoT Hub has the following characteristics:
34
35
35
36
* Device-to-cloud messages are durable and retained in an IoT hub's default **messages/events** endpoint for up to seven days.
36
37
37
38
* Device-to-cloud messages can be at most 256 KB, and can be grouped in batches to optimize sends. Batches can be at most 256 KB.
38
39
39
-
* IoT Hub does not allow arbitrary partitioning. Device-to-cloud messages are partitioned based on their originating **deviceId**.
40
+
* IoT Hub doesn't allow arbitrary partitioning. Device-to-cloud messages are partitioned based on their originating **deviceId**.
40
41
41
42
* As explained in [Control access to IoT Hub](iot-hub-devguide-security.md), IoT Hub enables per-device authentication and access control.
42
43
43
-
* You can stamp messages with information that goes into the application properties. For more information, please see [message enrichments](iot-hub-message-enrichments-overview.md).
44
-
45
-
For more information about how to encode and decode messages sent using different protocols, see [Azure IoT SDKs](iot-hub-devguide-sdks.md).
44
+
* You can stamp messages with information that goes into the application properties. For more information, see [message enrichments](iot-hub-message-enrichments-overview.md).
46
45
47
46
> [!NOTE]
48
-
> Each IoT Hub protocol provides a message content type property which is respected when routing data to custom endpoints. To have your data properly handled at the destination (for example, JSON being treated as a parsable string instead of Base64 encoded binary data), you must provide the appropriate content type and charset for the message.
49
-
>
47
+
> Each IoT Hub protocol provides a message content type property which is respected when routing data to custom endpoints. To have your data properly handled at the destination (for example, JSON being treated as a parsable string instead of Base64 encoded binary data), provide the appropriate content type and charset for the message.
50
48
51
-
To use your message body in an IoT Hub routing query you must provide a valid JSON object for the message and set the content type property of the message to `application/json;charset=utf-8`.
49
+
To use your message body in an IoT Hub routing query, provide a valid JSON object for the message and set the content type property of the message to `application/json;charset=utf-8`.
52
50
53
-
A valid, routable message body may look like the following:
51
+
The following example shows a valid, routable message body:
54
52
55
53
```json
56
54
{
@@ -60,13 +58,13 @@ A valid, routable message body may look like the following:
60
58
}
61
59
```
62
60
63
-
## System Properties of **D2C** IoT Hub messages
61
+
## System properties of device-to-cloud messages
64
62
65
63
| Property | Description |User Settable?|Keyword for </br>routing query|
66
64
| --- | --- | --- | --- |
67
-
| message-id |A user-settable identifier for the message used for request-reply patterns. Format: A case-sensitive string (up to 128 characters long) of ASCII 7-bit alphanumeric characters + `{'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}`. | Yes | messageId |
65
+
| message-id |A user-settable identifier for the message used for request-reply patterns. Format: A case-sensitive string (up to 128 characters long) of ASCII 7-bit alphanumeric characters plus `- : . + % _ # * ? ! ( ) , = @ ; $ '`. | Yes | messageId |
68
66
| iothub-enqueuedtime |Date and time the [Device-to-Cloud](iot-hub-devguide-d2c-guidance.md) message was received by IoT Hub. | No | enqueuedTime |
69
-
| user-id |An ID used to specify the origin of messages. When messages are generated by IoT Hub, it is set to `{iot hub name}`. | Yes | userId |
67
+
| user-id |An ID used to specify the origin of messages. | Yes | userId |
70
68
| iothub-connection-device-id |An ID set by IoT Hub on device-to-cloud messages. It contains the **deviceId** of the device that sent the message. | No | connectionDeviceId |
71
69
| iothub-connection-module-id |An ID set by IoT Hub on device-to-cloud messages. It contains the **moduleId** of the device that sent the message. | No | connectionModuleId |
72
70
| iothub-connection-auth-generation-id |An ID set by IoT Hub on device-to-cloud messages. It contains the **connectionDeviceGenerationId** (as per [Device identity properties](iot-hub-devguide-identity-registry.md#device-identity-properties)) of the device that sent the message. | No |connectionDeviceGenerationId |
@@ -76,9 +74,9 @@ A valid, routable message body may look like the following:
76
74
| dt-dataschema | This value is set by IoT hub on device-to-cloud messages. It contains the device model ID set in the device connection. | No | $dt-dataschema |
77
75
| dt-subject | The name of the component that is sending the device-to-cloud messages. | Yes | $dt-subject |
78
76
79
-
## Application Properties of **D2C** IoT Hub messages
77
+
## Application properties of device-to-cloud messages
80
78
81
-
A common use of application properties is to send a timestamp from the device using the `iothub-creation-time-utc` property to record when the message was sent by the device. The format of this timestamp must be UTC with no timezone information. For example, `2021-04-21T11:30:16Z` is valid, `2021-04-21T11:30:16-07:00` is invalid:
79
+
A common use of application properties is to send a timestamp from the device using the `iothub-creation-time-utc` property to record when the message was sent by the device. The format of this timestamp must be UTC with no timezone information. For example, `2021-04-21T11:30:16Z` is valid, but `2021-04-21T11:30:16-07:00` is invalid.
82
80
83
81
```json
84
82
{
@@ -98,21 +96,21 @@ A common use of application properties is to send a timestamp from the device us
98
96
}
99
97
```
100
98
101
-
## System Properties of **C2D** IoT Hub messages
99
+
## System properties of cloud-to-device messages
102
100
103
101
| Property | Description |User Settable?|
104
102
| --- | --- | --- |
105
-
| message-id |A user-settable identifier for the message used for request-reply patterns. Format: A case-sensitive string (up to 128 characters long) of ASCII 7-bit alphanumeric characters + `{'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}`. |Yes|
103
+
| message-id |A user-settable identifier for the message used for request-reply patterns. Format: A case-sensitive string (up to 128 characters long) of ASCII 7-bit alphanumeric characters plus `- : . + % _ # * ? ! ( ) , = @ ; $ '`. |Yes|
106
104
| sequence-number |A number (unique per device-queue) assigned by IoT Hub to each cloud-to-device message. |No|
107
105
| to |A destination specified in [Cloud-to-Device](iot-hub-devguide-c2d-guidance.md) messages. |No|
108
106
| absolute-expiry-time |Date and time of message expiration. |Yes|
109
107
| correlation-id |A string property in a response message that typically contains the MessageId of the request, in request-reply patterns. |Yes|
110
-
| user-id |An ID used to specify the origin of messages. When messages are generated by IoT Hub, it is set to `{iot hub name}`. |Yes|
108
+
| user-id |An ID used to specify the origin of messages. When messages are generated by IoT Hub, the user ID is the IoT hub name. |Yes|
111
109
| iothub-ack |A feedback message generator. This property is used in cloud-to-device messages to request IoT Hub to generate feedback messages as a result of the consumption of the message by the device. Possible values: **none** (default): no feedback message is generated, **positive**: receive a feedback message if the message was completed, **negative**: receive a feedback message if the message expired (or maximum delivery count was reached) without being completed by the device, or **full**: both positive and negative. |Yes|
112
110
113
-
### System Property Names
111
+
### System property names
114
112
115
-
The system property names vary based on the endpoint to which the messages are being routed. Please see the table below for details on these names.
113
+
The system property names vary based on the endpoint to which the messages are being routed.
Copy file name to clipboardExpand all lines: articles/iot-hub/iot-hub-non-telemetry-event-schema.md
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,7 +11,7 @@ services: iot-hub
11
11
12
12
# Azure IoT Hub non-telemetry event schemas
13
13
14
-
This article provides the properties and schemas for non-telemetry events emitted by Azure IoT Hub. Non-telemetry events are different from device-to-cloud and cloud-to-device messages in that they are emitted directly by IoT Hub in response to specific kinds of state changes associated with your devices. For example, lifecycle changes like a device or module being created or deleted, or connection state changes like a device or module connecting or disconnecting.
14
+
This article provides the properties and schemas for non-telemetry events emitted by Azure IoT Hub. Non-telemetry events are different from device-to-cloud and cloud-to-device messages in that IoT Hub emits these events in response to specific state changes associated with your devices. For example, lifecycle changes like a device or module being created or deleted, or connection state changes like a device or module connecting or disconnecting.
15
15
16
16
You can route non-telemetry events using message routing, or reach to non-telemetry events using Azure Event Grid. To learn more about IoT Hub message routing, see [IoT Hub message routing](iot-hub-devguide-messages-d2c.md) and [React to IoT Hub events by using Event Grid](./iot-hub-event-grid.md).
17
17
@@ -34,7 +34,7 @@ Non-telemetry events share several common properties.
34
34
35
35
### System properties
36
36
37
-
The following system properties are set by IoT Hub on each event.
37
+
IoT Hub sets the following system properties on each event.
38
38
39
39
| Property | Type |Description | Keyword for routing query |
**Body**: The body contains a sequence number. The sequence number is a string representation of a hexadecimal number. You can use string compare to identify the larger number. If you're converting the string to hex, then the number will be a 256-bit number. The sequence number is strictly increasing, and the latest event will have a higher number than other events. This is useful if you have frequent device connects and disconnects, and want to ensure only the latest event is used to trigger a downstream action.
82
+
**Body**: The body contains a sequence number. The sequence number is a string representation of a hexadecimal number. You can use string compare to identify the larger number. If you're converting the string to hex, then the number will be a 256-bit number. The sequence number is strictly increasing, so the latest event has a higher number than older events. This is useful if you have frequent device connects and disconnects, and want to ensure that only the latest event is used to trigger a downstream action.
83
83
84
84
### Example
85
85
@@ -139,7 +139,7 @@ Device lifecycle events are emitted whenever a device or module is created or de
139
139
| ---- | ----------- |
140
140
| iothub-message-source | deviceLifecycleEvents |
141
141
142
-
**Body**: The body contains a representation of the device twin or module twin. It includes the device ID and module ID, the twin etag, the version property, and the tags, properties and associated metadata of the twin.
142
+
**Body**: The body contains a representation of the device twin or module twin. It includes the device ID and module ID, the twin etag, the version property, and the tags, properties, and associated metadata of the twin.
143
143
144
144
### Example
145
145
@@ -218,7 +218,7 @@ Device twin change events are emitted whenever a device twin or a module twin is
218
218
| ---- | ----------- |
219
219
| iothub-message-source | twinChangeEvents |
220
220
221
-
**Body**: On an update, the body contains the version property of the twin and the updated tags and properties and their associated metadata. On a replace, the body contains the device ID and module ID, the twin etag, the version property, and all the tags, properties and associated metadata of the device or module twin.
221
+
**Body**: On an update, the body contains the version property of the twin and the updated tags and properties and their associated metadata. On a replace, the body contains the device ID and module ID, the twin etag, the version property, and all the tags, properties, and associated metadata of the device or module twin.
0 commit comments