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-amqp-support.md
+25-15Lines changed: 25 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,12 @@
1
1
---
2
2
title: Understand Azure IoT Hub AMQP support | Microsoft Docs
3
3
description: Developer guide - support for devices connecting to IoT Hub device-facing and service-facing endpoints using the AMQP Protocol. Includes information about built-in AMQP support in the Azure IoT device SDKs.
4
-
author: rezasherafat
5
-
manager:
4
+
author: robinsh
6
5
ms.service: iot-hub
7
6
services: iot-hub
8
7
ms.topic: conceptual
9
8
ms.date: 04/30/2019
10
-
ms.author: rezas
9
+
ms.author: robinsh
11
10
---
12
11
13
12
# Communicate with your IoT hub by using the AMQP Protocol
### Connect and authenticate to an IoT hub (service client)
20
+
21
21
To connect to an IoT hub by using AMQP, a client can use the [claims-based security (CBS)](https://www.oasis-open.org/committees/download.php/60412/amqp-cbs-v1.0-wd03.doc) or [Simple Authentication and Security Layer (SASL) authentication](https://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer).
22
22
23
23
The following information is required for the service client:
To learn about the cloud-to-device message exchange between the service and the IoT hub and between the device and the IoT hub, see [Send cloud-to-device messages from your IoT hub](iot-hub-devguide-messages-c2d.md). The service client uses two links to send messages and receive feedback for previously sent messages from devices, as described in the following table:
59
61
60
62
| Created by | Link type | Link path | Description |
@@ -117,8 +119,11 @@ for msg in batch:
117
119
```
118
120
119
121
As shown in the preceding code, a cloud-to-device feedback message has a content type of *application/vnd.microsoft.iothub.feedback.json*. You can use the properties in the message's JSON body to infer the delivery status of the original message:
122
+
120
123
* Key `statusCode` in the feedback body has one of the following values: *Success*, *Expired*, *DeliveryCountExceeded*, *Rejected*, or *Purged*.
124
+
121
125
* Key `deviceId` in the feedback body has the ID of the target device.
126
+
122
127
* Key `originalMessageId` in the feedback body has the ID of the original cloud-to-device message that was sent by the service. You can use this delivery status to correlate feedback to cloud-to-device messages.
123
128
124
129
### Receive telemetry messages (service client)
@@ -128,8 +133,11 @@ By default, your IoT hub stores ingested device telemetry messages in a built-in
128
133
For this purpose, the service client first needs to connect to the IoT hub endpoint and receive a redirection address to the built-in event hubs. The service client then uses the provided address to connect to the built-in event hub.
129
134
130
135
In each step, the client needs to present the following pieces of information:
136
+
131
137
* Valid service credentials (service shared access signature token).
138
+
132
139
* A well-formatted path to the consumer group partition that it intends to retrieve messages from. For a given consumer group and partition ID, the path has the following format: `/messages/events/ConsumerGroups/<consumer_group>/Partitions/<partition_id>` (the default consumer group is `$Default`).
140
+
133
141
* An optional filtering predicate to designate a starting point in the partition. This predicate can be in the form of a sequence number, offset, or enqueued timestamp.
134
142
135
143
The following code snippet uses the [uAMQP library in Python](https://github.com/Azure/azure-uamqp-python) to demonstrate the preceding steps:
@@ -189,29 +197,29 @@ for msg in batch:
189
197
190
198
For a given device ID, the IoT hub uses a hash of the device ID to determine which partition to store its messages in. The preceding code snippet demonstrates how events are received from a single such partition. However, note that a typical application often needs to retrieve events that are stored in all event hub partitions.
191
199
192
-
193
200
## Device client
194
201
195
202
### Connect and authenticate to an IoT hub (device client)
203
+
196
204
To connect to an IoT hub by using AMQP, a device can use [claims based security (CBS)](https://www.oasis-open.org/committees/download.php/60412/amqp-cbs-v1.0-wd03.doc) or [Simple Authentication and Security Layer (SASL)](https://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer) authentication.
197
205
198
206
The following information is required for the device client:
| Access key | A primary or secondary key that's associated with the device |
204
212
| Shared access signature | A short-lived shared access signature in the following format: `SharedAccessSignature sig={signature-string}&se={expiry}&skn={policyName}&sr={URL-encoded-resourceURI}`. To get the code for generating this signature, see [Control access to IoT Hub](./iot-hub-devguide-security.md#security-token-structure).
205
213
206
-
207
214
The following code snippet uses the [uAMQP library in Python](https://github.com/Azure/azure-uamqp-python) to connect to an IoT hub via a sender link.
208
215
209
216
```python
210
217
import uamqp
211
218
import urllib
212
219
import uuid
213
220
214
-
# Use generate_sas_token implementation available here: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-security#security-token-structure
221
+
# Use generate_sas_token implementation available here:
Cloud-to-device commands that are sent to devices arrive on a `/devices/<deviceID>/messages/devicebound` link. Devices can receive these messages in batches, and use the message data payload, message properties, annotations, or application properties in the message as needed.
242
250
243
251
The following code snippet uses the [uAMQP library in Python](https://github.com/Azure/azure-uamqp-python)) to receive cloud-to-device messages by a device.
244
252
245
253
```python
246
-
# ...
254
+
# ...
247
255
# Create a receive client for the cloud-to-device receive link on the device
uri ='amqps://{}:{}@{}{}'.format(urllib.quote_plus(username), urllib.quote_plus(sas_token), hostname, operation)
@@ -279,13 +287,13 @@ while True:
279
287
```
280
288
281
289
### Send telemetry messages (device client)
290
+
282
291
You can also send telemetry messages from a device by using AMQP. The device can optionally provide a dictionary of application properties, or various message properties, such as message ID.
283
292
284
293
The following code snippet uses the [uAMQP library in Python](https://github.com/Azure/azure-uamqp-python) to send device-to-cloud messages from a device.
285
294
286
-
287
295
```python
288
-
# ...
296
+
# ...
289
297
# Create a send client for the device-to-cloud send link on the device
uri ='amqps://{}:{}@{}{}'.format(urllib.quote_plus(username), urllib.quote_plus(sas_token), hostname, operation)
@@ -324,7 +332,9 @@ for result in results:
324
332
```
325
333
326
334
## Additional notes
335
+
327
336
* The AMQP connections might be disrupted because of a network glitch or the expiration of the authentication token (generated in the code). The service client must handle these circumstances and reestablish the connection and links, if needed. If an authentication token expires, the client can avoid a connection drop by proactively renewing the token prior to its expiration.
337
+
328
338
* Your client must occasionally be able to handle link redirections correctly. To understand such an operation, see your AMQP client documentation.
329
339
330
340
## Next steps
@@ -335,4 +345,4 @@ To learn more about IoT Hub messaging, see:
Copy file name to clipboardExpand all lines: articles/iot-hub/iot-hub-devguide-query-language.md
+8-5Lines changed: 8 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,12 @@
1
1
---
2
2
title: Understand the Azure IoT Hub query language | Microsoft Docs
3
3
description: Developer guide - description of the SQL-like IoT Hub query language used to retrieve information about device/module twins and jobs from your IoT hub.
4
-
author: rezasherafat
4
+
author: robinsh
5
5
ms.service: iot-hub
6
6
services: iot-hub
7
7
ms.topic: conceptual
8
8
ms.date: 10/29/2018
9
-
ms.author: rezas
9
+
ms.author: robinsh
10
10
---
11
11
12
12
# IoT Hub query language for device and module twins, jobs, and message routing
@@ -323,8 +323,8 @@ SELECT <select_list>
323
323
324
324
The **FROM <from_specification>** clause can assume only three values: **FROM devices** to query device twins, **FROM devices.modules** to query module twins, or **FROM devices.jobs** to query job per-device details.
325
325
326
-
327
326
## WHERE clause
327
+
328
328
The **WHERE <filter_condition>** clause is optional. It specifies one or more conditions that the JSON documents in the FROM collection must satisfy to be included as part of the result. Any JSON document must evaluate the specified conditions to "true" to be included in the result.
329
329
330
330
The allowed conditions are described in section [Expressions and conditions](iot-hub-devguide-query-language.md#expressions-and-conditions).
Currently, selection clauses different than **SELECT*** are only supported in aggregate queries on device twins.
362
362
363
363
## GROUP BY clause
364
+
364
365
The **GROUP BY <group_specification>** clause is an optional step that executes after the filter specified in the WHERE clause, and before the projection specified in the SELECT. It groups documents based on the value of an attribute. These groups are used to generate aggregated values as specified in the SELECT clause.
365
366
366
367
An example of a query using GROUP BY is:
@@ -388,9 +389,9 @@ Currently, the GROUP BY clause is only supported when querying device twins.
388
389
> [!IMPORTANT]
389
390
> The term `group` is currently treated as a special keyword in queries. In case, you use `group` as your property name, consider surrounding it with double brackets to avoid errors, e.g., `SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'`.
390
391
>
391
-
>
392
392
393
393
## Expressions and conditions
394
+
394
395
At a high level, an *expression*:
395
396
396
397
* Evaluates to an instance of a JSON type (such as Boolean, number, string, array, or object).
@@ -438,6 +439,7 @@ To understand what each symbol in the expressions syntax stands for, refer to th
438
439
| string_literal |String literals are Unicode strings represented by a sequence of zero or more Unicode characters or escape sequences. String literals are enclosed in single quotes or double quotes. Allowed escapes: `\'`, `\"`, `\\`, `\uXXXX` for Unicode characters defined by 4 hexadecimal digits. |
439
440
440
441
### Operators
442
+
441
443
The following operators are supported:
442
444
443
445
| Family | Operators |
@@ -447,6 +449,7 @@ The following operators are supported:
447
449
| Comparison |=, !=, <, >, <=, >=, <> |
448
450
449
451
### Functions
452
+
450
453
When querying twins and jobs the only supported function is:
451
454
452
455
| Function | Description |
@@ -496,4 +499,4 @@ In routes conditions, the following string functions are supported:
496
499
497
500
## Next steps
498
501
499
-
Learn how to execute queries in your apps using [Azure IoT SDKs](iot-hub-devguide-sdks.md).
502
+
Learn how to execute queries in your apps using [Azure IoT SDKs](iot-hub-devguide-sdks.md).
Copy file name to clipboardExpand all lines: articles/iot-hub/iot-hub-ip-filtering.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,12 @@
1
1
---
2
2
title: Azure IoT Hub IP connection filters | Microsoft Docs
3
3
description: How to use IP filtering to block connections from specific IP addresses for to your Azure IoT hub. You can block connections from individual or ranges of IP addresses.
Copy file name to clipboardExpand all lines: articles/iot-hub/iot-hub-mqtt-support.md
+2-3Lines changed: 2 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,12 @@
1
1
---
2
2
title: Understand Azure IoT Hub MQTT support | Microsoft Docs
3
3
description: Developer guide - support for devices connecting to an IoT Hub device-facing endpoint using the MQTT protocol. Includes information about built-in MQTT support in the Azure IoT device SDKs.
4
-
author: rezasherafat
5
-
manager:
4
+
author: robinsh
6
5
ms.service: iot-hub
7
6
services: iot-hub
8
7
ms.topic: conceptual
9
8
ms.date: 10/12/2018
10
-
ms.author: rezas
9
+
ms.author: robinsh
11
10
---
12
11
# Communicate with your IoT hub using the MQTT protocol
0 commit comments