ServiceBusClient Class

The ServiceBusClient class defines a high level interface for getting ServiceBusSender and ServiceBusReceiver.

Inheritance

builtins.object

ServiceBusClient

Constructor

ServiceBusClient(fully_qualified_namespace: str, credential: Union[TokenCredential, AzureSasCredential, AzureNamedKeyCredential], **kwargs: Any)

Parameters

fully_qualified_namespace

str

Required

The fully qualified host name for the Service Bus namespace. The namespace format is: .servicebus.windows.net.

credential

TokenCredential or AzureSasCredential or AzureNamedKeyCredential

Required

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.

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 in which case port 5671 is used. If the port 5671 is unavailable/blocked in the network environment, TransportType.AmqpOverWebsocket could be used instead which uses port 443 for communication.

http_proxy

dict

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

user_agent

str

If specified, this will be added in front of the built-in user agent string.

retry_total

int

The total number of attempts to redo a failed operation when an error occurs. Default value is 3.

retry_backoff_factor

float

Delta back-off internal in the unit of second between retries. Default value is 0.8.

retry_backoff_max

float

Maximum back-off interval in the unit of second. Default value is 120.

Examples

Create a new instance of the ServiceBusClient.

   import os
   from azure.identity import DefaultAzureCredential
   from azure.servicebus import ServiceBusClient
   fully_qualified_namespace = os.environ['SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE']
   servicebus_client = ServiceBusClient(
       fully_qualified_namespace=fully_qualified_namespace,
       credential=DefaultAzureCredential()
   )

Variables

fully_qualified_namespace

str

The fully qualified host name for the Service Bus namespace. The namespace format is: .servicebus.windows.net.

Methods

close	Close down the ServiceBus client. All spawned senders, receivers and underlying connection will be shutdown.
from_connection_string	Create a ServiceBusClient from a connection string.
get_queue_receiver	Get ServiceBusReceiver for the specific queue.
get_queue_sender	Get ServiceBusSender for the specific queue.
get_subscription_receiver	Get ServiceBusReceiver for the specific subscription under the topic.
get_topic_sender	Get ServiceBusSender for the specific topic.

close

Close down the ServiceBus client. All spawned senders, receivers and underlying connection will be shutdown.

close() -> None

Returns

None

from_connection_string

Create a ServiceBusClient from a connection string.

from_connection_string(conn_str: str, **kwargs: Any) -> azure.servicebus._servicebus_client.ServiceBusClient

Parameters

conn_str

str

Required

The connection string of a Service Bus.

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 in which case port 5671 is used. If the port 5671 is unavailable/blocked in the network environment, TransportType.AmqpOverWebsocket could be used instead which uses port 443 for communication.

http_proxy

dict

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

user_agent

str

If specified, this will be added in front of the built-in user agent string.

retry_total

int

The total number of attempts to redo a failed operation when an error occurs. Default value is 3.

retry_backoff_factor

float

Delta back-off internal in the unit of second between retries. Default value is 0.8.

retry_backoff_max

float

Maximum back-off interval in the unit of second. Default value is 120.

Return type

ServiceBusClient

Examples

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_receiver

Get ServiceBusReceiver for the specific queue.

get_queue_receiver(queue_name: str, **kwargs: Any) -> azure.servicebus._servicebus_receiver.ServiceBusReceiver

Parameters

queue_name

str

Required

The path of specific Service Bus Queue the client connects to.

session_id

<xref:Union>[str, <xref:azure.servicebus.NEXT_AVAILABLE_SESSION>]

A specific session from which to receive. This must be specified for a sessionful queue, otherwise it must be None. In order to receive messages from the next available session, set this to ~azure.servicebus.NEXT_AVAILABLE_SESSION.

str]] sub_queue

<xref:Optional>[<xref:Union>[<xref:azure.servicebus.ServiceBusSubQueue,>

If specified, the subqueue this receiver will connect to. This includes the DEAD_LETTER and TRANSFER_DEAD_LETTER queues, holds messages that can't be delivered to any receiver or messages that can't be processed. The default is None, meaning connect to the primary queue. Can be assigned values from ServiceBusSubQueue enum or equivalent string values "deadletter" and "transferdeadletter".

receive_mode

<xref:Union>[ServiceBusReceiveMode, str]

The receive_mode with which messages will be retrieved from the entity. The two options are PEEK_LOCK and RECEIVE_AND_DELETE. Messages received with PEEK_LOCK must be settled within a given lock period before they will be removed from the queue. Messages received with RECEIVE_AND_DELETE 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 receive_mode is PEEK_LOCK.

max_wait_time

<xref:Optional>[float]

The timeout in seconds between received messages after which the receiver will automatically stop receiving. The default value is None, meaning no timeout.

auto_lock_renewer

<xref:Optional>[AutoLockRenewer]

An ~azure.servicebus.AutoLockRenewer can be provided such that messages are automatically registered on receipt. If the receiver is a session receiver, it will apply to the session instead.

prefetch_count

int

The maximum number of messages to cache with each request to the service. This setting is only for advanced performance tuning. Increasing this value will improve message throughput performance but increase the chance that messages will expire while they are cached if they're not processed fast enough. The default value is 0, meaning messages will be received from the service and processed one at a time. In the case of prefetch_count being 0, ServiceBusReceiver.receive would try to cache max_message_count (if provided) within its request to the service.

Return type

ServiceBusReceiver

Examples

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

Get ServiceBusSender for the specific queue.

get_queue_sender(queue_name: str, **kwargs: Any) -> azure.servicebus._servicebus_sender.ServiceBusSender

Parameters

queue_name

str

Required

The path of specific Service Bus Queue the client connects to.

Return type

ServiceBusSender

Examples

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_subscription_receiver

Get ServiceBusReceiver for the specific subscription under the topic.

get_subscription_receiver(topic_name: str, subscription_name: str, **kwargs: Any) -> azure.servicebus._servicebus_receiver.ServiceBusReceiver

Parameters

topic_name

str

Required

The name of specific Service Bus Topic the client connects to.

subscription_name

str

Required

The name of specific Service Bus Subscription under the given Service Bus Topic.

session_id

<xref:Union>[str, <xref:azure.servicebus.NEXT_AVAILABLE_SESSION>]

A specific session from which to receive. This must be specified for a sessionful subscription, otherwise it must be None. In order to receive messages from the next available session, set this to ~azure.servicebus.NEXT_AVAILABLE_SESSION.

str]] sub_queue

<xref:Optional>[<xref:Union>[<xref:azure.servicebus.ServiceBusSubQueue,>

If specified, the subqueue this receiver will connect to. This includes the DEAD_LETTER and TRANSFER_DEAD_LETTER queues, holds messages that can't be delivered to any receiver or messages that can't be processed. The default is None, meaning connect to the primary queue. Can be assigned values from ServiceBusSubQueue enum or equivalent string values "deadletter" and "transferdeadletter".

receive_mode

<xref:Union>[ServiceBusReceiveMode, str]

The receive_mode with which messages will be retrieved from the entity. The two options are PEEK_LOCK and RECEIVE_AND_DELETE. Messages received with PEEK_LOCK must be settled within a given lock period before they will be removed from the subscription. Messages received with RECEIVE_AND_DELETE 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 receive_mode is PEEK_LOCK.

max_wait_time

<xref:Optional>[float]

The timeout in seconds between received messages after which the receiver will automatically stop receiving. The default value is None, meaning no timeout.

auto_lock_renewer

<xref:Optional>[AutoLockRenewer]

An ~azure.servicebus.AutoLockRenewer can be provided such that messages are automatically registered on receipt. If the receiver is a session receiver, it will apply to the session instead.

prefetch_count

int

The maximum number of messages to cache with each request to the service. This setting is only for advanced performance tuning. Increasing this value will improve message throughput performance but increase the chance that messages will expire while they are cached if they're not processed fast enough. The default value is 0, meaning messages will be received from the service and processed one at a time. In the case of prefetch_count being 0, ServiceBusReceiver.receive would try to cache max_message_count (if provided) within its request to the service.

Return type

ServiceBusReceiver

Examples

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

Get ServiceBusSender for the specific topic.

get_topic_sender(topic_name: str, **kwargs: Any) -> azure.servicebus._servicebus_sender.ServiceBusSender

Parameters

topic_name

str

Required

The path of specific Service Bus Topic the client connects to.

Return type

ServiceBusSender

Examples

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)