Microsoft Azure Service Bus Client Library for Python
Azure Service Bus is a high performance cloud-managed messaging service for providing real-time and fault-tolerant communication between distributed senders and receivers.
Service Bus provides multiple mechanisms for asynchronous highly reliable communication, such as structured first-in-first-out messaging, publish/subscribe capabilities, and the ability to easily scale as your needs grow.
Use the Service Bus client library for Python to communicate between applications and services and implement asynchronous messaging patterns.
Source code | Package (PyPi) | Package (Conda) | API reference documentation | Product documentation | Samples | Changelog
NOTE: If you are using version 0.50 or lower and want to migrate to the latest version of this package please look at our migration guide to move from Service Bus V0.50 to Service Bus V7.
Install the Azure Service Bus client library for Python with pip:
pip install azure-servicebus
To use this package, you must have:
If you need an Azure service bus namespace, you can create it via the Azure Portal. If you do not wish to use the graphical portal UI, you can use the Azure CLI via Cloud Shell, or Azure CLI run locally, to create one with this Azure CLI command:
az servicebus namespace create --resource-group <resource-group-name> --name <servicebus-namespace-name> --location <servicebus-namespace-location>
Interaction with Service Bus starts with an instance of the ServiceBusClient
class. You either need a connection string with SAS key, or a namespace and one of its account keys to instantiate the client object.
Please find the samples linked below for demonstration as to how to authenticate via either approach.
TokenCredential
protocol available in the
azure-identity package. The fully qualified namespace is of the format <yournamespace.servicebus.windows.net>
.azure-identity
, please install the package:
pip install azure-identity
aiohttp
:
pip install aiohttp
Note: client can be initialized without a context manager, but must be manually closed via client.close() to not leak resources.
Once you've initialized a ServiceBusClient
, you can interact with the primary resource types within a Service Bus Namespace, of which multiple can exist and on which actual message transmission takes place, the namespace often serving as an application container:
Queue: Allows for Sending and Receiving of message. Often used for point-to-point communication.
Topic: As opposed to Queues, Topics are better suited to publish/subscribe scenarios. A topic can be sent to, but requires a subscription, of which there can be multiple in parallel, to consume from.
Subscription: The mechanism to consume from a Topic. Each subscription is independent, and receives a copy of each message sent to the topic. Rules and Filters can be used to tailor which messages are received by a specific subscription.
For more information about these resources, see What is Azure Service Bus?.
To interact with these resources, one should be familiar with the following SDK concepts:
ServiceBusClient: This is the object a user should first initialize to connect to a Service Bus Namespace. To interact with a queue, topic, or subscription, one would spawn a sender or receiver off of this client.
ServiceBusSender: To send messages to a Queue or Topic, one would use the corresponding get_queue_sender
or get_topic_sender
method off of a ServiceBusClient
instance as seen here.
ServiceBusReceiver: To receive messages from a Queue or Subscription, one would use the corresponding get_queue_receiver
or get_subscription_receiver
method off of a ServiceBusClient
instance as seen here.
ServiceBusMessage: When sending, this is the type you will construct to contain your payload. When receiving, this is where you will access the payload.
We do not guarantee that the ServiceBusClient, ServiceBusSender, and ServiceBusReceiver are thread-safe. We do not recommend reusing these instances across threads. It is up to the running application to use these classes in a thread-safe manner.
The following sections provide several code snippets covering some of the most common Service Bus tasks, including:
To perform management tasks such as creating and deleting queues/topics/subscriptions, please utilize the azure-mgmt-servicebus library, available here.
Please find further examples in the samples directory demonstrating common Service Bus scenarios such as sending, receiving, session management and message handling.
NOTE: see reference documentation here.
This example sends single message and array of messages to a queue that is assumed to already exist, created via the Azure portal or az commands.
from azure.servicebus import ServiceBusClient, ServiceBusMessage
import os
connstr = os.environ['SERVICE_BUS_CONNECTION_STR']
queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']
with ServiceBusClient.from_connection_string(connstr) as client:
with client.get_queue_sender(queue_name) as sender:
# Sending a single message
single_message = ServiceBusMessage("Single message")
sender.send_messages(single_message)
# Sending a list of messages
messages = [ServiceBusMessage("First message"), ServiceBusMessage("Second message")]
sender.send_messages(messages)
NOTE: A message may be scheduled for delayed delivery using the
ServiceBusSender.schedule_messages()
method, or by specifyingServiceBusMessage.scheduled_enqueue_time_utc
before callingServiceBusSender.send_messages()
For more detail on scheduling and schedule cancellation please see a sample here.
To receive from a queue, you can either perform an ad-hoc receive via receiver.receive_messages()
or receive persistently through the receiver itself.
from azure.servicebus import ServiceBusClient
import os
connstr = os.environ['SERVICE_BUS_CONNECTION_STR']
queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']
with ServiceBusClient.from_connection_string(connstr) as client:
# max_wait_time specifies how long the receiver should wait with no incoming messages before stopping receipt.
# Default is None; to receive forever.
with client.get_queue_receiver(queue_name, max_wait_time=30) as receiver:
for msg in receiver: # ServiceBusReceiver instance is a generator.
print(str(msg))
# If it is desired to halt receiving early, one can break out of the loop here safely.
NOTE: Any message received with
receive_mode=PEEK_LOCK
(this is the default, with the alternative RECEIVE_AND_DELETE removing the message from the queue immediately on receipt) has a lock that must be renewed viareceiver.renew_message_lock
before it expires if processing would take longer than the lock duration. See AutoLockRenewer for a helper to perform this in the background automatically. Lock duration is set in Azure on the queue or topic itself.
NOTE:
ServiceBusReceiver.receive_messages()
receives a single or constrained list of messages through an ad-hoc method call, as opposed to receiving perpetually from the generator. It always returns a list.
from azure.servicebus import ServiceBusClient
import os
connstr = os.environ['SERVICE_BUS_CONNECTION_STR']
queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']
with ServiceBusClient.from_connection_string(connstr) as client:
with client.get_queue_receiver(queue_name) as receiver:
received_message_array = receiver.receive_messages(max_wait_time=10) # try to receive a single message within 10 seconds
if received_message_array:
print(str(received_message_array[0]))
with client.get_queue_receiver(queue_name) as receiver:
received_message_array = receiver.receive_messages(max_message_count=5, max_wait_time=10) # try to receive maximum 5 messages in a batch within 10 seconds
for message in received_message_array:
print(str(message))
In this example, max_message_count declares the maximum number of messages to attempt receiving before hitting a max_wait_time as specified in seconds.
NOTE: It should also be noted that
ServiceBusReceiver.peek_messages()
is subtly different than receiving, as it does not lock the messages being peeked, and thus they cannot be settled.
NOTE: see reference documentation for session send and receive.
Sessions provide first-in-first-out and single-receiver semantics on top of a queue or subscription. While the actual receive syntax is the same, initialization differs slightly.
from azure.servicebus import ServiceBusClient, ServiceBusMessage
import os
connstr = os.environ['SERVICE_BUS_CONNECTION_STR']
queue_name = os.environ['SERVICE_BUS_SESSION_QUEUE_NAME']
session_id = os.environ['SERVICE_BUS_SESSION_ID']
with ServiceBusClient.from_connection_string(connstr) as client:
with client.get_queue_sender(queue_name) as sender:
sender.send_messages(ServiceBusMessage("Session Enabled Message", session_id=session_id))
# If session_id is null here, will receive from the first available session.
with client.get_queue_receiver(queue_name, session_id=session_id) as receiver:
for msg in receiver:
print(str(msg))
NOTE: Messages received from a session do not need their locks renewed like a non-session receiver; instead the lock management occurs at the session level with a session lock that may be renewed with
receiver.session.renew_lock()
NOTE: see reference documentation for topics and subscriptions.
Topics and subscriptions give an alternative to queues for sending and receiving messages. See documents here for more overarching detail, and of how these differ from queues.
from azure.servicebus import ServiceBusClient, ServiceBusMessage
import os
connstr = os.environ['SERVICE_BUS_CONNECTION_STR']
topic_name = os.environ['SERVICE_BUS_TOPIC_NAME']
subscription_name = os.environ['SERVICE_BUS_SUBSCRIPTION_NAME']
with ServiceBusClient.from_connection_string(connstr) as client:
with client.get_topic_sender(topic_name) as sender:
sender.send_messages(ServiceBusMessage("Data"))
# If session_id is null here, will receive from the first available session.
with client.get_subscription_receiver(topic_name, subscription_name) as receiver:
for msg in receiver:
print(str(msg))
When receiving from a queue, you have multiple actions you can take on the messages you receive.
NOTE: You can only settle
ServiceBusReceivedMessage
objects which are received inServiceBusReceiveMode.PEEK_LOCK
mode (this is the default).ServiceBusReceiveMode.RECEIVE_AND_DELETE
mode removes the message from the queue on receipt.ServiceBusReceivedMessage
messages returned frompeek_messages()
cannot be settled, as the message lock is not taken like it is in the aforementioned receive methods.
If the message has a lock as mentioned above, settlement will fail if the message lock has expired.
If processing would take longer than the lock duration, it must be maintained via receiver.renew_message_lock
before it expires.
Lock duration is set in Azure on the queue or topic itself.
See AutoLockRenewer for a helper to perform this in the background automatically.
Declares the message processing to be successfully completed, removing the message from the queue.
from azure.servicebus import ServiceBusClient
import os
connstr = os.environ['SERVICE_BUS_CONNECTION_STR']
queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']
with ServiceBusClient.from_connection_string(connstr) as client:
with client.get_queue_receiver(queue_name) as receiver:
for msg in receiver:
print(str(msg))
receiver.complete_message(msg)
Abandon processing of the message for the time being, returning the message immediately back to the queue to be picked up by another (or the same) receiver.
from azure.servicebus import ServiceBusClient
import os
connstr = os.environ['SERVICE_BUS_CONNECTION_STR']
queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']
with ServiceBusClient.from_connection_string(connstr) as client:
with client.get_queue_receiver(queue_name) as receiver:
for msg in receiver:
print(str(msg))
receiver.abandon_message(msg)
Transfer the message from the primary queue into a special "dead-letter sub-queue" where it can be accessed using the ServiceBusClient.get_<queue|subscription>_receiver
function with parameter sub_queue=ServiceBusSubQueue.DEAD_LETTER
and consumed from like any other receiver. (see sample here)
from azure.servicebus import ServiceBusClient
import os
connstr = os.environ['SERVICE_BUS_CONNECTION_STR']
queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']
with ServiceBusClient.from_connection_string(connstr) as client:
with client.get_queue_receiver(queue_name) as receiver:
for msg in receiver:
print(str(msg))
receiver.dead_letter_message(msg)
Defer is subtly different from the prior settlement methods. It prevents the message from being directly received from the queue
by setting it aside such that it must be received by sequence number in a call to ServiceBusReceiver.receive_deferred_messages
(see sample here)
from azure.servicebus import ServiceBusClient
import os
connstr = os.environ['SERVICE_BUS_CONNECTION_STR']
queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']
with ServiceBusClient.from_connection_string(connstr) as client:
with client.get_queue_receiver(queue_name) as receiver:
for msg in receiver:
print(str(msg))
receiver.defer_message(msg)
NOTE: see reference documentation for auto-lock-renewal.
AutoLockRenewer
is a simple method for ensuring your message or session remains locked even over long periods of time, if calling receiver.renew_message_lock
/receiver.session.renew_lock
is impractical or undesired.
Internally, it is not much more than shorthand for creating a concurrent watchdog to do lock renewal if the object is nearing expiry.
It should be used as follows:
from azure.servicebus import ServiceBusClient, AutoLockRenewer
import os
connstr = os.environ['SERVICE_BUS_CONNECTION_STR']
queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']
# Can also be called via "with AutoLockRenewer() as renewer" to automate closing.
renewer = AutoLockRenewer()
with ServiceBusClient.from_connection_string(connstr) as client:
with client.get_queue_receiver(queue_name) as receiver:
for msg in receiver.receive_messages():
renewer.register(receiver, msg, max_lock_renewal_duration=60)
# Do your application logic here
receiver.complete_message(msg)
renewer.close()
from azure.servicebus import ServiceBusClient, AutoLockRenewer
import os
connstr = os.environ['SERVICE_BUS_CONNECTION_STR']
session_queue_name = os.environ['SERVICE_BUS_SESSION_QUEUE_NAME']
session_id = os.environ['SERVICE_BUS_SESSION_ID']
# Can also be called via "with AutoLockRenewer() as renewer" to automate closing.
renewer = AutoLockRenewer()
with ServiceBusClient.from_connection_string(connstr) as client:
with client.get_queue_receiver(session_queue_name, session_id=session_id) as receiver:
renewer.register(receiver, receiver.session, max_lock_renewal_duration=300) # Duration for how long to maintain the lock for, in seconds.
for msg in receiver.receive_messages():
# Do your application logic here
receiver.complete_message(msg)
renewer.close()
If for any reason auto-renewal has been interrupted or failed, this can be observed via the auto_renew_error
property on the object being renewed, or by having passed a callback to the on_lock_renew_failure
parameter on renewer initialization.
It would also manifest when trying to take action (such as completing a message) on the specified object.
azure.servicebus
logger to collect traces from the library.uamqp
logger to collect traces from the underlying uAMQP library.logging_enable=True
when creating the client.uamqp
logging to be too verbose. To suppress unnecessary logging, add the following snippet to the top of your code:import logging
# The logging levels below may need to be changed based on the logging that you want to suppress.
uamqp_logger = logging.getLogger('uamqp')
uamqp_logger.setLevel(logging.ERROR)
# or even further fine-grained control, suppressing the warnings in uamqp.connection module
uamqp_connection_logger = logging.getLogger('uamqp.connection')
uamqp_connection_logger.setLevel(logging.ERROR)
There are various timeouts a user should be aware of within the library.
receive_messages()
, the time after which receiving messages will halt after no traffic. This applies both to the imperative receive_messages()
function as well as the length
a generator-style receive will run for before exiting if there are no messages. Passing None (default) will wait forever, up until the 10 minute threshold if no other action is taken.NOTE: If processing of a message or session is sufficiently long as to cause timeouts, as an alternative to calling
receiver.renew_message_lock
/receiver.session.renew_lock
manually, one can leverage theAutoLockRenewer
functionality detailed above.
The Service Bus APIs generate the following exceptions in azure.servicebus.exceptions:
Message
is too large. It is recommended to reduce the count of messages being sent in a batch or the size of content being passed into a single ServiceBusMessage
.AutoLockRenewer
could help on keeping the lock of the message automatically renewed.AutoLockRenewer
could help on keeping the lock of the session automatically renewed.AutoLockRenewer
is closed or the lock of the renewable has expired.
It is recommended to re-register the renewable message or session by receiving the message or connect to the sessionful entity again.Please view the exceptions reference docs for detailed descriptions of our common Exception types.
Please find further examples in the samples directory demonstrating common Service Bus scenarios such as sending, receiving, session management and message handling.
For more extensive documentation on the Service Bus service, see the Service Bus documentation on docs.microsoft.com.
For users seeking to perform management operations against ServiceBus (Creating a queue/topic/etc, altering filter rules, enumerating entities) please see the azure-mgmt-servicebus documentation for API documentation. Terse usage examples can be found here as well.
The Azure Service Bus client library is now based on a pure Python AMQP implementation. uAMQP
has been removed as required dependency.
To use uAMQP
as the underlying transport:
uamqp
with pip.$ pip install uamqp
uamqp_transport=True
during client construction.from azure.servicebus import ServiceBusClient
connection_str = '<< CONNECTION STRING FOR THE SERVICE BUS NAMESPACE >>'
queue_name = '<< NAME OF THE QUEUE >>'
client = ServiceBusClient.from_connection_string(
connection_str, uamqp_transport=True
)
Note: The message
attribute on ServiceBusMessage
/ServiceBusMessageBatch
/ServiceBusReceivedMessage
, which previously exposed the uamqp.Message
, has been deprecated.
The "Legacy" objects returned by message
attribute have been introduced to help facilitate the transition.
azure-servicebus
depends on the uAMQP for the AMQP protocol implementation.
uAMQP wheels are provided for most major operating systems and will be installed automatically when installing azure-servicebus
.
If uAMQP is intended to be used as the underlying AMQP protocol implementation for azure-servicebus
,
uAMQP wheels can be found for most major operating systems.
If you're running on a platform for which uAMQP wheels are not provided, please follow
If you intend to use uAMQP
and you're running on a platform for which uAMQP wheels are not provided, please follow
the uAMQP Installation guidance to install from source.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
prefetch_count
was not being passed through correctly and caused messages to not be received as expected when in RECEIVE_AND_DELETE
mode (#31712, #31711).NoneType object has no attribute 'settle_messages'
which was raised when a connection was dropped due to a blocked process (#30514)__contains__
method was added to azure.servicebus
for the following (PR #30846, thanks @pamelafox).
ServiceBusConnectionStringProperties
amqp.AmqpMessageHeader
amqp.AmqpMessageProperties
management.AccessRights
management.NamespaceProperties
management.QueueProperties
management.TopicProperties
management.SubscriptionProperties
management.RuleProperties
end frame received on invalid channel
which was raised when a disconnect was sent by the service (#30860)link already closed
which was raised when the client was closing and disconnecting from the service (#30836)MessageLockLostError
from the superclass ServiceBusError
.socket_timeout
has been added to get_queue_sender
, get_queue_receiver
, get_topic_sender
, and get_subscription_receiver
on the sync and async ServiceBusClient
.delivery_id
being None
.Diagnostic-Id
if the traceparent
message application property is not found.component
attribute was removed from all spans.Version 7.10.0 is our first stable release of the Azure Service Bus client library based on a pure Python implemented AMQP stack.
uamqp_transport
has been added to sync and async ServiceBusClient
constructors which indicates whether to use the uamqp
library or the default pure Python AMQP library as the underlying transport.websocket-client
for syncaiohttp
for asyncuamqp_transport
keyword.ServiceBusAdministrationClient
expected credential
with get_token
method returning AccessToken.token
of type bytes
and not str
, now matching the documentation.raw_amqp_message.header
and message.header
properties on ServiceReceivedBusMessage
were returned with durable
, first_acquirer
, and priority
properties set by default, rather than the values returned by the service.ServiceBusReceivedMessage
was not picklable (Issue #27947).message
attribute on ServiceBus
/ServiceBusMessageBatch
/ServiceBusReceivedMessage
, which previously exposed the uamqp.Message
/uamqp.BatchMessage
, has been deprecated.
LegacyMessage
/LegacyBatchMessage
objects returned by the message
attribute on ServiceBus
/ServiceBusMessageBatch
have been introduced to help facilitate the transition.uamqp >= 1.6.3
as an optional dependency for use with the uamqp_transport
keyword.messaging.system
- messaging system (i.e., servicebus
)messaging.operation
- type of operation (i.e., publish
, receive
, or settle
)messaging.batch.message_count
- number of messages sent or received (if more than one)ServiceBus.complete
)az.namespace
, messaging.destination.name
, net.peer.name
, messaging.system
, and messaging.operation
attributes.send
spans now contain links to message
spans. Now, message
spans will no longer contain a link to the send
span.uamqp_transport
has been added to sync and async ServiceBusClient
constructors which indicates whether to use the uamqp
library or the default pure Python AMQP library as the underlying transport.ServiceBusAdministrationClient
expected credential
with get_token
method returning AccessToken.token
of type bytes
and not str
, now matching the documentation.raw_amqp_message.header
and message.header
properties on ServiceReceivedBusMessage
were returned with durable
, first_acquirer
, and priority
properties set by default, rather than the values returned by the service.message
attribute on ServiceBus
/ServiceBusMessageBatch
/ServiceBusReceivedMessage
, which previously exposed the uamqp.Message
/uamqp.BatchMessage
, has been deprecated.
LegacyMessage
/LegacyBatchMessage
objects returned by the message
attribute on ServiceBus
/ServiceBusMessageBatch
have been introduced to help facilitate the transition.uamqp >= 1.6.3
as an optional dependency for use with the uamqp_transport
keyword.ServiceBusAdministrationClient
. This means there will be no msrest.exceptions.ValidationError
raised by the ServiceBusAdministrationClient
in the case of malformed input. An azure.core.exceptions.HttpResponseError
may now be raised if the server refuses the request.azure.servicebus.management
were not following uppercase convention.azure-core
version to 1.24.0.msrest
dependency.azure-common
dependency.None
was sent to set_state
instead of clearing session state (Issue #27582).Version 7.9.0a1 is our first efforts to build an Azure Service Bus client library based on a pure Python implemented AMQP stack.
This version and all future versions will require Python 3.7+. Python 3.6 is no longer supported.
ServiceBusClient
where custom_endpoint_address
and connection_verify
kwargs were not being passed through correctly. (Issue #26015)This version will be the last version to officially support Python 3.6, future versions will require Python 3.7+.
ServiceBusClient
, get_queue_receiver
, get_subscription_receiver
, get_queue_sender
, and get_topic_sender
now accept
an optional client_identifier
argument which allows for specifying a custom identifier for the respective sender or receiver. It can
be useful during debugging as Service Bus associates the id with errors and helps with easier correlation.ServiceBusReceiver
and ServiceBusSender
have an added property client_identifier
which returns the client_identifier
for the current instance.ServiceBusClient
constructor now accepts optional custom_endpoint_address
argument
which allows for specifying a custom endpoint to use when communicating with the Service Bus service,
and is useful when your network does not allow communicating to the standard Service Bus endpoint.ServiceBusClient
constructor now accepts optional connection_verify
argument
which allows for specifying the path to the custom CA_BUNDLE file of the SSL certificate which is used to authenticate
the identity of the connection endpoint.prefetch_count
of ServiceBusReceiver
is set 0 and there is no active receive call, this helps avoid receiving expired messages and incrementing delivery count of a message.ServiceBusMessageState
enum that can assume the values of active
, scheduled
or deferred
.state
property in ServiceBusReceivedMessage
.This version and all future versions will require Python 3.6+. Python 2.7 is no longer supported.
ServiceBusClient
constructors and from_connection_string
take retry_mode
as a keyword argument.ServiceBusSessionFilter
, which is the type of existing NEXT_AVAILABLE_SESSION
value.ServiceBusMessage.time_to_live
with value being datetime.timedelta
, total_seconds
should be respected (PR #21869, thanks @jyggen).ServiceBusAdministrationClient
. This feature is only available for Service Bus of Premium Tier.
create_queue
, create_topic
, update_queue
, update_topic
on ServiceBusAdministrationClient
now take a new keyword argument max_message_size_in_kilobytes
.QueueProperties
and TopicProperties
now have a new instance variable max_message_size_in_kilobytes
.ServiceBusAdministrationClient
as well as ServiceBusAdministrationClient.from_connection_string
now take keyword argument api_version
to configure the Service Bus API version. Supported service versions are "2021-05" and "2017-04".azure.servicebus.management.ApiVersion
to represent the supported Service Bus API versions.ServiceBusReceiver
can not connect to sessionful entity with session id being empty string.ServiceBusMessage.partition_key
can not parse empty string properly.ServiceBusAdministrationClient
. This feature is only available for Service Bus of Premium Tier.
create_queue
, create_topic
, update_queue
, update_topic
on ServiceBusAdministrationClient
now take a new keyword argument max_message_size_in_kilobytes
.QueueProperties
and TopicProperties
now have a new instance variable max_message_size_in_kilobytes
.ServiceBusClient
to automatically discard spawned ServiceBusSender
or ServiceBusReceiver
from its handler set when no strong reference to the sender or receiver exists anymore.azure.servicebus.AutoLockRenewer
during lock renewal.azure.servicebus.aio.AutoLockRenewer
crashes on disposal if no messages have been registered (#19642).azure.servicebus.AutoLockRenewer
only supports auto lock renewal for max_workers
amount of messages/sessions at a time (#19362).ServiceBusMessage.partition_key
, input value should be not validated against session_id
of None (PR #19233, thanks @bishnu-shb).ServiceBusMessage.time_to_live
causes OverflowError error on Ubuntu 20.04.AmqpAnnotatedProperties.creation_time
and AmqpAnnotatedProperties.absolute_expiry_time
should be calculated in the unit of milliseconds instead of seconds.New Features
azure.servicebus.amqp
.azure.servicebus.amqp.AmqpMessageHeader
and azure.servicebus.amqp.AmqpMessageProperties
for accessing amqp header and properties.Breaking Changes from 7.2.0b1
azure.servicebus.AMQPAnnotatedMessage
to azure.servicebus.amqp.AmqpAnnotatedMessage
.azure.servicebus.AMQPMessageBodyType
to azure.servicebus.amqp.AmqpMessageBodyType
.AmqpAnnotatedMessage.header
returns azure.servicebus.amqp.AmqpMessageHeader
instead of uamqp.message.MessageHeader
.AmqpAnnotatedMessage.properties
returns azure.servicebus.amqp.AmqpMessageProperties
instead of uamqp.message.MessageProperties
.raw_amqp_message
on ServiceBusMessage
and ServiceBusReceivedMessage
is now a read-only property instead of an instance variable.Bug Fixes
ServiceBusReceiver
iterator stops iteration after recovery from connection error (#18795).The preview features related to AMQPAnnotatedMessage introduced in 7.2.0b1 are not included in this version.
New Features
azure.core.credentials.AzureNamedKeyCredential
as credential for authenticating the clients.azure.core.credentials.AzureSasCredential
as credential for authenticating the clients is now GA.ServiceBusAdministrationClient.update_*
methods now accept keyword arguments to override the properties specified in the model instance.Bug Fixes
update_queue
and update_subscription
methods were mutating the properties forward_to
and forward_dead_lettered_messages_to
of the model instance when those properties are entities instead of full paths.repr
on ServiceBusMessage
and ServiceBusReceivedMessage
to show more meaningful text.Notes
New Features
azure.core.credentials.AzureSasCredential
as credential for authenticating the clients.azure.servicebus.AMQPAnnotatedMessage
is now made public and could be instantiated for sending.azure.servicebus.AMQPMessageBodyType
to represent the body type of the message message which includes:
DATA
: The body of message consists of one or more data sections and each section contains opaque binary data.SEQUENCE
: The body of message consists of one or more sequence sections and each section contains an arbitrary number of structured data elements.VALUE
: The body of message consists of one amqp-value section and the section contains a single AMQP value.body_type
on azure.servicebus.ServiceBusMessage
and azure.servicebus.ReceivedMessage
which returns azure.servicebus.AMQPMessageBodyType
.This version and all future versions will require Python 2.7 or Python 3.6+, Python 3.5 is no longer supported.
New Features
forward_to
and forward_dead_lettered_messages_to
parameters in create_queue
, update_queue
, create_subscription
, and update_subscription
methods on sync and async ServiceBusAdministrationClient
to accept entities as well, rather than only full paths. In the case that an entity is passed in, it is assumed that the entity exists within the same namespace used for constructing the ServiceBusAdministrationClient
.Bug Fixes
This version will be the last version to officially support Python 3.5, future versions will require Python 2.7 or Python 3.6+.
New Features
update_queue
, update_topic
, update_subscription
, and update_rule
on ServiceBusAdministrationClient
accept Mapping representations of QueueProperties
, TopicProperties
, SubscriptionProperties
, and RuleProperties
, respectively.send_messages
and schedule_messages
on both sync and async versions of ServiceBusSender
accept a list of or single instance of Mapping representations of ServiceBusMessage
.add_message
on ServiceBusMessageBatch
now accepts a Mapping representation of ServiceBusMessage
.BugFixes
uamqp.errors.LinkForceDetach
caused by no activity on the connection for 10 minutes will now be retried internally except for the session receiver case.uamqp.errors.AMQPConnectionError
errors with condition code amqp:unknown-error
are now categorized into ServiceBusConnectionError
instead of the general ServiceBusError
.update_*
methods on ServiceBusManagementClient
will now raise a TypeError
rather than an AttributeError
in the case of unsupported input type.BugFixes
forward_to
and forward_dead_lettered_messages_to
will no longer cause authorization errors when used in ServiceBusAdministrationClient
for queues and subscriptions (#15543).uamqp.ReceiveClient
and uamqp.ReceiveClientAsync
receive messages during connection establishment (#15555).Note: This is the GA release of the
azure-servicebus
package, rolling out the official API surface area constructed over the prior preview releases. Users migrating fromv0.50
are advised to view the migration guide.
New Features
sub_queue
and receive_mode
may now be passed in as a valid string (as defined by their respective enum type) as well as their enum form when constructing ServiceBusReceiver
.Breaking Changes
ServiceBusSender
and ServiceBusReceiver
are no longer reusable and will raise ValueError
when trying to operate on a closed handler.ReceiveMode
to ServiceBusReceiveMode
and SubQueue
to ServiceBusSubQueue
, and convert their enum values from ints to human-readable strings.DeadLetter
to DEAD_LETTER
, TransferDeadLetter
to TRANSFER_DEAD_LETTER
, PeekLock
to PEEK_LOCK
and ReceiveAndDelete
to RECEIVE_AND_DELETE
to conform to sdk guidelines going forward.send_messages
, schedule_messages
, cancel_scheduled_messages
and receive_deferred_messages
now performs a no-op rather than raising a ValueError
if provided an empty list of messages or an empty batch.ServiceBusMessage.amqp_annotated_message
has been renamed to ServiceBusMessage.raw_amqp_message
to normalize with other SDKs.MessageAlreadySettled
now inherits from ValueError
instead of ServiceBusMessageError
as it's a client-side validation.NoActiveSession
which is now replaced by OperationTimeoutError
as the client times out when trying to connect to any available session.ServiceBusMessageError
as error condition based exceptions provide comprehensive error information.MessageSettleFailed
as error condition based exceptions provide comprehensive error information.MessageSendFailed
as error condition based exceptions provide comprehensive error information.MessageContentTooLarge
to MessageSizeExceededError
to be consistent with the term defined by the service.MessageLockExpired
to MessageLockLostError
to be consistent with the term defined by the service.SessionLockExpired
to SessionLockLostError
to be consistent with the term defined by the service.MessageNotFoundError
which would be raised when the requested message was not found.MessagingEntityNotFoundError
which would be raised when a Service Bus resource cannot be found by the Service Bus service.MessagingEntityDisabledError
which would be raised when the Messaging Entity is disabled.MessagingEntityAlreadyExistsError
which would be raised when an entity with the same name exists under the same namespace.ServiceBusQuotaExceededError
which would be raised when a Service Bus resource has been exceeded while interacting with the Azure Service Bus service.ServiceBusServerBusyError
which would be raised when the Azure Service Bus service reports that it is busy in response to a client request to perform an operation.ServiceBusCommunicationError
which would be raised when there was a general communications error encountered when interacting with the Azure Service Bus service.SessionCannotBeLockedError
which would be raised when the requested session cannot be locked.ServiceBusMessage
will now raise a TypeError
when provided an invalid body type. Valid bodies are strings, bytes, and None. Lists are no longer accepted, as they simply concatenated the contents prior.receive_mode
value will now raise ValueError
instead of TypeError
in line with supporting extensible enums.ServiceBusMessage.partition_key
to a value different than session_id
on the message instance now raises ValueError
.ServiceBusClient.get_queue/topic_sender
and ServiceBusClient.get_queue/subscription_receiver
will now
raise ValueError
if the queue_name
or topic_name
does not match the EntityPath
in the connection string used to construct the ServiceBusClient
.ValueError
.RECEIVE_AND_DELETE
receive mode will raise ValueError
.session_id
, reply_to_session_id
, message_id
and partition_key
on ServiceBusMessage
longer than 128 characters will raise ValueError
.ServiceBusReceiver.get_streaming_message_iter
has been made internal for the time being to assess use patterns before committing to back-compatibility; messages may still be iterated over in equivalent fashion by iterating on the receiver itself.BugFixes
ServiceBusAdministrationClient.create_rule
by default now creates a TrueRuleFilter
rule.auto_lock_renewer
on a sessionful receiver alongside ReceiveMode.ReceiveAndDelete
will no longer fail during receipt due to failure to register the message with the renewer.New Features
timeout
parameter on the following operations:
ServiceBusSender
: send_messages
, schedule_messages
and cancel_scheduled_messages
ServiceBusReceiver
: receive_deferred_messages
, peek_messages
and renew_message_lock
ServiceBusSession
: get_state
, set_state
and renew_lock
azure.servicebus.exceptions.ServiceBusError
now inherits from azure.core.exceptions.AzureError
.parse_connection_string
method which parses a connection string into a properties bag containing its component partsauto_lock_renewer
parameter on get_queue_receiver
and get_subscription_receiver
calls to allow auto-registration of messages and sessions for auto-renewal.Breaking Changes
AutoLockRenew
to AutoLockRenewer
.ServiceBusSessionReceiver
which is now unified within class ServiceBusReceiver
.
ServiceBusClient.get_queue_session_receiver
and ServiceBusClient.get_subscription_session_receiver
.ServiceBusClient.get_queue_receiver
and ServiceBusClient.get_subscription_receiver
now take keyword parameter session_id
which must be set when getting a receiver for the sessionful entity.inner_exception
that ServiceBusError.__init__
takes is now renamed to error
.azure.servicebus.exceptions.MessageError
to azure.servicebus.exceptions.ServiceBusMessageError
azure.servicebus.exceptions.ServiceBusResourceNotFound
as azure.core.exceptions.ResourceNotFoundError
is now raised when a Service Bus
resource does not exist when using the ServiceBusAdministrationClient
.Message
to ServiceBusMessage
.ReceivedMessage
to ServiceBusReceivedMessage
.BatchMessage
to ServiceBusMessageBatch
.
add
to add_message
on the class.PeekedMessage
.ReceivedMessage
under module azure.servicebus.aio
.ServiceBusSender.create_batch
to ServiceBusSender.create_message_batch
.MessageSendFailed
, MessageSettleFailed
and MessageLockExpired
now inherit from azure.servicebus.exceptions.ServiceBusMessageError
.get_state
in ServiceBusSession
now returns bytes
instead of a string
.ServiceBusReceiver.receive_messages/get_streaming_message_iter
and
ServiceBusClient.get_<queue/subscription>_receiver
now raises ValueError if the given max_wait_time
is less than or equal to 0.ServiceBusMessage
to ServiceBusReceiver
:
ServiceBusReceiver.complete_message
instead of ServiceBusReceivedMessage.complete
to complete a message.ServiceBusReceiver.abandon_message
instead of ServiceBusReceivedMessage.abandon
to abandon a message.ServiceBusReceiver.defer_message
instead of ServiceBusReceivedMessage.defer
to defer a message.ServiceBusReceiver.dead_letter_message
instead of ServiceBusReceivedMessage.dead_letter
to dead letter a message.complete_message
, abandon_message
, defer_message
and dead_letter_message
)
and methods that use amqp management link for request like schedule_messages
, received_deferred_messages
, etc.
now raise more concrete exception other than MessageSettleFailed
and ServiceBusError
.renew_lock
method is moved from ServiceBusMessage
to ServiceBusReceiver
:
ServiceBusReceivedMessage.renew_lock
to ServiceBusReceiver.renew_message_lock
AutoLockRenewer.register
now takes ServiceBusReceiver
as a positional parameter.encoding
support from ServiceBusMessage
.ServiceBusMessage.amqp_message
has been renamed to ServiceBusMessage.amqp_annotated_message
for cross-sdk consistency.name
parameters in ServiceBusAdministrationClient
are now precisely specified ala queue_name
or rule_name
ServiceBusMessage.via_partition_key
is no longer exposed, this is pending a full implementation of transactions as it has no external use. If needed, the underlying value can still be accessed in ServiceBusMessage.amqp_annotated_message.annotations
.ServiceBusMessage.properties
has been renamed to ServiceBusMessage.application_properties
for consistency with service verbiage.ServiceBusSender
and ServiceBusReceiver
) from_connection_string
initializers have been made internal until needed. Clients should be initialized from root ServiceBusClient
.ServiceBusMessage.label
has been renamed to ServiceBusMessage.subject
.ServiceBusMessage.amqp_annotated_message
has had its type renamed from AMQPMessage
to AMQPAnnotatedMessage
AutoLockRenewer
timeout
parameter is renamed to max_lock_renew_duration
ReceiveAndDelete
mode, or configure auto-autorenewal on a ReceiveAndDelete
receiver, will raise a ValueError
.max_message_count
on ServiceBusReceiver.receive_messages
is now 1
instead of None
and will raise ValueError if the given value is less than or equal to 0.BugFixes
footer
and delivery_annotation
were not encoded into the outgoing payload.Breaking Changes
ReceiveMode
as parameter receive_mode
now throws a TypeError
instead of AttributeError
.<Entity>Descriptions
as well to reduce ambiguity in which entity was being acted on. TypeError will now be thrown on improper parameter types (non-string).AMQPMessage
(Message.amqp_message
) properties are now read-only, changes of these properties would not be reflected in the underlying message. This may be subject to change before GA.New Features
renew_lock()
now returns the UTC datetime that the lock is set to expire at.receive_deferred_messages()
can now take a single sequence number as well as a list of sequence numbers.from_connection_string
methods now support using the SharedAccessSignature
key in leiu of sharedaccesskey
and sharedaccesskeyname
, taking the string of the properly constructed token as value.Message.amqp_message
Breaking Changes
prefetch
to prefetch_count
.ReceiveSettleMode
enum to ReceiveMode
, and respectively the mode
parameter to receive_mode
.retry_total
, retry_backoff_factor
and retry_backoff_max
are now defined at the ServiceBusClient
level and inherited by senders and receivers created from it.NEXT_AVAILABLE
in azure.servicebus
module. A null session_id
will suffice.message_count
to max_message_count
as fewer messages may be present for method peek_messages()
and receive_messages()
.PeekMessage
to PeekedMessage
.get_session_state()
and set_session_state()
to get_state()
and set_state()
accordingly.description
to error_description
for method dead_letter()
.created_time
and modified_time
to created_at_utc
and modified_at_utc
within AuthorizationRule
and NamespaceProperties
.requires_preprocessing
from SqlRuleFilter
and SqlRuleAction
.namespace_type
from NamespaceProperties
.ServiceBusManagementClient
to ServiceBusAdministrationClient
send_messages
on something not a Message
, BatchMessage
, or list of Message
s, will now throw a TypeError
instead of ValueError
ServiceBusClient.close()
now closes spawned senders and receivers.queue_name
) will result in an AuthenticationErroris_anonymous_accessible
from management entities.support_ordering
from create_queue
and QueueProperties
enable_subscription_partitioning
from create_topic
and TopicProperties
get_dead_letter_[queue,subscription]_receiver()
has been removed. To connect to a dead letter queue, utilize the sub_queue
parameter of get_[queue,subscription]_receiver()
provided with a value from the SubQueue
enumServiceBusSharedKeyCredential
entity_availability_status
to availability_status
New Features
content_type
, correlation_id
, label
,
message_id
, reply_to
, reply_to_session_id
and to
. Please refer to the docstring for further information.enqueued_sequence_number
, dead_letter_error_description
,
dead_letter_reason
, dead_letter_source
, delivery_count
and expires_at_utc
. Please refer to the docstring for further information.ServiceBusSender.send_messages
.on_lock_renew_failure
as a parameter to AutoLockRenew.register
, taking a callback for when the lock is lost non-intentially (e.g. not via settling, shutdown, or autolockrenew duration completion).CorrelationFilter.properties
.parameters
and requires_preprocessing
to SqlRuleFilter
and SqlRuleAction
.get_streaming_message_iter()
such that max_wait_time
can be specified as an override.Breaking Changes
user_properties
to properties
properties
which represents the AMQP properties now becomes an internal instance variable _amqp_properties
.enqueue_sequence_number
.annotations
.header
.partition_id
on both type.settled
on both type.received_timestamp_utc
on both type.settled
on PeekMessage
.expired
on ReceivedMessage
.AutoLockRenew.sleep_time
and AutoLockRenew.renew_period
have been made internal as _sleep_time
and _renew_period
respectively, as it is not expected a user will have to interact with them.AutoLockRenew.shutdown
is now AutoLockRenew.close
to normalize with other equivalent behaviors.QueueDescription
, TopicDescription
, SubscriptionDescription
and RuleDescription
to QueueProperties
, TopicProperties
, SubscriptionProperties
, and RuleProperties
.QueueRuntimeInfo
, TopicRuntimeInfo
, and SubscriptionRuntimeInfo
to QueueRuntimeProperties
, TopicRuntimeProperties
, and SubscriptionRuntimeProperties
.queue
from create_queue
, topic
from create_topic
, subscription
from create_subscription
and rule
from create_rule
of ServiceBusManagementClient
. Added param name
to them and keyword arguments for queue properties, topic properties, subscription properties and rule properties.update_queue
and update_topic
of ServiceBusManagementClient
. This is to encourage utilizing the model class instance instead as returned from a create_*, list_* or get_* operation to ensure it is properly populated. Properties may still be modified.QueueProperties
, TopicProperties
, SubscriptionProperties
and RuleProperties
require all arguments to be present for creation. This is to protect against lack of partial updates by requiring all properties to be specified.idle_timeout
in get_<queue/subscription>_receiver()
to max_wait_time
to normalize with naming elsewhere.New Features
receive_messages()
(formerly receive()
) now supports receiving a batch of messages (max_batch_size
> 1) without the need to set prefetch
parameter during ServiceBusReceiver
initialization.BugFixes
AutoLockRenew
does not shutdown itself timely.AutoLockRenew
does not support context manager.Breaking Changes
receive()
, peek()
schedule()
and send()
to receive_messages()
, peek_messages()
, schedule_messages()
and send_messages()
to align with other service bus SDKs.receive_messages()
(formerly receive()
) no longer raises a ValueError
if max_batch_size
is less than the prefetch
parameter set during ServiceBusReceiver
initialization.New Features
azure.servicebus.management.ServiceBusManagementClient
(azure.servicebus.management.aio.ServiceBusManagementClient
for aio) to create, update, delete, list queues and get settings as well as runtime information of queues under a ServiceBus namespace.get_queue_deadletter_receiver
and get_subscription_deadletter_receiver
in ServiceBusClient
to get a ServiceBusReceiver
for the dead-letter sub-queue of the target entity.BugFixes
New Features
get_topic_sender
in ServiceBusClient
to get a ServiceBusSender
for a topic.get_subscription_receiver
in ServiceBusClient
to get a ServiceBusReceiver
for a subscription under specific topic.ServiceBusSender.schedule(messages, schedule_time_utc)
for scheduling messages.ServiceBusSender.cancel_scheduled_messages(sequence_numbers)
for scheduled messages cancellation.ServiceBusSender.send()
can now send a list of messages in one call, if they fit into a single batch. If they do not fit a ValueError
is thrown.BatchMessage.add()
and ServiceBusSender.send()
would raise MessageContentTooLarge
if the content is over-sized.ServiceBusReceiver.receive()
raises ValueError
if its param max_batch_size
is greater than param prefetch
of ServiceBusClient
.MessageError
, MessageContentTooLarge
, ServiceBusAuthenticationError
.
MessageError
: when you send a problematic message, such as an already sent message or an over-sized message.MessageContentTooLarge
: when you send an over-sized message. A subclass of ValueError
and MessageError
.ServiceBusAuthenticationError
: on failure to be authenticated by the service.InvalidHandlerState
.BugFixes
logging_enable
to True
in ServiceBusClient
.Breaking Changes
get_queue_sesison_receiver
and get_subscription_session_receiver
. Non session receivers no longer take session_id as a paramter.ServiceBusSender.send()
no longer takes a timeout parameter, as it should be redundant with retry options provided when creating the client.azure.servicebus
. Import from azure.servicebus.exceptions
instead.ServiceBusSender.schedule()
has swapped the ordering of parameters schedule_time_utc
and messages
for better consistency with send()
syntax.Version 7.0.0b1 is a preview of our efforts to create a client library that is user friendly and idiomatic to the Python ecosystem. The reasons for most of the changes in this update can be found in the Azure SDK Design Guidelines for Python. For more information, please visit https://aka.ms/azure-sdk-preview1-python.
New Features
ServiceBusClient
.
credential
: The credential object used for authentication which implements TokenCredential
interface of getting tokens.http_proxy
: A dictionary populated with proxy settings.ServiceBusClient
and/or the reference documentation for more information.reconnect
should no longer be necessary, it is now performed implicitly.open
should no longer be necessary, it is now performed implicitly.
close()
-ing is still required if a context manager is not used, to avoid leaking connections.Breaking changes
get_queue
no longer exists, utilize get_queue_sender/receiver
instead.peek
and other queue_client
functions have moved to their respective sender/receiver.fetch_next
to receive
.session
to session_id
to normalize naming when requesting a receiver against a given session.reconnect
no longer exists, and is performed implicitly if needed.open
no longer exists, and is performed implicitly if needed.debug
in ServiceBusClient
initializer to logging_enable
.service_namespace
in ServiceBusClient
initializer to fully_qualified_namespace
.azure.servicebus.exceptions.ServiceBusError
azure.servicebus.exceptions.ServiceBusConnectionError
azure.servicebus.exceptions.ServiceBusResourceNotFound
azure.servicebus.exceptions.ServiceBusAuthorizationError
azure.servicebus.exceptions.NoActiveSession
azure.servicebus.exceptions.OperationTimeoutError
azure.servicebus.exceptions.InvalidHandlerState
azure.servicebus.exceptions.AutoLockRenewTimeout
azure.servicebus.exceptions.AutoLockRenewFailed
azure.servicebus.exceptions.EventDataSendError
azure.servicebus.exceptions.MessageSendFailed
azure.servicebus.exceptions.MessageLockExpired
azure.servicebus.exceptions.MessageSettleFailed
azure.servicebus.exceptions.MessageAlreadySettled
azure.servicebus.exceptions.SessionLockExpired
create_batch
on a Sender, using add()
on the batch to add messages, in order to enforce service-side max batch sized limitations.session_id
parameter or property, as opposed to on Send
or get_sender
via session
. This is to allow sending a batch of messages destined to varied sessions.receiver.session
, to better compartmentalize functionality specific to sessions.
AutoLockRenew
against sessions, one would simply pass the inner session object, instead of the receiver itself.New Features
BugFixes
BugFixes
Breaking changes
Within the new namespace, the original HTTP-based API from version 0.21.1 remains unchanged (i.e. no additional features or bugfixes) so for those intending to only use HTTP operations - there is no additional benefit in updating at this time.
New Features
asyncio
) for send, receive and message handling.This wheel package is now built with the azure wheel extension
New Features
str
messages are now accepted in Python 3 and will be encoded in 'utf-8' (will not raise TypeError anymore)broker_properties
can now be defined as a dict, and not only a JSON str
. datetime, int, float and boolean are converted.send_topic_message_batch
operation (takes an iterable of messages)send_queue_message_batch
operation (takes an iterable of messages)Bugfixes
News
Bugfixes
Bugfixes
News
Initial release of this package, from the split of the azure
package.
See the azure
package release note for 1.0.0 for details and previous
history on Service Bus.