Merge pull request #77144 from rezasherafat/docupdate_amqp_3

Added service telemetry receive using AMQP.

Author: American-Dipper

articles/iot-hub/iot-hub-amqp-support.md

@@ -60,7 +60,7 @@ The cloud-to-device message exchange between service and IoT Hub as well as betw
 | Created by | Link type | Link path | Description |
 |------------|-----------|-----------|-------------|
 | Service | Sender link | `/messages/devicebound` | C2D messages destined to devices are sent to this link by the service. Messages sent over this link have their `To` property set to the target device's receiver link path: i.e., `/devices/<deviceID>/messages/devicebound`. |
-| Service | Receiver link | `/messages/serviceBound/feedback` | Completion, rejection, and abandonment feedback messages coming from devices received on this link by service. See [here](./iot-hub-devguide-messages-c2d.md#message-feedback) for more information about feedback messages. |
+| Service | Receiver link | `/messages/serviceBound/feedback` | Completion, rejection, and abandonment feedback messages coming from devices received on this link by service. For more information about feedback messages, see [here](./iot-hub-devguide-messages-c2d.md#message-feedback). |
 
 The code snippet below demonstrates how to create a C2D message and send it to a device using [uAMQP library in Python](https://github.com/Azure/azure-uamqp-python).
 
@@ -122,11 +122,76 @@ As shown above, a C2D feedback message has content type of `application/vnd.micr
 * Key `originalMessageId` in feedback body has the ID of the original C2D message sent by the service. This can be used to correlate feedback to C2D messages.
 
 ### Receive telemetry messages (service client)
+By default, IoT Hub stores ingested device telemetry messages in a built-in Event hub. Your service client can use the AMQP protocol to receive the stored events.
+
+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. Service client then uses the provided address to connect to the built-in Event hub.
+
+In each step, the client needs to present the following pieces of information:
+* Valid service credentials (service SAS token).
+* A well-formatted path to the consumer group partition 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`).
+* An optional filtering predicate to designate a starting point in the partition (this can be in the form of a sequence number, offset or enqueued timestamp).
+
+The code snippet below uses [uAMQP library in Python](https://github.com/Azure/azure-uamqp-python) to demonstrate the above steps.
+
+```python
+import json
+import uamqp
+import urllib
+import time
+
+# Use generate_sas_token implementation available here: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-security#security-token-structure
+from helper import generate_sas_token
+
+iot_hub_name = '<iot-hub-name>'
+hostname = '{iot_hub_name}.azure-devices.net'.format(iot_hub_name=iot_hub_name)
+policy_name = 'service'
+access_key = '<primary-or-secondary-key>'
+operation = '/messages/events/ConsumerGroups/{consumer_group}/Partitions/{p_id}'.format(consumer_group='$Default', p_id=0)
+
+username = '{policy_name}@sas.root.{iot_hub_name}'.format(policy_name=policy_name, iot_hub_name=iot_hub_name)
+sas_token = generate_sas_token(hostname, access_key, policy_name)
+uri = 'amqps://{}:{}@{}{}'.format(urllib.quote_plus(username), urllib.quote_plus(sas_token), hostname, operation)
+
+# Optional filtering predicates can be specified using endpiont_filter
+# Valid predicates include:
+# - amqp.annotation.x-opt-sequence-number
+# - amqp.annotation.x-opt-offset
+# - amqp.annotation.x-opt-enqueued-time
+# Set endpoint_filter variable to None if no filter is needed
+endpoint_filter = b'amqp.annotation.x-opt-sequence-number > 2995'
+
+# Helper function to set the filtering predicate on the source URI
+def set_endpoint_filter(uri, endpoint_filter=''):
+  source_uri = uamqp.address.Source(uri)
+  source_uri.set_filter(endpoint_filter)
+  return source_uri
+
+receive_client = uamqp.ReceiveClient(set_endpoint_filter(uri, endpoint_filter), debug=True)
+try:
+  batch = receive_client.receive_message_batch(max_batch_size=5)
+except uamqp.errors.LinkRedirect as redirect:
+  # Once a redirect error is received, close the original client and recreate a new one to the re-directed address
+  receive_client.close()
+
+  sas_auth = uamqp.authentication.SASTokenAuth.from_shared_access_key(redirect.address, policy_name, access_key)
+  receive_client = uamqp.ReceiveClient(set_endpoint_filter(redirect.address, endpoint_filter), auth=sas_auth, debug=True)
+
+# Start receiving messages in batches
+batch = receive_client.receive_message_batch(max_batch_size=5)
+for msg in batch:
+  print('*** received a message ***')
+  print(''.join(msg.get_data()))
+  print('\t: ' + str(msg.annotations['x-opt-sequence-number']))
+  print('\t: ' + str(msg.annotations['x-opt-offset']))
+  print('\t: ' + str(msg.annotations['x-opt-enqueued-time']))
+```
+
+For a given device ID, IoT Hub uses a hash of the device ID to determine which partition to store its messages in. The code snippet above demonstrates receiving events from a single such partition. Note, however, that a typical application often needs to retrieve events stored in all event hub partitions.
 
 
 ### Additional notes
 * The AMQP connections may be disrupted due to network glitch, or expiry of the authentication token (generated in the code). The service client must handle these circumstances and re-establish the connection and links if needed. For the case of authentication token expiry, the client can also proactively renew the token prior to its expiry to avoid a connection drop.
-* In some cases, your client must be able to correctly handle link redirections. Refer to your AMQP client documentation on how to do this.
+* In some cases, your client must be able to correctly handle link redirections. Refer to your AMQP client documentation on how to handle this operation.
 
 ### Receive cloud-to-device messages (device and module client)
 AMQP links used on the device side are as follows: