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
In this tutorial, you learn how to create Python applications to send messages to and receive messages from a Service Bus queue.
24
+
This article shows you how to use Python to create, send messages to, and receive messages from Azure Service Bus queues.
25
25
26
-
## Prerequisites
27
-
1. An Azure subscription. To complete this tutorial, you need an Azure account. You can activate your [MSDN subscriber benefits](https://azure.microsoft.com/pricing/member-offers/credit-for-visual-studio-subscribers/?WT.mc_id=A85619ABF) or sign up for a [free account](https://azure.microsoft.com/free/?WT.mc_id=A85619ABF).
28
-
2. Follow steps in the [Use Azure portal to create a Service Bus queue](service-bus-quickstart-portal.md) article.
29
-
1. Read the quick **overview** of Service Bus **queues**.
30
-
2. Create a Service Bus **namespace**.
31
-
3. Get the **connection string**.
26
+
For more information about the Python Azure Service Bus libraries, see [Service Bus libraries for Python](/python/api/overview/azure/servicebus?view=azure-python).
32
27
33
-
> [!NOTE]
34
-
> You will create a **queue** in the Service Bus namespace by using Python in this tutorial.
35
-
1. Install Python or the [Python Azure Service Bus package][Python Azure Service Bus package], see the [Python Installation Guide](/azure/python/python-sdk-azure-install). See full documentation of Service Bus Python SDK [here](/python/api/overview/azure/servicebus?view=azure-python).
28
+
## Prerequisites
29
+
- An Azure subscription. You can activate your [Visual Studio or MSDN subscriber benefits](https://azure.microsoft.com/pricing/member-offers/msdn-benefits-details/?WT.mc_id=A85619ABF) or sign up for a [free account](https://azure.microsoft.com/free/?WT.mc_id=A85619ABF).
30
+
- A Service Bus namespace, created by following the steps at [Quickstart: Use the Azure portal to create a Service Bus topic and subscriptions](service-bus-quickstart-topics-subscriptions-portal.md). Copy the primary connection string from the **Shared access policies** screen to use later in this article.
31
+
- Python 3.4x or above, with the [Python Azure Service Bus][Python Azure Service Bus package] package installed. For more information, see the [Python Installation Guide](/azure/python/python-sdk-azure-install).
36
32
37
33
## Create a queue
38
-
The **ServiceBusClient** object enables you to work with queues. Add the following code near the top of any Python file in which you wish to programmatically access Service Bus:
34
+
35
+
A **ServiceBusClient** object lets you work with queues. To programmatically access Service Bus, add the following line near the top of your Python file:
39
36
40
37
```python
41
38
from azure.servicebus import ServiceBusClient
42
39
```
43
40
44
-
The following code creates a **ServiceBusClient** object. Replace `<CONNECTION STRING>` with your servicebus connectionstring.
41
+
Add the following code to create a **ServiceBusClient** object. Replace `<connectionstring>` with your Service Bus primary connection string value. You can find this value under **Shared access policies** in your Service Bus namespace in the [Azure portal][Azure portal].
The values for the SAS key name and value can be found in the [Azure portal][Azure portal] connection information, or in the Visual Studio **Properties**pane when selecting the Service Bus namespace in Server Explorer (as shown in the previous section).
47
+
The following code uses the `create_queue` method of the **ServiceBusClient**to create a queue named `taskqueue` with default settings:
51
48
52
49
```python
53
50
sb_client.create_queue("taskqueue")
54
51
```
55
52
56
-
The `create_queue` method also supports additional options, which enable you to override default queue settings such as message time to live (TTL) or maximum queue size. The following example sets the maximum queue size to 5 GB, and the TTL value to 1 minute:
53
+
You can use optionsto override default queue settings, such as message time to live (TTL) or maximum topic size. The following code creates a queue called `taskqueue` with a maximum queue size of 5 GB and TTL value of 1 minute:
For more information, see [Azure Service Bus Python documentation](/python/api/overview/azure/servicebus?view=azure-python).
64
-
65
60
## Send messages to a queue
66
-
To send a message to a Service Bus queue, your application calls the `send` method on the `ServiceBusClient` object.
67
61
68
-
The following example demonstrates how to send a test message to the queue named `taskqueue`using `send_queue_message`:
62
+
To send a message to a Service Bus queue, an application calls the `send` method on the **ServiceBusClient** object. The following code example creates a queue client and sends a test message to the `taskqueue`queue. Replace `<connectionstring>` with your Service Bus primary connection string value.
Service Bus queues support a maximum message size of 256 KB in the [Standard tier](service-bus-premium-messaging.md) and 1 MB in the [Premium tier](service-bus-premium-messaging.md). The header, which includes the standard and custom application properties, can have
83
-
a maximum size of 64 KB. There is no limit on the number of messages held in a queue but there is a cap on the total size of the messages held by a queue. This queue size is defined at creation time, with an upper limit of 5 GB. For more information about quotas, see [Service Bus quotas][Service Bus quotas].
75
+
### Message size limits and quotas
76
+
77
+
Service Bus queues support a maximum message size of 256 KB in the [Standard tier](service-bus-premium-messaging.md) and 1 MB in the [Premium tier](service-bus-premium-messaging.md). The header, which includes the standard and custom application properties, can have a maximum size of 64 KB. There's no limit on the number of messages a queue can hold, but there's a cap on the total size of the messages the queue holds. You can define queue size at creation time, with an upper limit of 5 GB.
84
78
85
-
For more information, see [Azure Service Bus Python documentation](/python/api/overview/azure/servicebus?view=azure-python).
79
+
For more information about quotas, see [Service Bus quotas][Service Bus quotas].
86
80
87
81
## Receive messages from a queue
88
-
Messages are received from a queue using the `get_receiver` method on the `ServiceBusService` object:
82
+
83
+
The queue client receives messages from a queue by using the `get_receiver` method on the **ServiceBusClient** object. The following code example creates a queue client and receives a message from the `taskqueue` queue. Replace `<connectionstring>` with your Service Bus primary connection string value.
with queue_client.get_receiver() as queue_receiver:
@@ -102,36 +96,30 @@ with queue_client.get_receiver() as queue_receiver:
102
96
message.complete()
103
97
```
104
98
105
-
For more information, see [Azure Service Bus Python documentation](/python/api/overview/azure/servicebus?view=azure-python).
99
+
### Use the peek_lock parameter
106
100
101
+
The optional `peek_lock` parameter of `get_receiver` determines whether Service Bus deletes messages from the queue as they're read. The default mode for message receiving is *PeekLock*, or `peek_lock` set to **True**, which reads (peeks) and locks messages without deleting them from the queue. Each message must then be explicitly completed to remove it from the queue.
107
102
108
-
Messages are deleted from the queue as they are read when the parameter `peek_lock`is set to **False**. You can read (peek) and lock the message without deleting it from the queue by setting the parameter `peek_lock` to **True**.
103
+
To delete messages from the queue as they're read, you can set the `peek_lock`parameter of `get_receiver`to **False**. Deleting messages as part of the receive operation is the simplest model, but only works if the application can tolerate missing messages if there's a failure. To understand this behavior, consider a scenario in which the consumer issues a receive request and then crashes before processing it. If the message was deleted on being received, when the application restarts and begins consuming messages again, it has missed the message it received before the crash.
109
104
110
-
The behavior of reading and deleting the message as part of the receive operation is the simplest model, and works best for scenarios in which an application can tolerate not processing a message in the event of a failure. To understand this, consider a scenario in which the consumer issues the receive request and then crashes before processing it. Because Service Bus will have marked the message as being consumed, then when the application restarts and begins consuming messages again, it will have missed the message that was consumed prior to the crash.
105
+
If your application can't tolerate missed messages, receive is a two-stage operation. PeekLock finds the next message to be consumed, locks it to prevent other consumers from receiving it, and returns it to the application. After processing or storing the message, the application completes the second stage of the receive process by calling the `complete` method on the **Message** object. The `complete` method marks the message as being consumedand removes it from the queue.
111
106
112
-
If the `peek_lock` parameter is set to **True**, the receive becomes a two stage operation, which makes it possible to support applications that cannot tolerate missing messages. When Service Bus receives a request, it finds the next message to be consumed, locks it to prevent other consumers receiving it, and then returns it to the application. After the application finishes processing the message (or stores it reliably for future processing), it completes the second stage of the receive process by calling the **delete** method on the **Message** object. The **delete** method will mark the message as being consumed and remove it from the queue.
107
+
## Handle application crashes and unreadable messages
113
108
114
-
```python
115
-
msg.delete()
116
-
```
109
+
Service Bus provides functionality to help you gracefully recover from errors in your application or difficulties processing a message. If a receiver application can't process a message for some reason, it can call the `unlock` method on the **Message** object. Service Bus unlocks the message within the queue and makes it available to be received again, either by the same or another consuming application.
117
110
118
-
## How to handle application crashes and unreadable messages
119
-
Service Bus provides functionality to help you gracefully recover from errors in your application or difficulties processing a message. If a receiver application is unable to process the message for some reason, then it can call the **unlock** method on the **Message** object. This will cause Service Bus to unlock the message within the queue and make it available to be received again, either by the same consuming application or by another consuming application.
111
+
There's also a timeout for messages locked within the queue. If an application fails to process a message before the lock timeout expires, for example if the application crashes, Service Bus unlocks the message automatically and makes it available to be received again.
120
112
121
-
There is also a timeout associated with a message locked within the queue, and if the application fails to process the message before the lock timeout expires (for example, if the application crashes), then Service Bus will unlock the message automatically and make it available to be received again.
113
+
If an application crashes after processing a message but before calling the `complete` method, the message is redelivered to the application when it restarts. This behavior is often called *At-least-once Processing*. Each message is processed at least once, but in certain situations the same message may be redelivered. If your scenario can't tolerate duplicate processing, you can use the **MessageId** property of the message, which remains constant across delivery attempts, to handle duplicate message delivery.
122
114
123
-
In the event that the application crashes after processing the message but before the **delete** method is called, then the message will be redelivered to the application when it restarts. This is often called **at least once processing**, that is, each message will be processed at least once but in certain situations the same message may be redelivered. If the scenario cannot tolerate duplicate processing, then application developers should add additional logic to their application to handle duplicate message delivery. This is often achieved using the **MessageId** property of the message, which will remain constant across delivery attempts.
124
-
125
-
> [!NOTE]
126
-
> You can manage Service Bus resources with [Service Bus Explorer](https://github.com/paolosalvatori/ServiceBusExplorer/). The Service Bus Explorer allows users to connect to a Service Bus namespace and administer messaging entities in an easy manner. The tool provides advanced features like import/export functionality or the ability to test topic, queues, subscriptions, relay services, notification hubs and events hubs.
115
+
> [!TIP]
116
+
> You can manage Service Bus resources with [Service Bus Explorer](https://github.com/paolosalvatori/ServiceBusExplorer/). Service Bus Explorer lets you connect to a Service Bus namespace and easily administer messaging entities. The tool provides advanced features like import/export functionality and the ability to test topics, queues, subscriptions, relay services, notification hubs, and event hubs.
127
117
128
118
## Next steps
129
-
Now that you have learned the basics of Service Bus queues, see these articles to learn more.
130
119
131
-
*[Queues, topics, and subscriptions][Queues, topics, and subscriptions]
120
+
Now that you've learned the basics of Service Bus queues, see [Queues, topics, and subscriptions][Queues, topics, and subscriptions] to learn more.
132
121
133
122
[Azure portal]: https://portal.azure.com
134
123
[Python Azure Service Bus package]: https://pypi.python.org/pypi/azure-servicebus
135
124
[Queues, topics, and subscriptions]: service-bus-queues-topics-subscriptions.md
0 commit comments