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
Message routing allows you to query on the message properties and message body as well as device twin tags and device twin properties. If the message body isn't in JSON format, message routing can still route the message, but queries can't be applied to the message body. Queries are described as Boolean expressions where, if true, the query succeeds and routes all the incoming data; otherwise, the query fails and the incoming data isn't routed. If the expression evaluates to a null or undefined value, it's treated as a Boolean false value, and generates an error in the IoT Hub [routes resource logs](monitor-iot-hub-reference.md#routes). The query syntax must be correct for the route to be saved and evaluated.
19
+
Message routing allows you to query on the message properties and message body as well as device twin tags and device twin properties. If the message body isn't in JSON format, message routing can still route the message, but queries can't be applied to the message body. Queries are described as Boolean expressions where, if true, the query succeeds and routes all the incoming data; otherwise, the query fails and the incoming data isn't routed. If the expression evaluates to a null or undefined value, it's treated as a Boolean false value, and generates an error in the IoT Hub [routes resource logs](monitor-iot-hub-reference.md#routes-category). The query syntax must be correct for the route to be saved and evaluated.
20
20
21
21
## Query based on message properties
22
22
23
-
IoT Hub defines a [common format](iot-hub-devguide-messages-construct.md) for all device-to-cloud messaging for interoperability across protocols. IoT Hub assumes the following JSON representation of the message. System properties are added for all users and identify content of the message. Users can selectively add application properties to the message. We recommend using unique property names because IoT Hub device-to-cloud messaging isn't case-sensitive. For example, if you have multiple properties with the same name, IoT Hub will only send one of the properties.
23
+
IoT Hub defines a [common format](iot-hub-devguide-messages-construct.md) for all device-to-cloud messaging for interoperability across protocols. IoT Hub assumes the following JSON representation of the message. System properties are added for all users and identify content of the message. Users can selectively add application properties to the message. We recommend using unique property names because IoT Hub device-to-cloud messaging isn't case-sensitive. For example, if you have multiple properties with the same name, IoT Hub only sends one of the properties.
24
24
25
25
```json
26
26
{
@@ -64,7 +64,7 @@ Application properties are user-defined strings that can be added to the message
64
64
65
65
### Message properties query expressions
66
66
67
-
A query on message system properties must be prefixed with the `$` symbol. Queries on application properties are accessed with their name and shouldn't be prefixed with the `$`symbol. If an application property name begins with `$`, then IoT Hub first searches for it in the system properties, and if it's not found will then search for it in the application properties. The following examples show how to query on system properties and application properties.
67
+
A query on message system properties must be prefixed with the `$` symbol. Queries on application properties are accessed with their name and shouldn't be prefixed with the `$`symbol. If an application property name begins with `$`, then IoT Hub first searches for it in the system properties, and if it's not found then searches for it in the application properties. The following examples show how to query on system properties and application properties.
68
68
69
69
To query on the system property contentEncoding:
70
70
@@ -88,7 +88,7 @@ A full list of supported operators and functions is provided in the [expression
88
88
89
89
## Query based on message body
90
90
91
-
To enable querying on a message body, the message should be in a JSON format and encoded in either UTF-8, UTF-16 or UTF-32. The `contentType` system property must be `application/JSON`. The `contentEncoding` system property must be one of the UTF encoding values supported by that system property. If these system properties aren't specified, IoT Hub won't evaluate the query expression on the message body.
91
+
To enable querying on a message body, the message should be in a JSON format and encoded in either UTF-8, UTF-16 or UTF-32. The `contentType` system property must be `application/JSON`. The `contentEncoding` system property must be one of the UTF encoding values supported by that system property. If these system properties aren't specified, IoT Hub doesn't evaluate the query expression on the message body.
92
92
93
93
The following JavaScript example shows how to create a message with a properly formed and encoded JSON body:
Azure IoT Hub *device streams* facilitate the creation of secure bi-directional TCP tunnels for a variety of cloud-to-device communication scenarios. A device stream is mediated by an IoT Hub *streaming endpoint* which acts as a proxy between your device and service endpoints. This setup, depicted in the diagram below, is especially useful when devices are behind a network firewall or reside inside of a private network. As such, IoT Hub device streams help address customers' need to reach IoT devices in a firewall-friendly manner and without the need to broadly opening up incoming or outgoing network firewall ports.
15
+
Azure IoT Hub *device streams* facilitate the creation of secure bi-directional TCP tunnels for various cloud-to-device communication scenarios. A device stream is mediated by an IoT Hub *streaming endpoint, which acts as a proxy between your device and service endpoints. This setup, depicted in the diagram, is especially useful when devices are behind a network firewall or reside inside of a private network. As such, IoT Hub device streams help address customers' need to reach IoT devices in a firewall-friendly manner and without the need to broadly opening up incoming or outgoing network firewall ports.
Using IoT Hub device streams, devices remain secure and will only need to open up outbound TCP connections to IoT hub's streaming endpoint over port 443. Once a stream is established, the service-side and device-side applications will each have programmatic access to a WebSocket client object to send and receive raw bytes to one another. The reliability and ordering guarantees provided by this tunnel is on par with TCP.
19
+
Using IoT Hub device streams, devices remain secure and will only need to open up outbound TCP connections to IoT hub's streaming endpoint over port 443. Once a stream is established, the service-side and device-side applications each have programmatic access to a WebSocket client object to send and receive raw bytes to one another. The reliability and ordering guarantees provided by this tunnel is on par with TCP.
20
20
21
21
## Benefits
22
22
@@ -26,13 +26,13 @@ IoT Hub device streams provide the following benefits:
26
26
27
27
***Authentication:** Both device and service sides of the tunnel need to authenticate with IoT Hub using their corresponding credentials.
28
28
29
-
***Encryption:** By default, IoT Hub device streams use TLS-enabled connections. This ensures that the traffic is always encrypted regardless of whether the application uses encryption or not.
29
+
***Encryption:** By default, IoT Hub device streams use TLS-enabled connections. This factor ensures that the traffic is always encrypted regardless of whether the application uses encryption or not.
30
30
31
31
***Simplicity of connectivity:** In many cases, the use of device streams eliminates the need for complex setup of Virtual Private Networks to enable connectivity to IoT devices.
32
32
33
-
***Compatibility with TCP/IP stack:** IoT Hub device streams can accommodate TCP/IP application traffic. This means that a wide range of proprietary as well as standards-based protocols can leverage this feature.
33
+
***Compatibility with TCP/IP stack:** IoT Hub device streams can accommodate TCP/IP application traffic. This approach means that a wide range of proprietary and standards-based protocols can use this feature.
34
34
35
-
***Ease of use in private network setups:** Service can communicate with a device by referencing its device ID, rather than device's IP address. This is useful in situations where a device is located inside a private network and has a private IP address, or its IP address is assigned dynamically and is unknown to the service side.
35
+
***Ease of use in private network setups:** Service can communicate with a device by referencing its device ID, rather than device's IP address. This fact is useful in situations where a device is located inside a private network and has a private IP address, or its IP address is assigned dynamically and is unknown to the service side.
36
36
37
37
## Device stream workflows
38
38
@@ -42,17 +42,17 @@ The device stream creation process involves a negotiation between the device, se
42
42
43
43
### Device stream creation flow
44
44
45
-
Programmatic creation of a device stream using the SDK involves the following steps, which are also depicted in the figure below:
45
+
Programmatic creation of a device stream using the SDK involves the following steps, which are also depicted in the figure:
1. The device application registers a callback in advance to be notified of when a new device stream is initiated to the device. This step typically takes place when the device boots up and connects to IoT Hub.
50
50
51
51
2. The service-side program initiates a device stream when needed by providing the device ID (_not_ the IP address).
52
52
53
-
3. IoT hub notifies the device-side program by invoking the callback registered in step 1. The device may accept or reject the stream initiation request. This logic can be specific to your application scenario. If the stream request is rejected by the device, IoT Hub informs the service accordingly; otherwise, the steps below follow.
53
+
3. IoT hub notifies the device-side program by invoking the callback registered in step 1. The device might accept or reject the stream initiation request. This logic can be specific to your application scenario. If the device rejects the stream request, IoT Hub informs the service accordingly; otherwise, the following steps take place.
54
54
55
-
4. The device creates a secure outbound TCP connection to the streaming endpoint over port 443 and upgrades the connection to a WebSocket. The URL of the streaming endpoint as well as the credentials to use to authenticate are both provided to the device by IoT Hub as part of the request sent in step 3.
55
+
4. The device creates a secure outbound TCP connection to the streaming endpoint over port 443 and upgrades the connection to a WebSocket. The URL of the streaming endpoint and the credentials to use to authenticate are both provided to the device by IoT Hub as part of the request sent in step 3.
56
56
57
57
5. The service is notified of the result of device accepting the stream and proceeds to create its own WebSocket client to the streaming endpoint. Similarly, it receives the streaming endpoint URL and authentication information from IoT Hub.
58
58
@@ -62,19 +62,19 @@ In the handshake process above:
62
62
63
63
* After the stream creation flow above completes, the streaming endpoint will act as a proxy and will transfer traffic between the service and the device over their respective WebSockets.
64
64
65
-
* Device and service both need outbound connectivity to IoT Hub's main endpoint as well as the streaming endpoint over port 443. The URL of these endpoints is available on *Overview* tab on the IoT Hub's portal.
65
+
* Device and service both need outbound connectivity to IoT Hub's main endpoint and the streaming endpoint over port 443. The URL of these endpoints is available on *Overview* tab on the IoT Hub's portal.
66
66
67
67
* The reliability and ordering guarantees of an established stream is on par with TCP.
68
68
69
69
* All connections to IoT Hub and streaming endpoint use TLS and are encrypted.
70
70
71
71
### Termination flow
72
72
73
-
An established stream terminates when either of the TCP connections to the gateway are disconnected (by the service or device). This can take place voluntarily by closing the WebSocket on either the device or service programs, or involuntarily in case of a network connectivity timeout or process failure. Upon termination of either device or service's connection to the streaming endpoint, the other TCP connection will also be (forcefully) terminated and the service and device are responsible to re-create the stream, if needed.
73
+
An established stream terminates when either of the TCP connections to the gateway are disconnected (by the service or device). This action can take place voluntarily by closing the WebSocket on either the device or service programs, or involuntarily if a network connectivity timeout or process failure. Upon termination of either device or service's connection to the streaming endpoint, the other TCP connection is also (forcefully) terminated and the service and device are responsible to re-create the stream, if needed.
74
74
75
75
## Connectivity requirements
76
76
77
-
Both the device and the service sides of a device stream must be capable of establishing TLS-enabled connections to IoT Hub and its streaming endpoint. This requires outbound connectivity over port 443 to these endpoints. The hostname associated with these endpoints can be found on the *Overview* tab of IoT Hub, as shown in the figure below:
77
+
Both the device and the service sides of a device stream must be capable of establishing TLS-enabled connections to IoT Hub and its streaming endpoint. This situation requires outbound connectivity over port 443 to these endpoints. The hostname associated with these endpoints can be found on the *Overview* tab of IoT Hub, as shown in the figure:
@@ -84,7 +84,7 @@ Alternatively, the endpoints information can be retrieved using Azure CLI under
84
84
az iot hub devicestream show --name <YourIoTHubName>
85
85
```
86
86
87
-
The output is a JSON object of all endpoints that your hub's device and service may need to connect to in order to establish a device stream.
87
+
The output is a JSON object of all endpoints that your hub's device and service might need to connect to in order to establish a device stream.
88
88
89
89
```json
90
90
{
@@ -117,27 +117,27 @@ az iot hub devicestream show --name <YourIoTHubName>
117
117
118
118
## Troubleshoot via Device Streams resource logs
119
119
120
-
You can set up Azure Monitor to collect the [resource logs for device streams](monitor-iot-hub-reference.md#device-streams-preview) emitted by your IoT Hub. This can be very helpful in troubleshooting scenarios.
120
+
You can set up Azure Monitor to collect the [resource logs for device streams](monitor-iot-hub-reference.md#device-streams-category-preview) emitted by your IoT Hub. This approach can be helpful in troubleshooting scenarios.
121
121
122
-
Follow the steps below to create a diagnostics setting to send device streams logs for your IoT Hub to Azure Monitor Logs:
122
+
Follow these steps to create a diagnostics setting to send device streams logs for your IoT Hub to Azure Monitor Logs:
123
123
124
124
1. In Azure portal, navigate to your IoT hub. On the left pane, under **Monitoring**, select **Diagnostic settings**. Then select **Add diagnostic setting**.
125
125
126
126
2. Provide a name for your diagnostics setting and select **DeviceStreams** from the list of logs. Then select **Send to Log Analytics**. You'll be guided to choose an existing Log Analytics workspace or create a new one.
3. After you create a diagnostic setting to send your device streams logs to a Log Analytics workspace, you can access the logs by selecting **Logs** under **Monitoring** on the left pane of your IoT hub in Azure portal. Device streams logs will appear in the `AzureDiagnostics` table and have `Category=DeviceStreams`. Be aware that it may take several minutes following an operation for logs to appear in the table.
130
+
3. After you create a diagnostic setting to send your device streams logs to a Log Analytics workspace, you can access the logs by selecting **Logs** under **Monitoring** on the left pane of your IoT hub in Azure portal. Device streams logs appear in the `AzureDiagnostics` table and have `Category=DeviceStreams`. It might take several minutes following an operation for logs to appear in the table.
131
131
132
-
As shown below, the identity of the target device and the result of the operation is also available in the logs.
132
+
As shown here, the identity of the target device and the result of the operation is also available in the logs.
To learn more about using Azure Monitor with IoT Hub, see [Monitor IoT Hub](monitor-iot-hub.md). For information about all of the resource logs, metrics, and tables available for IoT Hub, see [Monitoring Azure IoT Hub data reference](monitor-iot-hub-reference.md).
137
137
138
138
## Regional availability
139
139
140
-
During public preview, IoT Hub device streams are available in the Central US, East US EUAP, North Europe, and Southeast Asia regions. Please make sure you create your hub in one of these regions.
140
+
During public preview, IoT Hub device streams are available in the Central US, East US EUAP, North Europe, and Southeast Asia regions. Make sure you create your hub in one of these regions.
141
141
142
142
## SDK availability
143
143
@@ -149,7 +149,5 @@ Two sides of each stream (on the device and service side) use the IoT Hub SDK to
149
149
150
150
## Next steps
151
151
152
-
Use the links below to learn more about device streams.
0 commit comments