Skip to content

Commit a0a7591

Browse files
Stacyrch140Stacyrch140
authored
Merge pull request #199757 from JimacoMS4/document-non-telemetry-events-hub
Add schemas for non-telemetry events
2 parents 03abda6 + 782c584 commit a0a7591

6 files changed

+293
-159
lines changed

‎articles/iot-hub/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,8 @@
9595
href: iot-hub-devguide-messaging.md
9696
- name: Create and read IoT Hub messages
9797
href: iot-hub-devguide-messages-construct.md
98+
- name: Non-telemetry event schemas
99+
href: iot-hub-non-telemetry-event-schema.md
98100
- name: Send cloud-to-device messages from IoT Hub
99101
href: iot-hub-devguide-messages-c2d.md
100102
- name: Choose a device communication protocol

‎articles/iot-hub/iot-hub-devguide-device-twins.md

Lines changed: 1 addition & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -177,46 +177,7 @@ The solution back end operates on the device twin using the following atomic ope
177177

178178
* **Replace tags**. This operation enables the solution back end to completely overwrite all existing tags and substitute a new JSON document for `tags`.
179179

180-
* **Receive twin notifications**. This operation allows the solution back end to be notified when the twin is modified. To do so, your IoT solution needs to create a route and to set the Data Source equal to *twinChangeEvents*. By default, no such routes pre-exist, so no twin notifications are sent. If the rate of change is too high, or for other reasons such as internal failures, the IoT Hub might send only one notification that contains all changes. Therefore, if your application needs reliable auditing and logging of all intermediate states, you should use device-to-cloud messages. The twin notification message includes properties and body.
181-
182-
- Properties
183-
184-
| Name | Value |
185-
| --- | --- |
186-
$content-type | application/json |
187-
$iothub-enqueuedtime | Time when the notification was sent |
188-
$iothub-message-source | twinChangeEvents |
189-
$content-encoding | utf-8 |
190-
deviceId | ID of the device |
191-
hubName | Name of IoT Hub |
192-
operationTimestamp | [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp of operation |
193-
iothub-message-schema | twinChangeNotification |
194-
opType | "replaceTwin" or "updateTwin" |
195-
196-
Message system properties are prefixed with the `$` symbol.
197-
198-
- Body
199-
200-
This section includes all the twin changes in a JSON format. It uses the same format as a patch, with the difference that it can contain all twin sections: tags, properties.reported, properties.desired, and that it contains the "$metadata" elements. For example,
201-
202-
```json
203-
{
204-
"properties": {
205-
"desired": {
206-
"$metadata": {
207-
"$lastUpdated": "2016-02-30T16:24:48.789Z"
208-
},
209-
"$version": 1
210-
},
211-
"reported": {
212-
"$metadata": {
213-
"$lastUpdated": "2016-02-30T16:24:48.789Z"
214-
},
215-
"$version": 1
216-
}
217-
}
218-
}
219-
```
180+
* **Receive twin notifications**. This operation allows the solution back end to be notified when the twin is modified. To do so, your IoT solution needs to create a route and to set the Data Source equal to *twinChangeEvents*. By default, no such route exists, so no twin notifications are sent. If the rate of change is too high, or for other reasons such as internal failures, the IoT Hub might send only one notification that contains all changes. Therefore, if your application needs reliable auditing and logging of all intermediate states, you should use device-to-cloud messages. To learn more about the properties and body returned in the twin notification message, see [Non-telemetry event schemas](iot-hub-non-telemetry-event-schema.md).
220181

221182
All the preceding operations support [Optimistic concurrency](iot-hub-devguide-device-twins.md#optimistic-concurrency) and require the **ServiceConnect** permission, as defined in [Control access to IoT Hub](iot-hub-dev-guide-sas.md).
222183

‎articles/iot-hub/iot-hub-devguide-identity-registry.md

Lines changed: 1 addition & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -90,83 +90,7 @@ A more complex implementation could include the information from [Azure Monitor]
9090
9191
## Device and module lifecycle notifications
9292

93-
IoT Hub can notify your IoT solution when a device identity is created or deleted by sending lifecycle notifications. To do so, your IoT solution needs to create a route and to set the Data Source equal to *DeviceLifecycleEvents*. By default, no lifecycle notifications are sent, that is, no such routes pre-exist. By creating a route with Data Source equal to *DeviceLifecycleEvents*, lifecycle events will be sent for both device identities and module identities; however, the message contents will differ depending on whether the events are generated for module identities or device identities. It should be noted that for IoT Edge modules, the module identity creation flow is different than for other modules, as a result for IoT Edge modules the create notification is only sent if the corresponding IoT Edge Device for the updated IoT Edge module identity is running. For all other modules, lifecycle notifications are sent whenever the module identity is updated on the IoT Hub side. The notification message includes properties, and body.
94-
95-
Properties: Message system properties are prefixed with the `$` symbol.
96-
97-
Notification message for device:
98-
99-
| Name | Value |
100-
| --- | --- |
101-
|$content-type | application/json |
102-
|$iothub-enqueuedtime | Time when the notification was sent |
103-
|$iothub-message-source | deviceLifecycleEvents |
104-
|$content-encoding | utf-8 |
105-
|opType | **createDeviceIdentity** or **deleteDeviceIdentity** |
106-
|hubName | Name of IoT Hub |
107-
|deviceId | ID of the device |
108-
|operationTimestamp | ISO8601 timestamp of operation |
109-
|iothub-message-schema | deviceLifecycleNotification |
110-
111-
Body: This section is in JSON format and represents the twin of the created device identity. For example,
112-
113-
```json
114-
{
115-
"deviceId":"11576-ailn-test-0-67333793211",
116-
"etag":"AAAAAAAAAAE=",
117-
"properties": {
118-
"desired": {
119-
"$metadata": {
120-
"$lastUpdated": "2016-02-30T16:24:48.789Z"
121-
},
122-
"$version": 1
123-
},
124-
"reported": {
125-
"$metadata": {
126-
"$lastUpdated": "2016-02-30T16:24:48.789Z"
127-
},
128-
"$version": 1
129-
}
130-
}
131-
}
132-
```
133-
Notification message for module:
134-
135-
| Name | Value |
136-
| --- | --- |
137-
$content-type | application/json |
138-
$iothub-enqueuedtime | Time when the notification was sent |
139-
$iothub-message-source | moduleLifecycleEvents |
140-
$content-encoding | utf-8 |
141-
opType | **createModuleIdentity** or **deleteModuleIdentity** |
142-
hubName | Name of IoT Hub |
143-
moduleId | ID of the module |
144-
operationTimestamp | ISO8601 timestamp of operation |
145-
iothub-message-schema | moduleLifecycleNotification |
146-
147-
Body: This section is in JSON format and represents the twin of the created module identity. For example,
148-
149-
```json
150-
{
151-
"deviceId":"11576-ailn-test-0-67333793211",
152-
"moduleId":"tempSensor",
153-
"etag":"AAAAAAAAAAE=",
154-
"properties": {
155-
"desired": {
156-
"$metadata": {
157-
"$lastUpdated": "2016-02-30T16:24:48.789Z"
158-
},
159-
"$version": 1
160-
},
161-
"reported": {
162-
"$metadata": {
163-
"$lastUpdated": "2016-02-30T16:24:48.789Z"
164-
},
165-
"$version": 1
166-
}
167-
}
168-
}
169-
```
93+
IoT Hub can notify your IoT solution when a device identity is created or deleted by sending lifecycle notifications. To do so, your IoT solution needs to create a route and to set the Data Source equal to *DeviceLifecycleEvents*. By default, no lifecycle notifications are sent, that is, no such routes pre-exist. By creating a route with Data Source equal to *DeviceLifecycleEvents*, lifecycle events will be sent for both device identities and module identities; however, the message contents will differ depending on whether the events are generated for module identities or device identities. It should be noted that for IoT Edge modules, the module identity creation flow is different than for other modules, as a result for IoT Edge modules the create notification is only sent if the corresponding IoT Edge Device for the updated IoT Edge module identity is running. For all other modules, lifecycle notifications are sent whenever the module identity is updated on the IoT Hub side. To learn more about the properties and body returned in the notification message, see [Non-telemetry event schemas](iot-hub-non-telemetry-event-schema.md).
17094

17195
## Device identity properties
17296

‎articles/iot-hub/iot-hub-devguide-messages-construct.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -163,4 +163,6 @@ The **iothub-connection-auth-method** property contains a JSON serialized object
163163

164164
* For information about message size limits in IoT Hub, see [IoT Hub quotas and throttling](iot-hub-devguide-quotas-throttling.md).
165165

166-
* To learn how to create and read IoT Hub messages in various programming languages, see the [Quickstarts](../iot-develop/quickstart-send-telemetry-iot-hub.md?pivots=programming-language-nodejs).
166+
* To learn how to create and read IoT Hub messages in various programming languages, see the [Quickstarts](../iot-develop/quickstart-send-telemetry-iot-hub.md?pivots=programming-language-nodejs).
167+
168+
* To learn about the structure of non-telemetry events generated by IoT Hub, see [IoT Hub non-telemetry event schemas](iot-hub-non-telemetry-event-schema.md).

‎articles/iot-hub/iot-hub-devguide-module-twins.md

Lines changed: 1 addition & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -169,47 +169,7 @@ The solution back end operates on the module twin using the following atomic ope
169169

170170
* **Replace tags**. This operation enables the solution back end to completely overwrite all existing tags and substitute a new JSON document for `tags`.
171171

172-
* **Receive twin notifications**. This operation allows the solution back end to be notified when the twin is modified. To do so, your IoT solution needs to create a route and to set the Data Source equal to *twinChangeEvents*. By default, no twin notifications are sent, that is, no such routes pre-exist. If the rate of change is too high, or for other reasons such as internal failures, the IoT Hub might send only one notification that contains all changes. Therefore, if your application needs reliable auditing and logging of all intermediate states, you should use device-to-cloud messages. The twin notification message includes properties and body.
173-
174-
- Properties
175-
176-
| Name | Value |
177-
| --- | --- |
178-
$content-type | application/json |
179-
$iothub-enqueuedtime | Time when the notification was sent |
180-
$iothub-message-source | twinChangeEvents |
181-
$content-encoding | utf-8 |
182-
deviceId | ID of the device |
183-
moduleId | ID of the module |
184-
hubName | Name of IoT Hub |
185-
operationTimestamp | [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp of operation |
186-
iothub-message-schema | twinChangeNotification |
187-
opType | "replaceTwin" or "updateTwin" |
188-
189-
Message system properties are prefixed with the `$` symbol.
190-
191-
- Body
192-
193-
This section includes all the twin changes in a JSON format. It uses the same format as a patch, with the difference that it can contain all twin sections: tags, properties.reported, properties.desired, and that it contains the “$metadata” elements. For example,
194-
195-
```json
196-
{
197-
"properties": {
198-
"desired": {
199-
"$metadata": {
200-
"$lastUpdated": "2016-02-30T16:24:48.789Z"
201-
},
202-
"$version": 1
203-
},
204-
"reported": {
205-
"$metadata": {
206-
"$lastUpdated": "2016-02-30T16:24:48.789Z"
207-
},
208-
"$version": 1
209-
}
210-
}
211-
}
212-
```
172+
* **Receive twin notifications**. This operation allows the solution back end to be notified when the twin is modified. To do so, your IoT solution needs to create a route and to set the Data Source equal to *twinChangeEvents*. By default, no such route exists, so no twin notifications are sent. If the rate of change is too high, or for other reasons such as internal failures, the IoT Hub might send only one notification that contains all changes. Therefore, if your application needs reliable auditing and logging of all intermediate states, you should use device-to-cloud messages. To learn more about the properties and body returned in the twin notification message, see [Non-telemetry event schemas](iot-hub-non-telemetry-event-schema.md).
213173

214174
All the preceding operations support [Optimistic concurrency](iot-hub-devguide-device-twins.md#optimistic-concurrency) and require the **ServiceConnect** permission, as defined in the [Control Access to IoT Hub](iot-hub-devguide-security.md) article.
215175

0 commit comments

Comments
 (0)