ServiceBusSender Class

The ServiceBusSender class defines a high level interface for sending messages to the Azure Service Bus Queue or Topic.

Please use the get_<queue/topic>_sender method of ~azure.servicebus.ServiceBusClient to create a ServiceBusSender instance.

Inheritance

azure.servicebus._base_handler.BaseHandler

ServiceBusSender

azure.servicebus._servicebus_sender.SenderMixin

ServiceBusSender

Constructor

ServiceBusSender(fully_qualified_namespace: str, credential: TokenCredential | AzureSasCredential | AzureNamedKeyCredential, *, queue_name: str | None = None, topic_name: str | None = None, **kwargs: Any)

Parameters

Name	Description
fully_qualified_namespace Required	str The fully qualified host name for the Service Bus namespace. The namespace format is: .servicebus.windows.net.
credential Required	TokenCredential or AzureSasCredential or AzureNamedKeyCredential 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, or alternatively, an AzureSasCredential can be provided too.

Keyword-Only Parameters

Name	Description
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.
client_identifier	str A string-based identifier to uniquely identify the client instance. Service Bus will associate it with some error messages for easier correlation of errors. If not specified, a unique id will be generated.
socket_timeout	float The time in seconds that the underlying socket on the connection should wait when sending and receiving data before timing out. The default value is 0.2 for TransportType.Amqp and 1 for TransportType.AmqpOverWebsocket. If connection errors are occurring due to write timing out, a larger than default value may need to be passed in.

Variables

Name	Description
fully_qualified_namespace	str The fully qualified host name for the Service Bus namespace. The namespace format is: .servicebus.windows.net.
entity_name	str The name of the entity that the client connects to.

Methods

cancel_scheduled_messages	Cancel one or more messages that have previously been scheduled and are still pending.
close	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.
create_message_batch	Create a ServiceBusMessageBatch 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.
schedule_messages	Send Message or multiple Messages to be enqueued at a specific time. Returns a list of the sequence numbers of the enqueued messages.
send_messages	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.

cancel_scheduled_messages

Cancel one or more messages that have previously been scheduled and are still pending.

cancel_scheduled_messages(sequence_numbers: int | List[int], *, timeout: float | None = None, **kwargs: Any) -> None

Parameters

Name	Description
sequence_numbers Required	int or list[int] The sequence numbers of the scheduled messages.

Keyword-Only Parameters

Name	Description
timeout	float The total operation timeout in seconds including all the retries. The value must be greater than 0 if specified. The default value is None, meaning no timeout.

Returns

Type	Description
None

Exceptions

Type	Description
azure.servicebus.exceptions.ServiceBusError if messages cancellation failed due to message alreadycancelled or enqueued.

Examples

Cancelling messages scheduled to be sent in future

   with servicebus_sender:
       servicebus_sender.cancel_scheduled_messages(sequence_nums)

close

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.

close() -> None

Keyword-Only Parameters

Name	Description
timeout	float The total operation timeout in seconds including all the retries. The value must be greater than 0 if specified. The default value is None, meaning no timeout.

Returns

Type	Description
None

Exceptions

Type	Description
azure.servicebus.exceptions.ServiceBusError if messages cancellation failed due to message alreadycancelled or enqueued.

create_message_batch

Create a ServiceBusMessageBatch 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.

create_message_batch(max_size_in_bytes: int | None = None) -> ServiceBusMessageBatch

Parameters

Name	Description
max_size_in_bytes	Optional[int] The maximum size of bytes data that a ServiceBusMessageBatch object can hold. By default, the value is determined by your Service Bus tier. default value: None

Keyword-Only Parameters

Name	Description
timeout	float The total operation timeout in seconds including all the retries. The value must be greater than 0 if specified. The default value is None, meaning no timeout.

Returns

Type	Description
ServiceBusMessageBatch	A ServiceBusMessageBatch object

Exceptions

Type	Description
azure.servicebus.exceptions.ServiceBusError if messages cancellation failed due to message alreadycancelled or enqueued.

Examples

Create ServiceBusMessageBatch object within limited size

   with servicebus_sender:
       batch_message = servicebus_sender.create_message_batch()
       batch_message.add_message(ServiceBusMessage("Single message inside batch"))

schedule_messages

Send Message or multiple Messages to be enqueued at a specific time. Returns a list of the sequence numbers of the enqueued messages.

schedule_messages(messages: MessageTypes, schedule_time_utc: datetime, *, timeout: float | None = None, **kwargs: Any) -> List[int]

Parameters

Name	Description
messages Required	Union[ServiceBusMessage, AmqpAnnotatedMessage, List[Union[ServiceBusMessage, AmqpAnnotatedMessage]]] The message or list of messages to schedule.
schedule_time_utc Required	datetime The utc date and time to enqueue the messages.

Keyword-Only Parameters

Name	Description
timeout	float The total operation timeout in seconds including all the retries. The value must be greater than 0 if specified. The default value is None, meaning no timeout.

Returns

Type	Description
list[int]	A list of the sequence numbers of the enqueued messages.

Exceptions

Type	Description
azure.servicebus.exceptions.ServiceBusError if messages cancellation failed due to message alreadycancelled or enqueued.

Examples

Schedule a message to be sent in future

   with servicebus_sender:
       scheduled_time_utc = datetime.datetime.utcnow() + datetime.timedelta(seconds=30)
       scheduled_messages = [ServiceBusMessage("Scheduled message") for _ in range(10)]
       sequence_nums = servicebus_sender.schedule_messages(scheduled_messages, scheduled_time_utc)

send_messages

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.

send_messages(message: MessageTypes | ServiceBusMessageBatch, *, timeout: float | None = None, **kwargs: Any) -> None

Parameters

Name	Description
message Required	Union[ServiceBusMessage, ServiceBusMessageBatch, AmqpAnnotatedMessage, List[Union[ServiceBusMessage, AmqpAnnotatedMessage]]] The ServiceBus message to be sent.

Keyword-Only Parameters

Name	Description
timeout	Optional[float] The total operation timeout in seconds including all the retries. The value must be greater than 0 if specified. The default value is None, meaning no timeout.

Returns

Type	Description
None

Exceptions

Type	Description
azure.servicebus.exceptions.OperationTimeoutError if sending times out.

Examples

Send message.

   with servicebus_sender:
       message_send = ServiceBusMessage("Hello World")
       servicebus_sender.send_messages(message_send)

Attributes

client_identifier

Get the ServiceBusSender client_identifier associated with the sender instance.

Returns

Type	Description
str