Share via

ServiceBusSender Class

  • Reference

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.aio.ServiceBusClient to create a ServiceBusSender instance.

Inheritance
azure.servicebus.aio._base_handler_async.BaseHandler
ServiceBusSender
azure.servicebus._servicebus_sender.SenderMixin
ServiceBusSender

Constructor

ServiceBusSender(fully_qualified_namespace: str, credential: AsyncTokenCredential | 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
AsyncTokenCredential 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. Only one of queue_name or topic_name can be provided.
topic_name
str

The path of specific Service Bus Topic the client connects to. Only one of queue_name or topic_name can be provided.
logging_enable
bool

Whether to output network trace logs to the logger. Default is False.
transport_type
TransportType

The type of transport protocol that will be used for communicating with the Service Bus service. Default is TransportType.Amqp.
http_proxy
Dict

HTTP proxy settings. This must be a dictionary with the following keys: 'proxy_hostname' (str value) and 'proxy_port' (int value). Additionally the following keys may also be present: 'username', 'password'.
user_agent
str

If specified, this will be added in front of the built-in user agent string.
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 connection.

If the handler has already closed, this operation will do nothing. An optional exception can be passed in to indicate that the handler was shutdown due to error.
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 by the service. 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.

async 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


   async with servicebus_sender:
       await servicebus_sender.cancel_scheduled_messages(sequence_nums)

close

Close down the handler connection.

If the handler has already closed, this operation will do nothing. An optional exception can be passed in to indicate that the handler was shutdown due to error.

async 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.

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

Parameters

Name Description
max_size_in_bytes
int or None

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

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


   async with servicebus_sender:
       batch_message = await 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 by the service. Returns a list of the sequence numbers of the enqueued messages.

async schedule_messages(messages: Mapping[str, Any] | ServiceBusMessage | AmqpAnnotatedMessage | Iterable[Mapping[str, Any]] | Iterable[ServiceBusMessage] | Iterable[AmqpAnnotatedMessage], 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]

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


   async with servicebus_sender:
       scheduled_time_utc = datetime.datetime.utcnow() + datetime.timedelta(seconds=30)
       scheduled_messages = [ServiceBusMessage("Scheduled message") for _ in range(10)]
       sequence_nums = await 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.

async send_messages(message: Mapping[str, Any] | ServiceBusMessage | AmqpAnnotatedMessage | Iterable[Mapping[str, Any]] | Iterable[ServiceBusMessage] | Iterable[AmqpAnnotatedMessage] | 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.


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

Attributes

client_identifier

Get the ServiceBusSender client identifier associated with the sender instance.

Returns

Type Description
str