azure.servicebus.aio package¶
Submodules¶
azure.servicebus.aio.async_base_handler module¶
azure.servicebus.aio.async_client module¶
azure.servicebus.aio.async_message module¶
azure.servicebus.aio.async_receive_handler module¶
azure.servicebus.aio.async_send_handler module¶
azure.servicebus.aio.async_utils module¶
Module contents¶
-
class
azure.servicebus.aio.
AutoLockRenew
(loop: Optional[asyncio.base_events.BaseEventLoop] = None)[source]¶ Bases:
object
Auto lock renew.
An asynchronous AutoLockRenew handler for renewing the lock tokens of messages and/or sessions in the background.
- Parameters
loop (BaseEventLoop) – An async event loop.
Example:
-
async
close
() → None[source]¶ Cease autorenewal by cancelling any remaining open lock renewal futures.
-
register
(renewable: Union[azure.servicebus.aio._async_message.ReceivedMessage, azure.servicebus.aio._servicebus_session_async.ServiceBusSession], timeout: float = 300, on_lock_renew_failure: Optional[Callable[[Union[azure.servicebus.aio._servicebus_session_async.ServiceBusSession, azure.servicebus.aio._async_message.ReceivedMessage], Optional[Exception]], Awaitable[None]]] = None) → None[source]¶ Register a renewable entity for automatic lock renewal.
- Parameters
renewable (Union[ReceivedMessage,ServiceBusSession]) – A locked entity that needs to be renewed.
timeout (float) – A time in seconds that the lock should be maintained for. Default value is 300 (5 minutes).
on_lock_renew_failure (Optional[AsyncLockRenewFailureCallback]) – An async callback may be specified to be called when the lock is lost on the renewable being registered. Default value is None (no callback).
-
class
azure.servicebus.aio.
ReceivedMessage
(message: uamqp.message.Message, receive_mode: azure.servicebus._common.constants.ReceiveMode = <ReceiveMode.PeekLock: <ReceiverSettleMode.PeekLock: 1>>, **kwargs: Any)[source]¶ Bases:
azure.servicebus._common.message.ReceivedMessageBase
A Service Bus Message received from service side.
-
async
abandon
() → None[source]¶ Abandon the message.
This message will be returned to the queue and made available to be received again.
- Return type
- Raises
~azure.servicebus.exceptions.MessageAlreadySettled if the message has been settled.
- Raises
~azure.servicebus.exceptions.MessageLockExpired if message lock has already expired.
- Raises
~azure.servicebus.exceptions.MessageSettleFailed if message settle operation fails.
-
async
complete
() → None[source]¶ Complete the message.
This removes the message from the queue.
- Return type
- Raises
~azure.servicebus.exceptions.MessageAlreadySettled if the message has been settled.
- Raises
~azure.servicebus.exceptions.MessageLockExpired if message lock has already expired.
- Raises
~azure.servicebus.exceptions.SessionLockExpired if session lock has already expired.
- Raises
~azure.servicebus.exceptions.MessageSettleFailed if message settle operation fails.
-
async
dead_letter
(reason: Optional[str] = None, error_description: Optional[str] = None) → None[source]¶ Move the message to the Dead Letter queue.
The Dead Letter queue is a sub-queue that can be used to store messages that failed to process correctly, or otherwise require further inspection or processing. The queue can also be configured to send expired messages to the Dead Letter queue.
- Parameters
- Return type
- Raises
~azure.servicebus.exceptions.MessageAlreadySettled if the message has been settled.
- Raises
~azure.servicebus.exceptions.MessageLockExpired if message lock has already expired.
- Raises
~azure.servicebus.exceptions.MessageSettleFailed if message settle operation fails.
-
async
defer
() → None[source]¶ Defers the message.
This message will remain in the queue but must be requested specifically by its sequence number in order to be received.
- Return type
- Raises
~azure.servicebus.exceptions.MessageAlreadySettled if the message has been settled.
- Raises
~azure.servicebus.exceptions.MessageLockExpired if message lock has already expired.
- Raises
~azure.servicebus.exceptions.MessageSettleFailed if message settle operation fails.
-
async
renew_lock
() → datetime.datetime[source]¶ Renew the message lock.
This will maintain the lock on the message to ensure it is not returned to the queue to be reprocessed. In order to complete (or otherwise settle) the message, the lock must be maintained. Messages received via ReceiveAndDelete mode are not locked, and therefore cannot be renewed. This operation can also be performed as an asynchronous background task by registering the message with an azure.servicebus.aio.AutoLockRenew instance. This operation is only available for non-sessionful messages.
- Returns
The utc datetime the lock is set to expire at.
- Return type
- Raises
TypeError if the message is sessionful.
- Raises
~azure.servicebus.exceptions.MessageLockExpired is message lock has already expired.
- Raises
~azure.servicebus.exceptions.SessionLockExpired if session lock has already expired.
- Raises
~azure.servicebus.exceptions.MessageAlreadySettled is message has already been settled.
-
async
-
class
azure.servicebus.aio.
ServiceBusClient
(fully_qualified_namespace: str, credential: TokenCredential, **kwargs: Any)[source]¶ Bases:
object
The ServiceBusClient class defines a high level interface for getting ServiceBusSender and ServiceBusReceiver.
- Variables
fully_qualified_namespace (str) – The fully qualified host name for the Service Bus namespace. The namespace format is: <yournamespace>.servicebus.windows.net.
- Parameters
fully_qualified_namespace (str) – The fully qualified host name for the Service Bus namespace. The namespace format is: <yournamespace>.servicebus.windows.net.
credential (TokenCredential) – The credential object used for authentication which implements a particular interface for getting tokens. It accepts credential objects generated by the azure-identity library and objects that implement the get_token(self, *scopes) method.
- Keyword Arguments
logging_enable (bool) – Whether to output network trace logs to the logger. Default is False.
transport_type (TransportType) – The type of transport protocol that will be used for communicating with the Service Bus service. Default is TransportType.Amqp.
http_proxy (dict) – HTTP proxy settings. This must be a dictionary with the following keys: ‘proxy_hostname’ (str value) and ‘proxy_port’ (int value). Additionally the following keys may also be present: ‘username’, ‘password’.
user_agent (str) – If specified, this will be added in front of the built-in user agent string.
retry_total (int) – The total number of attempts to redo a failed operation when an error occurs. Default value is 3.
retry_backoff_factor (float) – Delta back-off internal in the unit of second between retries. Default value is 0.8.
retry_backoff_max (float) – Maximum back-off interval in the unit of second. Default value is 120.
Example:
-
async
close
() → None[source]¶ Close down the ServiceBus client. All spawned senders, receivers and underlying connection will be shutdown.
- Returns
None
-
classmethod
from_connection_string
(conn_str: str, **kwargs: Any) → azure.servicebus.aio._servicebus_client_async.ServiceBusClient[source]¶ Create a ServiceBusClient from a connection string.
- Parameters
conn_str (str) – The connection string of a Service Bus.
- Keyword Arguments
logging_enable (bool) – Whether to output network trace logs to the logger. Default is False.
transport_type (TransportType) – The type of transport protocol that will be used for communicating with the Service Bus service. Default is TransportType.Amqp.
http_proxy (dict) – HTTP proxy settings. This must be a dictionary with the following keys: ‘proxy_hostname’ (str value) and ‘proxy_port’ (int value). Additionally the following keys may also be present: ‘username’, ‘password’.
user_agent (str) – If specified, this will be added in front of the built-in user agent string.
retry_total (int) – The total number of attempts to redo a failed operation when an error occurs. Default value is 3.
retry_backoff_factor (float) – Delta back-off internal in the unit of second between retries. Default value is 0.8.
retry_backoff_max (float) – Maximum back-off interval in the unit of second. Default value is 120.
- Return type
Example:
-
get_queue_receiver
(queue_name: str, **kwargs: Any) → azure.servicebus.aio._servicebus_receiver_async.ServiceBusReceiver[source]¶ Get ServiceBusReceiver for the specific queue.
- Parameters
queue_name (str) – The path of specific Service Bus Queue the client connects to.
- Keyword Arguments
sub_queue (Optional[SubQueue]) – If specified, the subqueue this receiver will connect to. This includes the DeadLetter and TransferDeadLetter queues, holds messages that can’t be delivered to any receiver or messages that can’t be processed. The default is None, meaning connect to the primary queue.
receive_mode (ReceiveMode) – The mode with which messages will be retrieved from the entity. The two options are PeekLock and ReceiveAndDelete. Messages received with PeekLock must be settled within a given lock period before they will be removed from the queue. Messages received with ReceiveAndDelete will be immediately removed from the queue, and cannot be subsequently rejected or re-received if the client fails to process the message. The default mode is PeekLock.
max_wait_time (float) – The timeout in seconds between received messages after which the receiver will automatically stop receiving. The default value is 0, meaning no timeout.
prefetch_count (int) – The maximum number of messages to cache with each request to the service. This setting is only for advanced performance tuning. Increasing this value will improve message throughput performance but increase the chance that messages will expire while they are cached if they’re not processed fast enough. The default value is 0, meaning messages will be received from the service and processed one at a time. In the case of prefetch_count being 0, ServiceBusReceiver.receive would try to cache max_message_count (if provided) within its request to the service.
- Return type
Example:
-
get_queue_sender
(queue_name: str, **kwargs: Any) → azure.servicebus.aio._servicebus_sender_async.ServiceBusSender[source]¶ Get ServiceBusSender for the specific queue.
- Parameters
queue_name (str) – The path of specific Service Bus Queue the client connects to.
- Return type
Example:
-
get_queue_session_receiver
(queue_name: str, session_id: Optional[str] = None, **kwargs: Any) → azure.servicebus.aio._servicebus_session_receiver_async.ServiceBusSessionReceiver[source]¶ Get ServiceBusSessionReceiver for the specific queue.
- Parameters
queue_name (str) – The path of specific Service Bus Queue the client connects to.
session_id (str) – A specific session from which to receive. This must be specified for a sessionful entity, otherwise it must be None. In order to receive messages from the next available session, set this to None. The default is None.
- Keyword Arguments
receive_mode (ReceiveMode) – The mode with which messages will be retrieved from the entity. The two options are PeekLock and ReceiveAndDelete. Messages received with PeekLock must be settled within a given lock period before they will be removed from the queue. Messages received with ReceiveAndDelete will be immediately removed from the queue, and cannot be subsequently rejected or re-received if the client fails to process the message. The default mode is PeekLock.
max_wait_time (float) – The timeout in seconds between received messages after which the receiver will automatically stop receiving. The default value is 0, meaning no timeout.
prefetch_count (int) – The maximum number of messages to cache with each request to the service. This setting is only for advanced performance tuning. Increasing this value will improve message throughput performance but increase the chance that messages will expire while they are cached if they’re not processed fast enough. The default value is 0, meaning messages will be received from the service and processed one at a time. In the case of prefetch_count being 0, ServiceBusReceiver.receive would try to cache max_message_count (if provided) within its request to the service.
- Return type
Example:
-
get_subscription_receiver
(topic_name: str, subscription_name: str, **kwargs: Any) → azure.servicebus.aio._servicebus_receiver_async.ServiceBusReceiver[source]¶ Get ServiceBusReceiver for the specific subscription under the topic.
- Parameters
- Keyword Arguments
sub_queue (Optional[SubQueue]) – If specified, the subqueue this receiver will connect to. This includes the DeadLetter and TransferDeadLetter queues, holds messages that can’t be delivered to any receiver or messages that can’t be processed. The default is None, meaning connect to the primary queue.
receive_mode (ReceiveMode) – The mode with which messages will be retrieved from the entity. The two options are PeekLock and ReceiveAndDelete. Messages received with PeekLock must be settled within a given lock period before they will be removed from the subscription. Messages received with ReceiveAndDelete will be immediately removed from the subscription, and cannot be subsequently rejected or re-received if the client fails to process the message. The default mode is PeekLock.
max_wait_time (float) – The timeout in seconds between received messages after which the receiver will automatically stop receiving. The default value is 0, meaning no timeout.
prefetch_count (int) – The maximum number of messages to cache with each request to the service. This setting is only for advanced performance tuning. Increasing this value will improve message throughput performance but increase the chance that messages will expire while they are cached if they’re not processed fast enough. The default value is 0, meaning messages will be received from the service and processed one at a time. In the case of prefetch_count being 0, ServiceBusReceiver.receive would try to cache max_message_count (if provided) within its request to the service.
- Return type
Example:
-
get_subscription_session_receiver
(topic_name: str, subscription_name: str, session_id: Optional[str] = None, **kwargs: Any) → azure.servicebus.aio._servicebus_session_receiver_async.ServiceBusSessionReceiver[source]¶ Get ServiceBusReceiver for the specific subscription under the topic.
- Parameters
topic_name (str) – The name of specific Service Bus Topic the client connects to.
subscription_name (str) – The name of specific Service Bus Subscription under the given Service Bus Topic.
session_id (str) – A specific session from which to receive. This must be specified for a sessionful entity, otherwise it must be None. In order to receive messages from the next available session, set this to None. The default is None.
- Keyword Arguments
receive_mode (ReceiveMode) – The mode with which messages will be retrieved from the entity. The two options are PeekLock and ReceiveAndDelete. Messages received with PeekLock must be settled within a given lock period before they will be removed from the subscription. Messages received with ReceiveAndDelete will be immediately removed from the subscription, and cannot be subsequently rejected or re-received if the client fails to process the message. The default mode is PeekLock.
max_wait_time (float) – The timeout in seconds between received messages after which the receiver will automatically stop receiving. The default value is 0, meaning no timeout.
prefetch_count (int) – The maximum number of messages to cache with each request to the service. This setting is only for advanced performance tuning. Increasing this value will improve message throughput performance but increase the chance that messages will expire while they are cached if they’re not processed fast enough. The default value is 0, meaning messages will be received from the service and processed one at a time. In the case of prefetch_count being 0, ServiceBusReceiver.receive would try to cache max_message_count (if provided) within its request to the service.
- Return type
Example:
-
class
azure.servicebus.aio.
ServiceBusReceiver
(fully_qualified_namespace: str, credential: TokenCredential, **kwargs: Any)[source]¶ Bases:
collections.abc.AsyncIterator
,azure.servicebus.aio._base_handler_async.BaseHandler
,azure.servicebus._common.receiver_mixins.ReceiverMixin
The ServiceBusReceiver class defines a high level interface for receiving messages from the Azure Service Bus Queue or Topic Subscription.
The two primary channels for message receipt are receive() to make a single request for messages, and async for message in receiver: to continuously receive incoming messages in an ongoing fashion.
- Variables
- Parameters
fully_qualified_namespace (str) – The fully qualified host name for the Service Bus namespace. The namespace format is: <yournamespace>.servicebus.windows.net.
credential (TokenCredential) – The credential object used for authentication which implements a particular interface for getting tokens. It accepts :class: credential objects generated by the azure-identity library and objects that implement the get_token(self, *scopes) method.
- Keyword Arguments
queue_name (str) – The path of specific Service Bus Queue the client connects to.
topic_name (str) – The path of specific Service Bus Topic which contains the Subscription the client connects to.
subscription_name (str) – The path of specific Service Bus Subscription under the specified Topic the client connects to.
receive_mode (ReceiveMode) – The mode with which messages will be retrieved from the entity. The two options are PeekLock and ReceiveAndDelete. Messages received with PeekLock must be settled within a given lock period before they will be removed from the queue. Messages received with ReceiveAndDelete will be immediately removed from the queue, and cannot be subsequently abandoned or re-received if the client fails to process the message. The default mode is PeekLock.
max_wait_time (float) – The timeout in seconds between received messages after which the receiver will automatically shutdown. The default value is 0, meaning no timeout.
logging_enable (bool) – Whether to output network trace logs to the logger. Default is False.
transport_type (TransportType) – The type of transport protocol that will be used for communicating with the Service Bus service. Default is TransportType.Amqp.
http_proxy (dict) – HTTP proxy settings. This must be a dictionary with the following keys: ‘proxy_hostname’ (str value) and ‘proxy_port’ (int value). Additionally the following keys may also be present: ‘username’, ‘password’.
user_agent (str) – If specified, this will be added in front of the built-in user agent string.
prefetch_count (int) – The maximum number of messages to cache with each request to the service. This setting is only for advanced performance tuning. Increasing this value will improve message throughput performance but increase the chance that messages will expire while they are cached if they’re not processed fast enough. The default value is 0, meaning messages will be received from the service and processed one at a time. In the case of prefetch_count being 0, ServiceBusReceiver.receive would try to cache max_message_count (if provided) within its request to the service.
Example:
-
async
close
() → None[source]¶ Close down the handler connection.
If the handler has already closed, this operation will do nothing. An optional exception can be passed in to indicate that the handler was shutdown due to error.
- Return type
-
classmethod
from_connection_string
(conn_str: str, **kwargs: Any) → azure.servicebus.aio._servicebus_receiver_async.ServiceBusReceiver[source]¶ Create a ServiceBusReceiver from a connection string.
- Parameters
conn_str (str) – The connection string of a Service Bus.
- Keyword Arguments
queue_name (str) – The path of specific Service Bus Queue the client connects to.
topic_name (str) – The path of specific Service Bus Topic which contains the Subscription the client connects to.
subscription_name (str) – The path of specific Service Bus Subscription under the specified Topic the client connects to.
receive_mode (ReceiveMode) – The mode with which messages will be retrieved from the entity. The two options are PeekLock and ReceiveAndDelete. Messages received with PeekLock must be settled within a given lock period before they will be removed from the queue. Messages received with ReceiveAndDelete will be immediately removed from the queue, and cannot be subsequently abandoned or re-received if the client fails to process the message. The default mode is PeekLock.
max_wait_time (float) – The timeout in seconds between received messages after which the receiver will automatically shutdown. The default value is 0, meaning no timeout.
logging_enable (bool) – Whether to output network trace logs to the logger. Default is False.
transport_type (TransportType) – The type of transport protocol that will be used for communicating with the Service Bus service. Default is TransportType.Amqp.
http_proxy (dict) – HTTP proxy settings. This must be a dictionary with the following keys: ‘proxy_hostname’ (str value) and ‘proxy_port’ (int value). Additionally the following keys may also be present: ‘username’, ‘password’.
user_agent (str) – If specified, this will be added in front of the built-in user agent string.
prefetch_count (int) – The maximum number of messages to cache with each request to the service. This setting is only for advanced performance tuning. Increasing this value will improve message throughput performance but increase the chance that messages will expire while they are cached if they’re not processed fast enough. The default value is 0, meaning messages will be received from the service and processed one at a time. In the case of prefetch_count being 0, ServiceBusReceiver.receive would try to cache max_message_count (if provided) within its request to the service.
- Return type
- Raises
ServiceBusAuthenticationError – Indicates an issue in token/identity validity.
ServiceBusAuthorizationError – Indicates an access/rights related failure.
Example:
-
get_streaming_message_iter
(max_wait_time: float = None) → AsyncIterator[azure.servicebus.aio._async_message.ReceivedMessage][source]¶ Receive messages from an iterator indefinitely, or if a max_wait_time is specified, until such a timeout occurs.
- Parameters
max_wait_time (float) –
Maximum time to wait in seconds for the next message to arrive. If no messages arrive, and no timeout is specified, this call will not return until the connection is closed. If specified, and no messages arrive for the timeout period, the iterator will stop.
:rtype AsyncIterator[ReceivedMessage]
Example:
-
async
peek_messages
(max_message_count=1, sequence_number=0)[source]¶ Browse messages currently pending in the queue.
Peeked messages are not removed from queue, nor are they locked. They cannot be completed, deferred or dead-lettered.
- Parameters
- Return type
Example:
-
async
receive_deferred_messages
(sequence_numbers: Union[int, List[int]]) → List[azure.servicebus.aio._async_message.ReceivedMessage][source]¶ Receive messages that have previously been deferred.
When receiving deferred messages from a partitioned entity, all of the supplied sequence numbers must be messages from the same partition.
- Parameters
list[int]] sequence_numbers (Union[int,) – A list of the sequence numbers of messages that have been deferred.
- Return type
Example:
-
async
receive_messages
(max_message_count: Optional[int] = None, max_wait_time: Optional[float] = None) → List[azure.servicebus.aio._async_message.ReceivedMessage][source]¶ Receive a batch of messages at once.
This approach is optimal if you wish to process multiple messages simultaneously, or perform an ad-hoc receive as a single call.
Note that the number of messages retrieved in a single batch will be dependent on whether prefetch_count was set for the receiver. If prefetch_count is not set for the receiver, the receiver would try to cache max_message_count (if provided) messages within the request to the service.
This call will prioritize returning quickly over meeting a specified batch size, and so will return as soon as at least one message is received and there is a gap in incoming messages regardless of the specified batch size.
- Parameters
max_message_count (int) – Maximum number of messages in the batch. Actual number returned will depend on prefetch_count size and incoming stream rate.
max_wait_time (float) – Maximum time to wait in seconds for the first message to arrive. If no messages arrive, and no timeout is specified, this call will not return until the connection is closed. If specified, and no messages arrive within the timeout period, an empty list will be returned.
- Return type
Example:
-
class
azure.servicebus.aio.
ServiceBusSender
(fully_qualified_namespace: str, credential: TokenCredential, **kwargs: Any)[source]¶ Bases:
azure.servicebus.aio._base_handler_async.BaseHandler
,azure.servicebus._servicebus_sender.SenderMixin
The ServiceBusSender class defines a high level interface for sending messages to the Azure Service Bus Queue or Topic.
- Variables
- Parameters
fully_qualified_namespace (str) – The fully qualified host name for the Service Bus namespace. The namespace format is: <yournamespace>.servicebus.windows.net.
credential (TokenCredential) – The credential object used for authentication which implements a particular interface for getting tokens. It accepts :class: credential objects generated by the azure-identity library and objects that implement the get_token(self, *scopes) method.
- Keyword Arguments
queue_name (str) – The path of specific Service Bus Queue the client connects to. Only one of queue_name or topic_name can be provided.
topic_name (str) – The path of specific Service Bus Topic the client connects to. Only one of queue_name or topic_name can be provided.
logging_enable (bool) – Whether to output network trace logs to the logger. Default is False.
transport_type (TransportType) – The type of transport protocol that will be used for communicating with the Service Bus service. Default is TransportType.Amqp.
http_proxy (dict) – HTTP proxy settings. This must be a dictionary with the following keys: ‘proxy_hostname’ (str value) and ‘proxy_port’ (int value). Additionally the following keys may also be present: ‘username’, ‘password’.
user_agent (str) – If specified, this will be added in front of the built-in user agent string.
Example:
-
async
cancel_scheduled_messages
(sequence_numbers: Union[int, List[int]]) → None[source]¶ Cancel one or more messages that have previously been scheduled and are still pending.
- Parameters
sequence_numbers (int or list[int]) – The sequence numbers of the scheduled messages.
- Return type
- Raises
~azure.servicebus.exceptions.ServiceBusError if messages cancellation failed due to message already cancelled or enqueued.
Example:
-
async
create_batch
(max_size_in_bytes: Optional[int] = None) → azure.servicebus._common.message.BatchMessage[source]¶ Create a BatchMessage object with the max size of all content being constrained by max_size_in_bytes. The max_size should be no greater than the max allowed message size defined by the service.
- Parameters
max_size_in_bytes (int) – The maximum size of bytes data that a BatchMessage object can hold. By default, the value is determined by your Service Bus tier.
- Return type
Example:
-
classmethod
from_connection_string
(conn_str: str, **kwargs: Any) → azure.servicebus.aio._servicebus_sender_async.ServiceBusSender[source]¶ Create a ServiceBusSender from a connection string.
- Parameters
conn_str (str) – The connection string of a Service Bus.
- Keyword Arguments
queue_name (str) – The path of specific Service Bus Queue the client connects to.
topic_name (str) – The path of specific Service Bus Topic the client connects to.
logging_enable (bool) – Whether to output network trace logs to the logger. Default is False.
transport_type (TransportType) – The type of transport protocol that will be used for communicating with the Service Bus service. Default is TransportType.Amqp.
http_proxy (dict) – HTTP proxy settings. This must be a dictionary with the following keys: ‘proxy_hostname’ (str value) and ‘proxy_port’ (int value). Additionally the following keys may also be present: ‘username’, ‘password’.
user_agent (str) – If specified, this will be added in front of the built-in user agent string.
- Return type
- Raises
ServiceBusAuthenticationError – Indicates an issue in token/identity validity.
ServiceBusAuthorizationError – Indicates an access/rights related failure.
Example:
-
async
schedule_messages
(messages: Union[Message, List[Message]], schedule_time_utc: datetime.datetime) → List[int][source]¶ Send Message or multiple Messages to be enqueued at a specific time by the service. Returns a list of the sequence numbers of the enqueued messages. :param messages: The message or list of messages to schedule. :type messages: ~azure.servicebus.Message or list[~azure.servicebus.Message] :param schedule_time_utc: The utc date and time to enqueue the messages. :type schedule_time_utc: ~datetime.datetime :rtype: list[int]
Example:
-
async
send_messages
(message: Union[azure.servicebus._common.message.Message, azure.servicebus._common.message.BatchMessage, List[azure.servicebus._common.message.Message]]) → None[source]¶ Sends message and blocks until acknowledgement is received or operation times out.
If a list of messages was provided, attempts to send them as a single batch, throwing a ValueError if they cannot fit in a single batch.
- Parameters
message (Message or BatchMessage or list[Message]) – The ServiceBus message to be sent.
- Return type
- Raises
- class
~azure.servicebus.exceptions.OperationTimeoutError if sending times out.
- class
~azure.servicebus.exceptions.MessageContentTooLarge if the size of the message is over service bus frame size limit.
- class
~azure.servicebus.exceptions.MessageSendFailed if the message fails to send
- class
~azure.servicebus.exceptions.ServiceBusError when other errors happen such as connection error, authentication error, and any unexpected errors. It’s also the top-level root class of above errors.
Example:
-
class
azure.servicebus.aio.
ServiceBusSession
(session_id: str, receiver: Union[ServiceBusSessionReceiver, ServiceBusSessionReceiverAsync], encoding: str = 'UTF-8')[source]¶ Bases:
azure.servicebus._servicebus_session.BaseSession
The ServiceBusSession is used for manage session states and lock renewal.
Please use the instance variable `session` on the ServiceBusReceiver to get the corresponding ServiceBusSession object linked with the receiver instead of instantiating a ServiceBusSession object directly.
Example:
-
async
get_state
() → str[source]¶ Get the session state.
Returns None if no state has been set.
- Return type
Example:
-
async
renew_lock
() → datetime.datetime[source]¶ Renew the session lock.
This operation must be performed periodically in order to retain a lock on the session to continue message processing.
Once the lock is lost the connection will be closed; an expired lock cannot be renewed.
This operation can also be performed as a threaded background task by registering the session with an azure.servicebus.aio.AutoLockRenew instance.
- Returns
The utc datetime the lock is set to expire at.
- Return type
datetime
Example:
-
async
-
class
azure.servicebus.aio.
ServiceBusSessionReceiver
(fully_qualified_namespace: str, credential: TokenCredential, **kwargs: Any)[source]¶ Bases:
azure.servicebus.aio._servicebus_receiver_async.ServiceBusReceiver
,azure.servicebus._common.receiver_mixins.SessionReceiverMixin
The ServiceBusSessionReceiver class defines a high level interface for receiving messages from the Azure Service Bus Queue or Topic Subscription while utilizing a session for FIFO and ownership semantics.
The two primary channels for message receipt are receive() to make a single request for messages, and async for message in receiver: to continuously receive incoming messages in an ongoing fashion.
- Variables
- Parameters
fully_qualified_namespace (str) – The fully qualified host name for the Service Bus namespace. The namespace format is: <yournamespace>.servicebus.windows.net.
credential (TokenCredential) – The credential object used for authentication which implements a particular interface for getting tokens. It accepts :class: credential objects generated by the azure-identity library and objects that implement the get_token(self, *scopes) method.
- Keyword Arguments
queue_name (str) – The path of specific Service Bus Queue the client connects to.
topic_name (str) – The path of specific Service Bus Topic which contains the Subscription the client connects to.
subscription_name (str) – The path of specific Service Bus Subscription under the specified Topic the client connects to.
receive_mode (ReceiveMode) – The mode with which messages will be retrieved from the entity. The two options are PeekLock and ReceiveAndDelete. Messages received with PeekLock must be settled within a given lock period before they will be removed from the queue. Messages received with ReceiveAndDelete will be immediately removed from the queue, and cannot be subsequently abandoned or re-received if the client fails to process the message. The default mode is PeekLock.
session_id (str) – A specific session from which to receive. This must be specified for a sessionful entity, otherwise it must be None. In order to receive messages from the next available session, set this to None. The default is None.
max_wait_time (float) – The timeout in seconds between received messages after which the receiver will automatically shutdown. The default value is 0, meaning no timeout.
logging_enable (bool) – Whether to output network trace logs to the logger. Default is False.
transport_type (TransportType) – The type of transport protocol that will be used for communicating with the Service Bus service. Default is TransportType.Amqp.
http_proxy (dict) – HTTP proxy settings. This must be a dictionary with the following keys: ‘proxy_hostname’ (str value) and ‘proxy_port’ (int value). Additionally the following keys may also be present: ‘username’, ‘password’.
user_agent (str) – If specified, this will be added in front of the built-in user agent string.
prefetch_count (int) – The maximum number of messages to cache with each request to the service. This setting is only for advanced performance tuning. Increasing this value will improve message throughput performance but increase the chance that messages will expire while they are cached if they’re not processed fast enough. The default value is 0, meaning messages will be received from the service and processed one at a time. In the case of prefetch_count being 0, ServiceBusReceiver.receive would try to cache max_message_count (if provided) within its request to the service.
Example:
-
classmethod
from_connection_string
(conn_str: str, **kwargs: Any) → azure.servicebus.aio._servicebus_session_receiver_async.ServiceBusSessionReceiver[source]¶ Create a ServiceBusSessionReceiver from a connection string.
- Parameters
conn_str (str) – The connection string of a Service Bus.
- Keyword Arguments
queue_name (str) – The path of specific Service Bus Queue the client connects to.
topic_name (str) – The path of specific Service Bus Topic which contains the Subscription the client connects to.
subscription_name (str) – The path of specific Service Bus Subscription under the specified Topic the client connects to.
receive_mode (ReceiveMode) – The mode with which messages will be retrieved from the entity. The two options are PeekLock and ReceiveAndDelete. Messages received with PeekLock must be settled within a given lock period before they will be removed from the queue. Messages received with ReceiveAndDelete will be immediately removed from the queue, and cannot be subsequently abandoned or re-received if the client fails to process the message. The default mode is PeekLock.
session_id (str) – A specific session from which to receive. This must be specified for a sessionful entity, otherwise it must be None. In order to receive messages from the next available session, set this to None. The default is None.
max_wait_time (float) – The timeout in seconds between received messages after which the receiver will automatically shutdown. The default value is 0, meaning no timeout.
logging_enable (bool) – Whether to output network trace logs to the logger. Default is False.
transport_type (TransportType) – The type of transport protocol that will be used for communicating with the Service Bus service. Default is TransportType.Amqp.
http_proxy (dict) – HTTP proxy settings. This must be a dictionary with the following keys: ‘proxy_hostname’ (str value) and ‘proxy_port’ (int value). Additionally the following keys may also be present: ‘username’, ‘password’.
user_agent (str) – If specified, this will be added in front of the built-in user agent string.
prefetch_count (int) – The maximum number of messages to cache with each request to the service. This setting is only for advanced performance tuning. Increasing this value will improve message throughput performance but increase the chance that messages will expire while they are cached if they’re not processed fast enough. The default value is 0, meaning messages will be received from the service and processed one at a time. In the case of prefetch_count being 0, ServiceBusReceiver.receive would try to cache max_message_count (if provided) within its request to the service.
- Return type
- Raises
ServiceBusAuthenticationError – Indicates an issue in token/identity validity.
ServiceBusAuthorizationError – Indicates an access/rights related failure.
Example:
-
property
session
¶ Get the ServiceBusSession object linked with the receiver. Session is only available to session-enabled entities.
- Return type
Example: