azure.servicebus.Message(body, **kwargs)[source]¶A Service Bus Message.
Parametersbody (str or bytes) – The data to send in a single message.
Keyword Argumentsproperties (dict) – The user defined properties on the message.
session_id (str) – The session identifier of the message for a sessionful entity.
message_id (str) – The id to identify the message.
scheduled_enqueue_time_utc (datetime.datetime) – The utc scheduled enqueue time to the message.
time_to_live (datetime.timedelta) – The life duration of a message.
content_type (str) – The content type descriptor.
correlation_id (str) – The correlation identifier.
label (str) – The application specific label.
partition_key (str) – The partition key for sending a message to a partitioned entity.
via_partition_key (str) – The partition key for sending a message into an entity via a partitioned transfer queue.
to (str) – The to address used for auto_forward chaining scenarios.
reply_to (str) – The address of an entity to send replies to.
reply_to_session_id (str) – The session identifier augmenting the reply_to address.
encoding (str) – The encoding for string data. Default is UTF-8.
Example:
Sending a message with additional properties¶message = Message( "Hello World!!", session_id="MySessionID", partition_key="UsingSpecificPartition", user_properties={'data': 'custom_data'}, time_to_live=datetime.timedelta(seconds=30), label='MyLabel' )property
body¶The body of the Message.
Return typepropertycontent_type¶The content type descriptor.
Optionally describes the payload of the message, with a descriptor following the format of RFC2045, Section 5, for example “application/json”.
Return typepropertycorrelation_id¶The correlation identifier.
Allows an application to specify a context for the message for the purposes of correlation, for example reflecting the MessageId of a message that is being replied to.
See Message Routing and Correlation in https://docs.microsoft.com/azure/service-bus-messaging/service-bus-messages-payloads?#message-routing-and-correlation.
Return typepropertylabel¶The application specific label.
This property enables the application to indicate the purpose of the message to the receiver in a standardized fashion, similar to an email subject line.
Return typepropertymessage_id¶The id to identify the message.
The message identifier is an application-defined value that uniquely identifies the message and its payload. The identifier is a free-form string and can reflect a GUID or an identifier derived from the application context. If enabled, the duplicate detection (see https://docs.microsoft.com/azure/service-bus-messaging/duplicate-detection)
feature identifies and removes second and further submissions of messages with the same message id.
Return typepropertypartition_key¶The partition key for sending a message to a partitioned entity.
Setting this value enables assigning related messages to the same internal partition, so that submission sequence order is correctly recorded. The partition is chosen by a hash function over this value and cannot be chosen directly.
See Partitioned queues and topics in https://docs.microsoft.com/azure/service-bus-messaging/service-bus-partitioning.
Return typepropertyproperties¶The user defined properties on the message.
Return typepropertyreply_to¶The address of an entity to send replies to.
This optional and application-defined value is a standard way to express a reply path to the receiver of the message. When a sender expects a reply, it sets the value to the absolute or relative path of the queue or topic it expects the reply to be sent to.
See Message Routing and Correlation in https://docs.microsoft.com/azure/service-bus-messaging/service-bus-messages-payloads?#message-routing-and-correlation.
Return typepropertyreply_to_session_id¶The session identifier augmenting the reply_to address.
This value augments the reply_to information and specifies which session id should be set for the reply when sent to the reply entity.
See Message Routing and Correlation in https://docs.microsoft.com/azure/service-bus-messaging/service-bus-messages-payloads?#message-routing-and-correlation.
Return typepropertyscheduled_enqueue_time_utc¶The utc scheduled enqueue time to the message.
This property can be used for scheduling when sending a message through ServiceBusSender.send method. If cancelling scheduled messages is required, you should use the ServiceBusSender.schedule method, which returns sequence numbers that can be used for future cancellation. scheduled_enqueue_time_utc is None if not set.
Return typepropertysession_id¶The session identifier of the message for a sessionful entity.
For sessionful entities, this application-defined value specifies the session affiliation of the message. Messages with the same session identifier are subject to summary locking and enable exact in-order processing and demultiplexing. For non-sessionful entities, this value is ignored.
See Message Sessions in https://docs.microsoft.com/azure/service-bus-messaging/message-sessions.
Return typepropertytime_to_live¶The life duration of a message.
This value is the relative duration after which the message expires, starting from the instant the message has been accepted and stored by the broker, as captured in enqueued_time_utc. When not set explicitly, the assumed value is the DefaultTimeToLive for the respective queue or topic. A message-level time-to-live value cannot be longer than the entity’s time-to-live setting and it is silently adjusted if it does.
See Expiration in https://docs.microsoft.com/azure/service-bus-messaging/message-expiration
Return typepropertyto¶The to address.
This property is reserved for future use in routing scenarios and presently ignored by the broker itself. Applications can use this value in rule-driven auto-forward chaining scenarios to indicate the intended logical destination of the message.
See https://docs.microsoft.com/azure/service-bus-messaging/service-bus-auto-forwarding for more details.
Return typepropertyvia_partition_key¶The partition key for sending a message into an entity via a partitioned transfer queue.
If a message is sent via a transfer queue in the scope of a transaction, this value selects the transfer queue partition: This is functionally equivalent to partition_key and ensures that messages are kept together and in order as they are transferred.
See Transfers and Send Via in https://docs.microsoft.com/azure/service-bus-messaging/service-bus-transactions#transfers-and-send-via.
Return typeclassazure.servicebus.BatchMessage(max_size_in_bytes: Optional[int] = None)[source]¶A batch of messages.
Sending messages in a batch is more performant than sending individual message. BatchMessage helps you create the maximum allowed size batch of Message to improve sending performance.
Use the add method to add messages until the maximum batch size limit in bytes has been reached - at which point a ValueError will be raised.
Please use the create_batch method of ServiceBusSender to create a BatchMessage object instead of instantiating a BatchMessage object directly.
Variablesmax_size_in_bytes (int) – The maximum size of bytes data that a BatchMessage object can hold.
message (BatchMessage) – Internal AMQP BatchMessage object.
max_size_in_bytes (int) – The maximum size of bytes data that a BatchMessage object can hold.
add(message: azure.servicebus._common.message.Message) → None[source]¶Try to add a single Message to the batch.
The total size of an added message is the sum of its body, properties, etc. If this added size results in the batch exceeding the maximum batch size, a ValueError will be raised.
Parametersmessage (Message) – The Message to be added to the batch.
Return typeRaises class~azure.servicebus.exceptions.MessageContentTooLarge, when exceeding the size limit.
propertysize_in_bytes¶The combined size of the events in the batch, in bytes.
Return typeclassazure.servicebus.PeekMessage(message)[source]¶A preview message.
This message is still on the queue, and unlocked. A peeked message cannot be completed, abandoned, dead-lettered or deferred. It has no lock token or expiry.
propertybody¶The body of the Message.
Return typepropertycontent_type¶The content type descriptor.
Optionally describes the payload of the message, with a descriptor following the format of RFC2045, Section 5, for example “application/json”.
Return typepropertycorrelation_id¶The correlation identifier.
Allows an application to specify a context for the message for the purposes of correlation, for example reflecting the MessageId of a message that is being replied to.
See Message Routing and Correlation in https://docs.microsoft.com/azure/service-bus-messaging/service-bus-messages-payloads?#message-routing-and-correlation.
Return typepropertydead_letter_error_description¶Dead letter error description, when the message is received from a deadletter subqueue of an entity.
Return typepropertydead_letter_reason¶Dead letter reason, when the message is received from a deadletter subqueue of an entity.
Return typepropertydead_letter_source¶The name of the queue or subscription that this message was enqueued on, before it was deadlettered. This property is only set in messages that have been dead-lettered and subsequently auto-forwarded from the dead-letter queue to another entity. Indicates the entity in which the message was dead-lettered.
Return typepropertydelivery_count¶Number of deliveries that have been attempted for this message. The count is incremented when a message lock expires or the message is explicitly abandoned by the receiver.
Return typepropertyenqueued_sequence_number¶For messages that have been auto-forwarded, this property reflects the sequence number that had first been assigned to the message at its original point of submission.
Return typepropertyenqueued_time_utc¶The UTC datetime at which the message has been accepted and stored in the entity.
Return typepropertyexpires_at_utc¶The UTC datetime at which the message is marked for removal and no longer available for retrieval from the entity due to expiration. Expiry is controlled by the Message.time_to_live property. This property is computed from Message.enqueued_time_utc + Message.time_to_live.
Return typepropertylabel¶The application specific label.
This property enables the application to indicate the purpose of the message to the receiver in a standardized fashion, similar to an email subject line.
Return typepropertymessage_id¶The id to identify the message.
The message identifier is an application-defined value that uniquely identifies the message and its payload. The identifier is a free-form string and can reflect a GUID or an identifier derived from the application context. If enabled, the duplicate detection (see https://docs.microsoft.com/azure/service-bus-messaging/duplicate-detection)
feature identifies and removes second and further submissions of messages with the same message id.
Return typepropertypartition_key¶The partition key for sending a message to a partitioned entity.
Setting this value enables assigning related messages to the same internal partition, so that submission sequence order is correctly recorded. The partition is chosen by a hash function over this value and cannot be chosen directly.
See Partitioned queues and topics in https://docs.microsoft.com/azure/service-bus-messaging/service-bus-partitioning.
Return typepropertyproperties¶The user defined properties on the message.
Return typepropertyreply_to¶The address of an entity to send replies to.
This optional and application-defined value is a standard way to express a reply path to the receiver of the message. When a sender expects a reply, it sets the value to the absolute or relative path of the queue or topic it expects the reply to be sent to.
See Message Routing and Correlation in https://docs.microsoft.com/azure/service-bus-messaging/service-bus-messages-payloads?#message-routing-and-correlation.
Return typepropertyreply_to_session_id¶The session identifier augmenting the reply_to address.
This value augments the reply_to information and specifies which session id should be set for the reply when sent to the reply entity.
See Message Routing and Correlation in https://docs.microsoft.com/azure/service-bus-messaging/service-bus-messages-payloads?#message-routing-and-correlation.
Return typepropertyscheduled_enqueue_time_utc¶The utc scheduled enqueue time to the message.
This property can be used for scheduling when sending a message through ServiceBusSender.send method. If cancelling scheduled messages is required, you should use the ServiceBusSender.schedule method, which returns sequence numbers that can be used for future cancellation. scheduled_enqueue_time_utc is None if not set.
Return typepropertysequence_number¶The unique number assigned to a message by Service Bus. The sequence number is a unique 64-bit integer assigned to a message as it is accepted and stored by the broker and functions as its true identifier. For partitioned entities, the topmost 16 bits reflect the partition identifier. Sequence numbers monotonically increase. They roll over to 0 when the 48-64 bit range is exhausted.
Return typepropertysession_id¶The session identifier of the message for a sessionful entity.
For sessionful entities, this application-defined value specifies the session affiliation of the message. Messages with the same session identifier are subject to summary locking and enable exact in-order processing and demultiplexing. For non-sessionful entities, this value is ignored.
See Message Sessions in https://docs.microsoft.com/azure/service-bus-messaging/message-sessions.
Return typepropertytime_to_live¶The life duration of a message.
This value is the relative duration after which the message expires, starting from the instant the message has been accepted and stored by the broker, as captured in enqueued_time_utc. When not set explicitly, the assumed value is the DefaultTimeToLive for the respective queue or topic. A message-level time-to-live value cannot be longer than the entity’s time-to-live setting and it is silently adjusted if it does.
See Expiration in https://docs.microsoft.com/azure/service-bus-messaging/message-expiration
Return typepropertyto¶The to address.
This property is reserved for future use in routing scenarios and presently ignored by the broker itself. Applications can use this value in rule-driven auto-forward chaining scenarios to indicate the intended logical destination of the message.
See https://docs.microsoft.com/azure/service-bus-messaging/service-bus-auto-forwarding for more details.
Return typepropertyvia_partition_key¶The partition key for sending a message into an entity via a partitioned transfer queue.
If a message is sent via a transfer queue in the scope of a transaction, this value selects the transfer queue partition: This is functionally equivalent to partition_key and ensures that messages are kept together and in order as they are transferred.
See Transfers and Send Via in https://docs.microsoft.com/azure/service-bus-messaging/service-bus-transactions#transfers-and-send-via.
Return typeclassazure.servicebus.ReceivedMessage(message, mode=<ReceiveSettleMode.PeekLock: <ReceiverSettleMode.PeekLock: 1>>, **kwargs)[source]¶ abandon() → None[source]¶Abandon the message.
This message will be returned to the queue and made available to be received again.
Return typeRaises~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.
Example:
Abandoning a received message to return it immediately to the queue.¶messages = servicebus_receiver.receive_messages(max_wait_time=5) for message in messages: message.abandon()
complete() → None[source]¶Complete the message.
This removes the message from the queue.
Return typeRaises~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.
Example:
Completing a received message to remove it from the queue.¶with servicebus_receiver: messages = servicebus_receiver.receive_messages(max_wait_time=5) for message in messages: print(str(message)) message.complete()
dead_letter(reason: Optional[str] = None, 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.
Parametersreason (str) – The reason for dead-lettering the message.
description (str) – The detailed description for dead-lettering the message.
~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.
Example:
Dead letter a message to remove it from the queue by sending it to the dead letter subqueue, and receiving it from there.¶with servicebus_client.get_queue_receiver(queue_name) as servicebus_receiver: messages = servicebus_receiver.receive_messages(max_wait_time=5) for message in messages: message.dead_letter(reason='reason for dead lettering', description='description for dead lettering') with servicebus_client.get_queue_deadletter_receiver(queue_name) as servicebus_deadletter_receiver: messages = servicebus_deadletter_receiver.receive_messages(max_wait_time=5) for message in messages: message.complete()
defer() → None[source]¶Defer the message.
This message will remain in the queue but must be requested specifically by its sequence number in order to be received.
Return typeRaises~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.
Example:
Deferring a received message sets it aside such that it can only be received by calling receive_deffered_messages with its sequence number¶with servicebus_receiver: deferred_sequenced_numbers = [] messages = servicebus_receiver.receive_messages(max_wait_time=5) for message in messages: deferred_sequenced_numbers.append(message.sequence_number) print(str(message)) message.defer() received_deferred_msg = servicebus_receiver.receive_deferred_messages( sequence_numbers=deferred_sequenced_numbers ) for msg in received_deferred_msg: msg.complete()
renew_lock() → None[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, and cannot already have expired; an expired lock cannot be renewed.
Messages received via ReceiveAndDelete mode are not locked, and therefore cannot be renewed. This operation is only available for non-sessionful messages as well.
Lock renewal can be performed as a background task by registering the message with an azure.servicebus.AutoLockRenew instance.
Return typeRaisesTypeError if the message is sessionful.
Raises~azure.servicebus.exceptions.MessageLockExpired is message lock has already expired.
Raises~azure.servicebus.exceptions.MessageAlreadySettled is message has already been settled.
propertybody¶The body of the Message.
Return typepropertycontent_type¶The content type descriptor.
Optionally describes the payload of the message, with a descriptor following the format of RFC2045, Section 5, for example “application/json”.
Return typepropertycorrelation_id¶The correlation identifier.
Allows an application to specify a context for the message for the purposes of correlation, for example reflecting the MessageId of a message that is being replied to.
See Message Routing and Correlation in https://docs.microsoft.com/azure/service-bus-messaging/service-bus-messages-payloads?#message-routing-and-correlation.
Return typepropertydead_letter_error_description¶Dead letter error description, when the message is received from a deadletter subqueue of an entity.
Return typepropertydead_letter_reason¶Dead letter reason, when the message is received from a deadletter subqueue of an entity.
Return typepropertydead_letter_source¶The name of the queue or subscription that this message was enqueued on, before it was deadlettered. This property is only set in messages that have been dead-lettered and subsequently auto-forwarded from the dead-letter queue to another entity. Indicates the entity in which the message was dead-lettered.
Return typepropertydelivery_count¶Number of deliveries that have been attempted for this message. The count is incremented when a message lock expires or the message is explicitly abandoned by the receiver.
Return typepropertyenqueued_sequence_number¶For messages that have been auto-forwarded, this property reflects the sequence number that had first been assigned to the message at its original point of submission.
Return typepropertyenqueued_time_utc¶The UTC datetime at which the message has been accepted and stored in the entity.
Return typepropertyexpires_at_utc¶The UTC datetime at which the message is marked for removal and no longer available for retrieval from the entity due to expiration. Expiry is controlled by the Message.time_to_live property. This property is computed from Message.enqueued_time_utc + Message.time_to_live.
Return typepropertylabel¶The application specific label.
This property enables the application to indicate the purpose of the message to the receiver in a standardized fashion, similar to an email subject line.
Return typepropertylock_token¶The lock token for the current message serving as a reference to the lock that is being held by the broker in PeekLock mode.
Return typepropertylocked_until_utc¶The UTC datetime until which the message will be locked in the queue/subscription. When the lock expires, delivery count of hte message is incremented and the message is again available for retrieval.
Return typepropertymessage_id¶The id to identify the message.
The message identifier is an application-defined value that uniquely identifies the message and its payload. The identifier is a free-form string and can reflect a GUID or an identifier derived from the application context. If enabled, the duplicate detection (see https://docs.microsoft.com/azure/service-bus-messaging/duplicate-detection)
feature identifies and removes second and further submissions of messages with the same message id.
Return typepropertypartition_key¶The partition key for sending a message to a partitioned entity.
Setting this value enables assigning related messages to the same internal partition, so that submission sequence order is correctly recorded. The partition is chosen by a hash function over this value and cannot be chosen directly.
See Partitioned queues and topics in https://docs.microsoft.com/azure/service-bus-messaging/service-bus-partitioning.
Return typepropertyproperties¶The user defined properties on the message.
Return typepropertyreply_to¶The address of an entity to send replies to.
This optional and application-defined value is a standard way to express a reply path to the receiver of the message. When a sender expects a reply, it sets the value to the absolute or relative path of the queue or topic it expects the reply to be sent to.
See Message Routing and Correlation in https://docs.microsoft.com/azure/service-bus-messaging/service-bus-messages-payloads?#message-routing-and-correlation.
Return typepropertyreply_to_session_id¶The session identifier augmenting the reply_to address.
This value augments the reply_to information and specifies which session id should be set for the reply when sent to the reply entity.
See Message Routing and Correlation in https://docs.microsoft.com/azure/service-bus-messaging/service-bus-messages-payloads?#message-routing-and-correlation.
Return typepropertyscheduled_enqueue_time_utc¶The utc scheduled enqueue time to the message.
This property can be used for scheduling when sending a message through ServiceBusSender.send method. If cancelling scheduled messages is required, you should use the ServiceBusSender.schedule method, which returns sequence numbers that can be used for future cancellation. scheduled_enqueue_time_utc is None if not set.
Return typepropertysequence_number¶The unique number assigned to a message by Service Bus. The sequence number is a unique 64-bit integer assigned to a message as it is accepted and stored by the broker and functions as its true identifier. For partitioned entities, the topmost 16 bits reflect the partition identifier. Sequence numbers monotonically increase. They roll over to 0 when the 48-64 bit range is exhausted.
Return typepropertysession_id¶The session identifier of the message for a sessionful entity.
For sessionful entities, this application-defined value specifies the session affiliation of the message. Messages with the same session identifier are subject to summary locking and enable exact in-order processing and demultiplexing. For non-sessionful entities, this value is ignored.
See Message Sessions in https://docs.microsoft.com/azure/service-bus-messaging/message-sessions.
Return typepropertytime_to_live¶The life duration of a message.
This value is the relative duration after which the message expires, starting from the instant the message has been accepted and stored by the broker, as captured in enqueued_time_utc. When not set explicitly, the assumed value is the DefaultTimeToLive for the respective queue or topic. A message-level time-to-live value cannot be longer than the entity’s time-to-live setting and it is silently adjusted if it does.
See Expiration in https://docs.microsoft.com/azure/service-bus-messaging/message-expiration
Return typepropertyto¶The to address.
This property is reserved for future use in routing scenarios and presently ignored by the broker itself. Applications can use this value in rule-driven auto-forward chaining scenarios to indicate the intended logical destination of the message.
See https://docs.microsoft.com/azure/service-bus-messaging/service-bus-auto-forwarding for more details.
Return typepropertyvia_partition_key¶The partition key for sending a message into an entity via a partitioned transfer queue.
If a message is sent via a transfer queue in the scope of a transaction, this value selects the transfer queue partition: This is functionally equivalent to partition_key and ensures that messages are kept together and in order as they are transferred.
See Transfers and Send Via in https://docs.microsoft.com/azure/service-bus-messaging/service-bus-transactions#transfers-and-send-via.
Return typeclassazure.servicebus.ReceiveSettleMode[source]¶An enumeration.
PeekLock = <ReceiverSettleMode.PeekLock: 1>¶ ReceiveAndDelete = <ReceiverSettleMode.ReceiveAndDelete: 0>¶ class azure.servicebus.ServiceBusClient(fully_qualified_namespace: str, credential: TokenCredential, **kwargs: Any)[source]¶The ServiceBusClient class defines a high level interface for getting ServiceBusSender and ServiceBusReceiver.
Variablesfully_qualified_namespace (str) – The fully qualified host name for the Service Bus namespace. The namespace format is: <yournamespace>.servicebus.windows.net.
Parametersfully_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
ServiceBusSharedKeyCredential, or credential objects generated by the azure-identity library and objects that implement the get_token(self, *scopes) method.
entity_name (str) – Optional entity name, this can be the name of Queue or Topic. It must be specified if the credential is for specific Queue or Topic.
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:
Create a new instance of the ServiceBusClient.¶import os from azure.servicebus import ServiceBusClient, ServiceBusSharedKeyCredential fully_qualified_namespace = os.environ['SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE'] shared_access_policy = os.environ['SERVICE_BUS_SAS_POLICY'] shared_access_key = os.environ['SERVICE_BUS_SAS_KEY'] servicebus_client = ServiceBusClient( fully_qualified_namespace=fully_qualified_namespace, credential=ServiceBusSharedKeyCredential( shared_access_policy, shared_access_key ) )
close() → None[source]¶Close down the ServiceBus client and the underlying connection.
ReturnsNone
classmethodfrom_connection_string(conn_str: str, **kwargs: Any) → azure.servicebus._servicebus_client.ServiceBusClient[source]¶Create a ServiceBusClient from a connection string.
Parametersconn_str (str) – The connection string of a Service Bus.
Keyword Argumentsentity_name (str) – Optional entity name, this can be the name of Queue or Topic. It must be specified if the credential is for specific Queue or Topic.
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:
Create a new instance of the ServiceBusClient from connection string.¶import os from azure.servicebus import ServiceBusClient servicebus_connection_str = os.environ['SERVICE_BUS_CONNECTION_STR'] servicebus_client = ServiceBusClient.from_connection_string(conn_str=servicebus_connection_str)
get_queue_deadletter_receiver(queue_name: str, **kwargs: Any) → azure.servicebus._servicebus_receiver.ServiceBusReceiver[source]¶ Get ServiceBusReceiver for the dead-letter queue which is the secondary subqueue provided bythe specific Queue, it holds messages that can’t be delivered to any receiver or messages that can’t be processed.
Parametersqueue_name (str) – The path of specific Service Bus Queue the client connects to.
Keyword Argumentsmode (ReceiveSettleMode) – 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.
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.
transfer_deadletter (bool) – Whether to connect to the transfer dead-letter queue, or the standard dead-letter queue. The transfer dead-letter queue holds messages that have failed to be transferred in ForwardTo or SendVia scenarios. Default is False, using the standard dead-letter endpoint.
prefetch (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 being 0, ServiceBusReceiver.receive would try to cache max_batch_size (if provided) within its request to the service.
Example:
Create a new instance of the ServiceBusReceiver for Dead Letter Queue from ServiceBusClient.¶import os from azure.servicebus import ServiceBusClient servicebus_connection_str = os.environ['SERVICE_BUS_CONNECTION_STR'] queue_name = os.environ['SERVICE_BUS_QUEUE_NAME'] servicebus_client = ServiceBusClient.from_connection_string(conn_str=servicebus_connection_str) with servicebus_client: queue_receiver = servicebus_client.get_queue_deadletter_receiver(queue_name=queue_name)
get_queue_receiver(queue_name: str, **kwargs: Any) → azure.servicebus._servicebus_receiver.ServiceBusReceiver[source]¶Get ServiceBusReceiver for the specific queue.
Parametersqueue_name (str) – The path of specific Service Bus Queue the client connects to.
Keyword Argumentsmode (ReceiveSettleMode) – 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.
retry_total (int) – The total number of attempts to redo a failed operation when an error occurs. Default value is 3.
prefetch (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 being 0, ServiceBusReceiver.receive would try to cache max_batch_size (if provided) within its request to the service.
Example:
Create a new instance of the ServiceBusReceiver from ServiceBusClient.¶import os from azure.servicebus import ServiceBusClient servicebus_connection_str = os.environ['SERVICE_BUS_CONNECTION_STR'] queue_name = os.environ['SERVICE_BUS_QUEUE_NAME'] servicebus_client = ServiceBusClient.from_connection_string(conn_str=servicebus_connection_str) with servicebus_client: queue_receiver = servicebus_client.get_queue_receiver(queue_name=queue_name)
get_queue_sender(queue_name: str, **kwargs: Any) → azure.servicebus._servicebus_sender.ServiceBusSender[source]¶Get ServiceBusSender for the specific queue.
Parametersqueue_name (str) – The path of specific Service Bus Queue the client connects to.
Keyword Argumentsretry_total (int) – The total number of attempts to redo a failed operation when an error occurs. Default value is 3.
Return typeExample:
Create a new instance of the ServiceBusSender from ServiceBusClient.¶import os from azure.servicebus import ServiceBusClient servicebus_connection_str = os.environ['SERVICE_BUS_CONNECTION_STR'] queue_name = os.environ['SERVICE_BUS_QUEUE_NAME'] servicebus_client = ServiceBusClient.from_connection_string(conn_str=servicebus_connection_str) with servicebus_client: queue_sender = servicebus_client.get_queue_sender(queue_name=queue_name)
get_queue_session_receiver(queue_name: str, session_id: Optional[str] = None, **kwargs: Any) → azure.servicebus._servicebus_session_receiver.ServiceBusSessionReceiver[source]¶Get ServiceBusSessionReceiver for the specific queue.
Parametersqueue_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.
mode (ReceiveSettleMode) – 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.
retry_total (int) – The total number of attempts to redo a failed operation when an error occurs. Default value is 3.
prefetch (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 being 0, ServiceBusReceiver.receive would try to cache max_batch_size (if provided) within its request to the service.
Example:
Create a new instance of the ServiceBusReceiver from ServiceBusClient.¶import os from azure.servicebus import ServiceBusClient servicebus_connection_str = os.environ['SERVICE_BUS_CONNECTION_STR'] queue_name = os.environ['SERVICE_BUS_QUEUE_NAME'] servicebus_client = ServiceBusClient.from_connection_string(conn_str=servicebus_connection_str) with servicebus_client: queue_receiver = servicebus_client.get_queue_receiver(queue_name=queue_name)
get_subscription_deadletter_receiver(topic_name: str, subscription_name: str, **kwargs: Any) → azure.servicebus._servicebus_receiver.ServiceBusReceiver[source]¶ Get ServiceBusReceiver for the dead-letter queue which is the secondary subqueue provided bythe specific topic subscription, it holds messages that can’t be delivered to any receiver or messages that can’t be processed.
Parameterstopic_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.
mode (ReceiveSettleMode) – 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.
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.
transfer_deadletter (bool) – Whether to connect to the transfer dead-letter queue, or the standard dead-letter queue. The transfer dead letter queue holds messages that have failed to be transferred in ForwardTo or SendVia scenarios. Default is False, using the standard dead-letter endpoint.
prefetch (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 being 0, ServiceBusReceiver.receive would try to cache max_batch_size (if provided) within its request to the service.
Example:
Create a new instance of the ServiceBusReceiver for Dead Letter Queue from ServiceBusClient.¶import os from azure.servicebus import ServiceBusClient servicebus_connection_str = os.environ['SERVICE_BUS_CONNECTION_STR'] topic_name = os.environ["SERVICE_BUS_TOPIC_NAME"] subscription_name = os.environ["SERVICE_BUS_SUBSCRIPTION_NAME"] servicebus_client = ServiceBusClient.from_connection_string(conn_str=servicebus_connection_str) with servicebus_client: subscription_receiver = servicebus_client.get_subscription_deadletter_receiver( topic_name=topic_name, subscription_name=subscription_name, )
get_subscription_receiver(topic_name: str, subscription_name: str, **kwargs: Any) → azure.servicebus._servicebus_receiver.ServiceBusReceiver[source]¶Get ServiceBusReceiver for the specific subscription under the topic.
Parameterstopic_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.
mode (ReceiveSettleMode) – 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.
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.
prefetch (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 being 0, ServiceBusReceiver.receive would try to cache max_batch_size (if provided) within its request to the service.
Example:
Create a new instance of the ServiceBusReceiver from ServiceBusClient.¶import os from azure.servicebus import ServiceBusClient servicebus_connection_str = os.environ['SERVICE_BUS_CONNECTION_STR'] topic_name = os.environ["SERVICE_BUS_TOPIC_NAME"] subscription_name = os.environ["SERVICE_BUS_SUBSCRIPTION_NAME"] servicebus_client = ServiceBusClient.from_connection_string(conn_str=servicebus_connection_str) with servicebus_client: subscription_receiver = servicebus_client.get_subscription_receiver( topic_name=topic_name, subscription_name=subscription_name, )
get_subscription_session_receiver(topic_name: str, subscription_name: str, session_id: Optional[str] = None, **kwargs: Any) → azure.servicebus._servicebus_receiver.ServiceBusReceiver[source]¶Get ServiceBusReceiver for the specific subscription under the topic.
Parameterstopic_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.
mode (ReceiveSettleMode) – 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.
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.
prefetch (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 being 0, ServiceBusReceiver.receive would try to cache max_batch_size (if provided) within its request to the service.
Example:
Create a new instance of the ServiceBusReceiver from ServiceBusClient.¶import os from azure.servicebus import ServiceBusClient servicebus_connection_str = os.environ['SERVICE_BUS_CONNECTION_STR'] topic_name = os.environ["SERVICE_BUS_TOPIC_NAME"] subscription_name = os.environ["SERVICE_BUS_SUBSCRIPTION_NAME"] servicebus_client = ServiceBusClient.from_connection_string(conn_str=servicebus_connection_str) with servicebus_client: subscription_receiver = servicebus_client.get_subscription_receiver( topic_name=topic_name, subscription_name=subscription_name, )
get_topic_sender(topic_name: str, **kwargs: Any) → azure.servicebus._servicebus_sender.ServiceBusSender[source]¶Get ServiceBusSender for the specific topic.
Parameterstopic_name (str) – The path of specific Service Bus Topic the client connects to.
Keyword Argumentsretry_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:
Create a new instance of the ServiceBusSender from ServiceBusClient.¶import os from azure.servicebus import ServiceBusClient servicebus_connection_str = os.environ['SERVICE_BUS_CONNECTION_STR'] topic_name = os.environ['SERVICE_BUS_TOPIC_NAME'] servicebus_client = ServiceBusClient.from_connection_string(conn_str=servicebus_connection_str) with servicebus_client: topic_sender = servicebus_client.get_topic_sender(topic_name=topic_name)class
azure.servicebus.ServiceBusReceiver(fully_qualified_namespace: str, credential: TokenCredential, **kwargs: Any)[source]¶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 for message in receiver: to continuously receive incoming messages in an ongoing fashion.
Variablesfully_qualified_namespace (str) – The fully qualified host name for the Service Bus namespace. The namespace format is: <yournamespace>.servicebus.windows.net.
entity_path (str) – The path of the entity that the client connects to.
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
ServiceBusSharedKeyCredential, or credential objects generated by the azure-identity library and objects that implement the get_token(self, *scopes) method.
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.
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.
mode (ReceiveSettleMode) – 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.
logging_enable (bool) – Whether to output network trace logs to the logger. Default is False.
retry_total (int) – The total number of attempts to redo a failed operation when an error occurs. Default value is 3.
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 (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 being 0, ServiceBusReceiver.receive would try to cache max_batch_size (if provided) within its request to the service.
Example:
Create a new instance of the ServiceBusReceiver.¶import os from azure.servicebus import ServiceBusReceiver, ServiceBusSharedKeyCredential fully_qualified_namespace = os.environ['SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE'] shared_access_policy = os.environ['SERVICE_BUS_SAS_POLICY'] shared_access_key = os.environ['SERVICE_BUS_SAS_KEY'] queue_name = os.environ['SERVICE_BUS_QUEUE_NAME'] queue_receiver = ServiceBusReceiver( fully_qualified_namespace=fully_qualified_namespace, credential=ServiceBusSharedKeyCredential( shared_access_policy, shared_access_key ), queue_name=queue_name )
close() → None[source]¶Close down the handler links (and connection if the handler uses a separate connection).
If the handler has already closed, this operation will do nothing.
Return typeclassmethodfrom_connection_string(conn_str: str, **kwargs: Any) → azure.servicebus._servicebus_receiver.ServiceBusReceiver[source]¶Create a ServiceBusReceiver from a connection string.
Parametersconn_str – The connection string of a Service Bus.
Keyword Argumentsqueue_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.
mode (ReceiveSettleMode) – 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.
retry_total (int) – The total number of attempts to redo a failed operation when an error occurs. Default value is 3.
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 (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 being 0, ServiceBusReceiver.receive would try to cache max_batch_size (if provided) within its request to the service.
Example:
Create a new instance of the ServiceBusReceiver from connection string.¶import os from azure.servicebus import ServiceBusReceiver servicebus_connection_str = os.environ['SERVICE_BUS_CONNECTION_STR'] queue_name = os.environ['SERVICE_BUS_QUEUE_NAME'] queue_receiver = ServiceBusReceiver.from_connection_string( conn_str=servicebus_connection_str, queue_name=queue_name )
get_streaming_message_iter(max_wait_time=None)[source]¶Receive messages from an iterator indefinitely, or if a max_wait_time is specified, until such a timeout occurs.
Parametersmax_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 Iterator[ReceivedMessage]
next()¶ peek_messages(message_count: int = 1, sequence_number: Optional[int] = None) → List[azure.servicebus._common.message.PeekMessage][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.
Parametersmessage_count (int) – The maximum number of messages to try and peek. The default value is 1.
sequence_number (int) – A message sequence number from which to start browsing messages.
Example:
Look at pending messages in the queue.¶with servicebus_receiver: messages = servicebus_receiver.peek_messages() for message in messages: print(str(message))
receive_deferred_messages(sequence_numbers: List[int]) → List[azure.servicebus._common.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.
Parameterssequence_numbers (list[int]) – A list of the sequence numbers of messages that have been deferred.
Return typeExample:
Receive deferred messages from ServiceBus.¶with servicebus_receiver: deferred_sequenced_numbers = [] messages = servicebus_receiver.receive_messages(max_wait_time=5) for message in messages: deferred_sequenced_numbers.append(message.sequence_number) print(str(message)) message.defer() received_deferred_msg = servicebus_receiver.receive_deferred_messages( sequence_numbers=deferred_sequenced_numbers ) for msg in received_deferred_msg: msg.complete()
receive_messages(max_batch_size: Optional[int] = None, max_wait_time: Optional[float] = None) → List[azure.servicebus._common.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 was set for the receiver. If prefetch is not set for the receiver, the receiver would try to cache max_batch_size (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.
Parametersmax_batch_size (int) – Maximum number of messages in the batch. Actual number returned will depend on prefetch 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, an no messages arrive within the timeout period, an empty list will be returned.
Example:
Receive messages from ServiceBus.¶with servicebus_receiver: messages = servicebus_receiver.receive_messages(max_wait_time=5) for message in messages: print(str(message)) message.complete()class
azure.servicebus.ServiceBusSessionReceiver(fully_qualified_namespace, credential, **kwargs)[source]¶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 for message in receiver: to continuously receive incoming messages in an ongoing fashion.
Variablesfully_qualified_namespace (str) – The fully qualified host name for the Service Bus namespace. The namespace format is: <yournamespace>.servicebus.windows.net.
entity_path (str) – The path of the entity that the client connects to.
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
ServiceBusSharedKeyCredential, or credential objects generated by the azure-identity library and objects that implement the get_token(self, *scopes) method.
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.
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.
mode (ReceiveSettleMode) – 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.
logging_enable (bool) – Whether to output network trace logs to the logger. Default is False.
retry_total (int) – The total number of attempts to redo a failed operation when an error occurs. Default value is 3.
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 (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 being 0, ServiceBusReceiver.receive would try to cache max_batch_size (if provided) within its request to the service.
Example:
Create a new instance of the ServiceBusReceiver.¶import os from azure.servicebus import ServiceBusReceiver, ServiceBusSharedKeyCredential fully_qualified_namespace = os.environ['SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE'] shared_access_policy = os.environ['SERVICE_BUS_SAS_POLICY'] shared_access_key = os.environ['SERVICE_BUS_SAS_KEY'] queue_name = os.environ['SERVICE_BUS_QUEUE_NAME'] queue_receiver = ServiceBusReceiver( fully_qualified_namespace=fully_qualified_namespace, credential=ServiceBusSharedKeyCredential( shared_access_policy, shared_access_key ), queue_name=queue_name )
close() → None¶Close down the handler links (and connection if the handler uses a separate connection).
If the handler has already closed, this operation will do nothing.
Return typeclassmethodfrom_connection_string(conn_str: str, **kwargs: Any) → azure.servicebus._servicebus_session_receiver.ServiceBusSessionReceiver[source]¶Create a ServiceBusSessionReceiver from a connection string.
Parametersconn_str – The connection string of a Service Bus.
Keyword Argumentsqueue_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.
mode (ReceiveSettleMode) – 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.
retry_total (int) – The total number of attempts to redo a failed operation when an error occurs. Default value is 3.
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 (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 being 0, ServiceBusReceiver.receive would try to cache max_batch_size (if provided) within its request to the service.
Example:
Create a new instance of the ServiceBusReceiver from connection string.¶import os from azure.servicebus import ServiceBusReceiver servicebus_connection_str = os.environ['SERVICE_BUS_CONNECTION_STR'] queue_name = os.environ['SERVICE_BUS_QUEUE_NAME'] queue_receiver = ServiceBusReceiver.from_connection_string( conn_str=servicebus_connection_str, queue_name=queue_name )
get_streaming_message_iter(max_wait_time=None)¶Receive messages from an iterator indefinitely, or if a max_wait_time is specified, until such a timeout occurs.
Parametersmax_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 Iterator[ReceivedMessage]
next()¶ peek_messages(message_count: int = 1, sequence_number: Optional[int] = None) → List[azure.servicebus._common.message.PeekMessage]¶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.
Parametersmessage_count (int) – The maximum number of messages to try and peek. The default value is 1.
sequence_number (int) – A message sequence number from which to start browsing messages.
Example:
Look at pending messages in the queue.¶with servicebus_receiver: messages = servicebus_receiver.peek_messages() for message in messages: print(str(message))
receive_deferred_messages(sequence_numbers: List[int]) → List[azure.servicebus._common.message.ReceivedMessage]¶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.
Parameterssequence_numbers (list[int]) – A list of the sequence numbers of messages that have been deferred.
Return typeExample:
Receive deferred messages from ServiceBus.¶with servicebus_receiver: deferred_sequenced_numbers = [] messages = servicebus_receiver.receive_messages(max_wait_time=5) for message in messages: deferred_sequenced_numbers.append(message.sequence_number) print(str(message)) message.defer() received_deferred_msg = servicebus_receiver.receive_deferred_messages( sequence_numbers=deferred_sequenced_numbers ) for msg in received_deferred_msg: msg.complete()
receive_messages(max_batch_size: Optional[int] = None, max_wait_time: Optional[float] = None) → List[azure.servicebus._common.message.ReceivedMessage]¶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 was set for the receiver. If prefetch is not set for the receiver, the receiver would try to cache max_batch_size (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.
Parametersmax_batch_size (int) – Maximum number of messages in the batch. Actual number returned will depend on prefetch 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, an no messages arrive within the timeout period, an empty list will be returned.
Example:
Receive messages from ServiceBus.¶with servicebus_receiver: messages = servicebus_receiver.receive_messages(max_wait_time=5) for message in messages: print(str(message)) message.complete()property
session¶Get the ServiceBusSession object linked with the receiver. Session is only available to session-enabled entities.
Return typeExample:
Get session from a receiver¶with servicebus_client.get_queue_session_receiver(queue_name=queue_name, session_id=session_id) as receiver: session = receiver.sessionclass
azure.servicebus.ServiceBusSession(session_id: str, receiver: Union[ServiceBusSessionReceiver, ServiceBusSessionReceiverAsync], encoding: str = 'UTF-8')[source]¶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.
Variablesauto_renew_error (AutoLockRenewTimeout or AutoLockRenewFailed) – Error when AutoLockRenew is used and it fails to renew the session lock.
Example:
Get session from a receiver¶with servicebus_client.get_queue_session_receiver(queue_name=queue_name, session_id=session_id) as receiver: session = receiver.session
get_session_state() → str[source]¶Get the session state.
Returns None if no state has been set.
Return typeExample:
Get the session state¶with servicebus_client.get_queue_session_receiver(queue_name=queue_name, session_id=session_id) as receiver: session = receiver.session session_state = session.get_session_state()
renew_lock() → None[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.AutoLockRenew instance.
Example:
Renew the session lock before it expires¶with servicebus_client.get_queue_session_receiver(queue_name=queue_name, session_id=session_id) as receiver: session = receiver.session session_state = session.renew_lock()
set_session_state(state: Union[str, bytes, bytearray]) → None[source]¶Set the session state.
Parametersstate (str, bytes or bytearray) – The state value.
Example:
Set the session state¶with servicebus_client.get_queue_session_receiver(queue_name=queue_name, session_id=session_id) as receiver: session = receiver.session session_state = session.set_session_state("START")property
locked_until_utc¶The time at which this session’s lock will expire.
Return typepropertysession_id¶Session id of the current session.
Return typeclassazure.servicebus.ServiceBusSender(fully_qualified_namespace: str, credential: TokenCredential, **kwargs: Any)[source]¶The ServiceBusSender class defines a high level interface for sending messages to the Azure Service Bus Queue or Topic.
Variablesfully_qualified_namespace (str) – The fully qualified host name for the Service Bus namespace. The namespace format is: <yournamespace>.servicebus.windows.net.
entity_name (str) – The name of the entity that the client connects to.
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
ServiceBusSharedKeyCredential, or credential objects generated by the azure-identity library and objects that implement the get_token(self, *scopes) method.
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.
retry_total (int) – The total number of attempts to redo a failed operation when an error occurs. Default value is 3.
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:
Create a new instance of the ServiceBusSender.¶import os from azure.servicebus import ServiceBusSender, ServiceBusSharedKeyCredential fully_qualified_namespace = os.environ['SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE'] shared_access_policy = os.environ['SERVICE_BUS_SAS_POLICY'] shared_access_key = os.environ['SERVICE_BUS_SAS_KEY'] queue_name = os.environ['SERVICE_BUS_QUEUE_NAME'] queue_sender = ServiceBusSender( fully_qualified_namespace=fully_qualified_namespace, credential=ServiceBusSharedKeyCredential( shared_access_policy, shared_access_key ), queue_name=queue_name )
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.
Parameterssequence_numbers (int or list[int]) – The sequence numbers of the scheduled messages.
Return typeRaises~azure.servicebus.exceptions.ServiceBusError if messages cancellation failed due to message already cancelled or enqueued.
Example:
Cancelling messages scheduled to be sent in future¶with servicebus_sender: servicebus_sender.cancel_scheduled_messages(sequence_nums)
close() → None¶Close down the handler links (and connection if the handler uses a separate connection).
If the handler has already closed, this operation will do nothing.
Return typecreate_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.
Parametersmax_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 typeExample:
Create BatchMessage object within limited size¶with servicebus_sender: batch_message = servicebus_sender.create_batch() batch_message.add(Message("Single message inside batch"))classmethod
from_connection_string(conn_str: str, **kwargs: Any) → azure.servicebus._servicebus_sender.ServiceBusSender[source]¶Create a ServiceBusSender from a connection string.
Parametersconn_str – The connection string of a Service Bus.
Keyword Argumentsqueue_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.
retry_total (int) – The total number of attempts to redo a failed operation when an error occurs. Default value is 3.
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.
ServiceBusSenderClient
Example:
Create a new instance of the ServiceBusSender from connection string.¶import os from azure.servicebus import ServiceBusSender servicebus_connection_str = os.environ['SERVICE_BUS_CONNECTION_STR'] queue_name = os.environ['SERVICE_BUS_QUEUE_NAME'] queue_sender = ServiceBusSender.from_connection_string( conn_str=servicebus_connection_str, queue_name=queue_name )
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. 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:
Schedule a message to be sent in future¶with servicebus_sender: scheduled_time_utc = datetime.datetime.utcnow() + datetime.timedelta(seconds=30) scheduled_messages = [Message("Scheduled message") for _ in range(10)] sequence_nums = servicebus_sender.schedule_messages(scheduled_messages, scheduled_time_utc)
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.
Parametersmessage (Message or BatchMessage or list[Message]) – The ServiceBus message to be sent.
Return typeRaises 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:
Send message.¶with servicebus_sender: message = Message("Hello World") servicebus_sender.send_messages(message)class
azure.servicebus.ServiceBusSharedKeyCredential(policy: str, key: str)[source]¶The shared access key credential used for authentication.
Parametersget_token(*scopes: str, **kwargs: Any) → azure.servicebus._base_handler.AccessToken[source]¶ class azure.servicebus.TransportType[source]¶Transport type The underlying transport protocol type:
Amqp: AMQP over the default TCP transport protocol, it uses port 5671. AmqpOverWebsocket: Amqp over the Web Sockets transport protocol, it uses port 443.
Amqp = 1¶ AmqpOverWebsocket = 2¶ class azure.servicebus.AutoLockRenew(executor=None, max_workers=None)[source]¶Auto renew locks for messages and sessions using a background thread pool.
Parametersexecutor (ThreadPoolExecutor) – A user-specified thread pool. This cannot be combined with setting max_workers.
max_workers (int) – Specify the maximum workers in the thread pool. If not specified the number used will be derived from the core count of the environment. This cannot be combined with executor.
Example:
Automatically renew a message lock¶from azure.servicebus import AutoLockRenew lock_renewal = AutoLockRenew(max_workers=4) with servicebus_receiver: for message in servicebus_receiver: # Auto renew message for 1 minute. lock_renewal.register(message, timeout=60) process_message(message) message.complete()Automatically renew a session lock¶
from azure.servicebus import AutoLockRenew lock_renewal = AutoLockRenew(max_workers=4) with servicebus_client.get_queue_session_receiver(queue_name=queue_name, session_id=session_id) as receiver: session = receiver.session # Auto renew session lock for 2 minutes lock_renewal.register(session, timeout=120) for message in receiver: process_message(message) message.complete()
close(wait=True)[source]¶Cease autorenewal by shutting down the thread pool to clean up any remaining lock renewal threads.
Parameterswait (bool) – Whether to block until thread pool has shutdown. Default is True.
register(renewable, timeout=300, on_lock_renew_failure=None)[source]¶Register a renewable entity for automatic lock renewal.
Parametersrenewable (ReceivedMessage or 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[LockRenewFailureCallback]) – A callback may be specified to be called when the lock is lost on the renewable that is being registered. Default value is None (no callback).
Subpackages¶
Submodules¶
azure.servicebus.exceptions module¶
exceptionazure.servicebus.exceptions.AutoLockRenewFailed(message, inner_exception=None)[source]¶An attempt to renew a lock on a message or session in the background has failed.
with_traceback()¶Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
args¶ exception azure.servicebus.exceptions.AutoLockRenewTimeout(message, inner_exception=None)[source]¶The time allocated to renew the message or session lock has elapsed.
with_traceback()¶Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
args¶ exception azure.servicebus.exceptions.MessageAlreadySettled(action)[source]¶Failed to settle the message.
An attempt was made to complete an operation on a message that has already been settled (completed, abandoned, dead-lettered or deferred). This error will also be raised if an attempt is made to settle a message received via ReceiveAndDelete mode.
with_traceback()¶Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
args¶ exception azure.servicebus.exceptions.MessageContentTooLarge(message, inner_exception=None)[source]¶Message content is larger than the service bus frame size
with_traceback()¶Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
args¶ exception azure.servicebus.exceptions.MessageError(message, inner_exception=None)[source]¶A message failed to send because the message is in a wrong state
with_traceback()¶Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
args¶ exception azure.servicebus.exceptions.MessageLockExpired(message=None, inner_exception=None)[source]¶The lock on the message has expired and it has been released back to the queue.
It will need to be received again in order to settle it.
with_traceback()¶Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
args¶ exception azure.servicebus.exceptions.MessageSendFailed(inner_exception)[source]¶A message failed to send to the Service Bus entity.
with_traceback()¶Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
args¶ exception azure.servicebus.exceptions.MessageSettleFailed(action, inner_exception)[source]¶Attempt to settle a message failed.
with_traceback()¶Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
args¶ exception azure.servicebus.exceptions.NoActiveSession(message, inner_exception=None)[source]¶No active Sessions are available to receive from.
with_traceback()¶Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
args¶ exception azure.servicebus.exceptions.OperationTimeoutError(message, inner_exception=None)[source]¶Operation timed out.
with_traceback()¶Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
args¶ exception azure.servicebus.exceptions.ServiceBusAuthenticationError(message, inner_exception=None)[source]¶An error occured when authenticate the connection.
with_traceback()¶Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
args¶ exception azure.servicebus.exceptions.ServiceBusAuthorizationError(message, inner_exception=None)[source]¶An error occured when authorizing the connection.
with_traceback()¶Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
args¶ exception azure.servicebus.exceptions.ServiceBusConnectionError(message, inner_exception=None)[source]¶An error occured in the connection.
with_traceback()¶Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
args¶ exception azure.servicebus.exceptions.ServiceBusError(message, inner_exception=None)[source]¶An error occured.
This is the parent of all Service Bus errors and can be used for default error handling.
with_traceback()¶Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
args¶ exception azure.servicebus.exceptions.ServiceBusResourceNotFound(message, inner_exception=None)[source]¶The Service Bus entity could not be reached.
with_traceback()¶Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
args¶ exception azure.servicebus.exceptions.SessionLockExpired(message=None, inner_exception=None)[source]¶The lock on the session has expired.
All unsettled messages that have been received can no longer be settled.
with_traceback()¶Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
args¶ncG1vNJzZmiZqqq%2Fpr%2FDpJuom6Njr627wWeaqKqVY8SqusOorqxmnprBcHDWnploqKmptbC6jpqxrqqVYsCmvtWimp6apah8eHqPZ2ebbV%2BWx7a%2BxGeqnqqmnrCmrtSsZaGsnaE%3D