ServiceBusClient 類別

  • 參考

ServiceBusClient 類別會定義用於取得 ServiceBusSender 和 ServiceBusReceiver 的高階介面。

繼承
builtins.object
ServiceBusClient

建構函式

ServiceBusClient(fully_qualified_namespace: str, credential: TokenCredential | AzureSasCredential | AzureNamedKeyCredential, *, retry_total: int = 3, retry_backoff_factor: float = 0.8, retry_backoff_max: float = 120, retry_mode: str = 'exponential', **kwargs: Any)

參數

fully_qualified_namespace
str
必要

服務匯流排命名空間的完整主機名稱。 命名空間格式為： .servicebus.windows.net。

credential
TokenCredential 或 AzureSasCredential 或 AzureNamedKeyCredential
必要

用於驗證的認證物件，會實作用於取得權杖的特定介面。 它接受 azure-identity 程式庫所產生的認證物件，以及實作 *get_token (自我、 範圍) 方法的物件，或者也可以提供 AzureSasCredential。

logging_enable
bool

是否要將網路追蹤記錄輸出至記錄器。 預設值為 False。

transport_type
TransportType

將用於與服務匯流排服務通訊的傳輸通訊協定類型。 預設值為 TransportType.Amqp ，在此情況下會使用埠 5671。 如果網路環境中無法使用/封鎖埠 5671，則可改用 TransportType.AmqpOverWebsocket 來使用埠 443 進行通訊。

http_proxy
Dict

HTTP Proxy 設定。 這必須是具有下列索引鍵的字典： 'proxy_hostname' ( str 值) 和 'proxy_port' (int 值) 。 此外，也可能會出現下列金鑰： 'username'、'password'。

user_agent
str

如果指定，這會新增到內建使用者代理程式字串前面。

retry_total
int

發生錯誤時，嘗試取消復原失敗作業的嘗試總數。 預設值為 3。

retry_backoff_factor
float

重試之間第二個單位中的差異輪詢內部。 預設值為 0.8。

retry_backoff_max
float

第二個單位中的最大輪詢間隔。 預設值為 120。

retry_mode
str

重試嘗試之間的延遲行為。 支援的值為 「fixed」 或 「exponential」，其中預設值為 「exponential」。

custom_endpoint_address
str

用來建立服務匯流排服務的連線的自訂端點位址，允許透過任何應用程式閘道或其他主機環境所需的路徑路由傳送網路要求。 預設值為 None。 格式會像 「sb:// < custom_endpoint_hostname > ： < custom_endpoint_port > 」。 如果未在 custom_endpoint_address中指定埠，預設會使用埠 443。

connection_verify
str

SSL 憑證之自訂CA_BUNDLE檔案的路徑，用來驗證連線端點的身分識別。 預設值為 None，在此情況下會使用 certifi.where () 。

uamqp_transport
bool

是否要使用 uamqp 程式庫作為基礎傳輸。 預設值為 False，而純 Python AMQP 程式庫將作為基礎傳輸。

範例

建立 ServiceBusClient 的新實例。


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

變數

fully_qualified_namespace
str

服務匯流排命名空間的完整主機名稱。 命名空間格式為： .servicebus.windows.net。

方法

close

關閉 ServiceBus 用戶端。 所有繁衍的傳送者、接收者和基礎連線都會關閉。
from_connection_string

從連接字串建立 ServiceBusClient。
get_queue_receiver

取得特定佇列的 ServiceBusReceiver。
get_queue_sender

取得特定佇列的 ServiceBusSender。
get_subscription_receiver

取得主題下特定訂用帳戶的 ServiceBusReceiver。
get_topic_sender

取得特定主題的 ServiceBusSender。

close

關閉 ServiceBus 用戶端。 所有繁衍的傳送者、接收者和基礎連線都會關閉。

close() -> None

傳回

無

from_connection_string

從連接字串建立 ServiceBusClient。

from_connection_string(conn_str: str, *, retry_total: int = 3, retry_backoff_factor: float = 0.8, retry_backoff_max: float = 120, retry_mode: str = 'exponential', **kwargs: Any) -> ServiceBusClient

參數

conn_str
str
必要

服務匯流排的連接字串。

logging_enable
bool

是否要將網路追蹤記錄輸出至記錄器。 預設值為 False。

transport_type
TransportType

將用於與服務匯流排服務通訊的傳輸通訊協定類型。 預設值為 TransportType.Amqp ，在此情況下會使用埠 5671。 如果網路環境中無法使用/封鎖埠 5671，則可改用 TransportType.AmqpOverWebsocket 來使用埠 443 進行通訊。

http_proxy
Dict

HTTP Proxy 設定。 這必須是具有下列索引鍵的字典： 'proxy_hostname' ( str 值) 和 'proxy_port' (int 值) 。 此外，也可能會出現下列金鑰： 'username'、'password'。

user_agent
str

如果指定，這會新增到內建使用者代理程式字串前面。

retry_total
int

發生錯誤時，嘗試取消復原失敗作業的嘗試總數。 預設值為 3。

retry_backoff_factor
float

重試之間第二個單位中的差異輪詢內部。 預設值為 0.8。

retry_backoff_max
float

第二個單位中的最大輪詢間隔。 預設值為 120。

retry_mode
str

重試嘗試之間的延遲行為。 支援的值為 'fixed' 或 'exponential'，其中預設值為 'exponential'。

custom_endpoint_address
str

用來建立服務匯流排服務的連線的自訂端點位址，允許透過任何應用程式閘道或其他主機環境所需的路徑路由傳送網路要求。 預設值為 None。 格式會像 「sb:// < custom_endpoint_hostname > ： < custom_endpoint_port > 」。 如果未在custom_endpoint_address中指定埠，預設會使用埠 443。

connection_verify
str

SSL 憑證之自訂CA_BUNDLE檔案的路徑，用來驗證連線端點的身分識別。 預設值為 None，在此情況下會使用 certifi.where () 。

uamqp_transport
bool

是否要使用 uamqp 程式庫作為基礎傳輸。 預設值為 False，而純 Python AMQP 程式庫將作為基礎傳輸。

傳回類型

ServiceBusClient

範例

從連接字串建立 ServiceBusClient 的新實例。


   import os
   from azure.servicebus import ServiceBusClient
   servicebus_connection_str = os.environ['SERVICEBUS_CONNECTION_STR']
   servicebus_client = ServiceBusClient.from_connection_string(conn_str=servicebus_connection_str)

get_queue_receiver

取得特定佇列的 ServiceBusReceiver。

get_queue_receiver(queue_name: str, *, session_id: str | ~typing.Literal[<ServiceBusSessionFilter.NEXT_AVAILABLE: 0>] | None = None, sub_queue: ~azure.servicebus._common.constants.ServiceBusSubQueue | str | None = None, receive_mode: ~azure.servicebus._common.constants.ServiceBusReceiveMode | str = ServiceBusReceiveMode.PEEK_LOCK, max_wait_time: float | None = None, auto_lock_renewer: ~azure.servicebus._common.auto_lock_renewer.AutoLockRenewer | None = None, prefetch_count: int = 0, **kwargs: ~typing.Any) -> ServiceBusReceiver

參數

queue_name
str
必要

用戶端所連線的特定服務匯流排佇列路徑。

session_id
str 或 <xref:azure.servicebus.NEXT_AVAILABLE_SESSION>

要接收的特定會話。 這必須指定給會話佇列，否則必須是 None。 若要接收來自下一個可用會話的訊息，請將此設定為 ~azure.servicebus.NEXT_AVAILABLE_SESSION。

sub_queue
str 或 ServiceBusSubQueue 或 None

如果指定，這個接收者的子佇列將會連線。 這包括DEAD_LETTER和TRANSFER_DEAD_LETTER佇列，保留無法傳遞至任何無法處理的接收者或訊息的訊息。 預設值為 None，這表示連接到主要佇列。 可以從 ServiceBusSubQueue 列舉或對等字串值 「deadletter」 和 「transferdeadletter」 指派值。

receive_mode
Union[ServiceBusReceiveMode, str]

要從實體擷取訊息的receive_mode。 這兩個選項PEEK_LOCK和RECEIVE_AND_DELETE。 使用 PEEK_LOCK 接收的訊息必須在指定的鎖定期間內解決，才能從佇列中移除訊息。 使用 RECEIVE_AND_DELETE 接收的訊息將會立即從佇列中移除，如果用戶端無法處理訊息，則無法後續拒絕或重新接收。 預設receive_mode為 PEEK_LOCK。

max_wait_time
Optional[float]

接收的訊息之間的逾時，之後接收者會自動停止接收。 預設值為 None，表示沒有逾時。 如果因為寫入逾時而發生連線錯誤，可能需要調整連線逾時值。 如需詳細資訊 ，請參閱socket_timeout 選擇性參數。

auto_lock_renewer
Optional[AutoLockRenewer]

您可以提供 ~azure.servicebus.AutoLockRenewer，讓訊息在回條時自動註冊。 如果接收者是會話接收者，則會改為套用至會話。

prefetch_count
int

每個對服務的要求要快取的訊息數目上限。 此設定僅適用于進階效能微調。 增加此值可改善訊息輸送量效能，但如果訊息處理速度不夠快，則會增加訊息在快取時到期的機會。 預設值為 0，這表示訊息會從服務接收，並一次處理一個。 如果prefetch_count為 0，ServiceBusReceiver.receive 會嘗試快取max_message_count (，如果服務的要求內) 。

client_identifier
str

用來唯一識別接收者實例的字串型識別碼。 服務匯流排會將它與某些錯誤訊息產生關聯，以便更輕鬆地相互關聯錯誤。 如果未指定，則會產生唯一識別碼。

socket_timeout
float

連接上基礎通訊端在傳送和接收資料之前應該等候的時間，以秒為單位。TransportType.Amqp 的預設值為 0.2，而 TransportType.AmqpOverWebsocket 的預設值為 1。 如果因為寫入逾時而發生連線錯誤，可能需要傳入大於預設值。

傳回類型

ServiceBusReceiver

範例

從 ServiceBusClient 建立 ServiceBusReceiver 的新實例。


   import os
   from azure.servicebus import ServiceBusClient
   servicebus_connection_str = os.environ['SERVICEBUS_CONNECTION_STR']
   queue_name = os.environ['SERVICEBUS_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

取得特定佇列的 ServiceBusSender。

get_queue_sender(queue_name: str, **kwargs: Any) -> ServiceBusSender

參數

queue_name
str
必要

用戶端所連線的特定服務匯流排佇列路徑。

client_identifier
str

字串型識別碼，可唯一識別傳送者實例。 服務匯流排會將它與某些錯誤訊息產生關聯，以便更輕鬆地相互關聯錯誤。 如果未指定，則會產生唯一識別碼。

socket_timeout
float

連接上基礎通訊端在傳送和接收資料之前應該等候的時間，以秒為單位。TransportType.Amqp 的預設值為 0.2，而 TransportType.AmqpOverWebsocket 的預設值為 1。 如果因為寫入逾時而發生連線錯誤，可能需要傳入大於預設值。

傳回

佇列傳送者。

傳回類型

ServiceBusSender

範例

從 ServiceBusClient 建立 ServiceBusSender 的新實例。


   import os
   from azure.servicebus import ServiceBusClient
   servicebus_connection_str = os.environ['SERVICEBUS_CONNECTION_STR']
   queue_name = os.environ['SERVICEBUS_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

取得主題下特定訂用帳戶的 ServiceBusReceiver。

get_subscription_receiver(topic_name: str, subscription_name: str, *, session_id: str | ~typing.Literal[<ServiceBusSessionFilter.NEXT_AVAILABLE: 0>] | None = None, sub_queue: ~azure.servicebus._common.constants.ServiceBusSubQueue | str | None = None, receive_mode: ~azure.servicebus._common.constants.ServiceBusReceiveMode | str = ServiceBusReceiveMode.PEEK_LOCK, max_wait_time: float | None = None, auto_lock_renewer: ~azure.servicebus._common.auto_lock_renewer.AutoLockRenewer | None = None, prefetch_count: int = 0, **kwargs: ~typing.Any) -> ServiceBusReceiver

參數

topic_name
str
必要

用戶端所連線的特定服務匯流排主題名稱。

subscription_name
str
必要

指定服務匯流排主題下的特定服務匯流排訂用帳戶名稱。

session_id
str 或 <xref:azure.servicebus.NEXT_AVAILABLE_SESSION>

要接收的特定會話。 這必須指定給會話訂用帳戶，否則必須是 None。 若要接收來自下一個可用會話的訊息，請將此設定為 ~azure.servicebus.NEXT_AVAILABLE_SESSION。

sub_queue
str 或 ServiceBusSubQueue 或 None

如果指定，這個接收者的子佇列將會連線。 這包括DEAD_LETTER和TRANSFER_DEAD_LETTER佇列，保留無法傳遞至任何無法處理的接收者或訊息的訊息。 預設值為 None，這表示連接到主要佇列。 可以從 ServiceBusSubQueue 列舉或對等字串值 「deadletter」 和 「transferdeadletter」 指派值。

receive_mode
Union[ServiceBusReceiveMode, str]

要從實體擷取訊息的receive_mode。 這兩個選項PEEK_LOCK和RECEIVE_AND_DELETE。 使用 PEEK_LOCK 接收的訊息必須在指定的鎖定期間內解決，才能從訂用帳戶中移除訊息。 使用 RECEIVE_AND_DELETE 接收的訊息將會立即從訂用帳戶中移除，如果用戶端無法處理訊息，則無法後續拒絕或重新接收。 預設receive_mode為 PEEK_LOCK。

max_wait_time
Optional[float]

接收的訊息之間的逾時，之後接收者會自動停止接收。 預設值為 None，表示沒有逾時。 如果因為寫入逾時而發生連線錯誤，可能需要調整連線逾時值。 如需詳細資訊 ，請參閱socket_timeout 選擇性參數。

auto_lock_renewer
Optional[AutoLockRenewer]

您可以提供 ~azure.servicebus.AutoLockRenewer，讓訊息在回條時自動註冊。 如果接收者是會話接收者，則會改為套用至會話。

prefetch_count
int

每個對服務的要求要快取的訊息數目上限。 此設定僅適用于進階效能微調。 增加此值可改善訊息輸送量效能，但如果訊息處理速度不夠快，則會增加訊息在快取時到期的機會。 預設值為 0，這表示訊息會從服務接收，並一次處理一個。 如果prefetch_count為 0，ServiceBusReceiver.receive 會嘗試快取max_message_count (，如果服務的要求內) 。

client_identifier
str

用來唯一識別接收者實例的字串型識別碼。 服務匯流排會將它與某些錯誤訊息產生關聯，以便更輕鬆地相互關聯錯誤。 如果未指定，則會產生唯一識別碼。

socket_timeout
float

連接上基礎通訊端在傳送和接收資料之前應該等候的時間，以秒為單位。TransportType.Amqp 的預設值為 0.2，而 TransportType.AmqpOverWebsocket 的預設值為 1。 如果因為寫入逾時而發生連線錯誤，可能需要傳入大於預設值。

傳回類型

ServiceBusReceiver

範例

從 ServiceBusClient 建立 ServiceBusReceiver 的新實例。


   import os
   from azure.servicebus import ServiceBusClient
   servicebus_connection_str = os.environ['SERVICEBUS_CONNECTION_STR']
   topic_name = os.environ["SERVICEBUS_TOPIC_NAME"]
   subscription_name = os.environ["SERVICEBUS_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

取得特定主題的 ServiceBusSender。

get_topic_sender(topic_name: str, **kwargs: Any) -> ServiceBusSender

參數

topic_name
str
必要

用戶端所連線之特定服務匯流排主題的路徑。

client_identifier
str

字串型識別碼，可唯一識別傳送者實例。 服務匯流排會將它與某些錯誤訊息產生關聯，以便更輕鬆地相互關聯錯誤。 如果未指定，則會產生唯一識別碼。

socket_timeout
float

連接上基礎通訊端在傳送和接收資料之前應該等候的時間，以秒為單位。TransportType.Amqp 的預設值為 0.2，而 TransportType.AmqpOverWebsocket 的預設值為 1。 如果因為寫入逾時而發生連線錯誤，可能需要傳入大於預設值。

傳回

主題傳送者。

傳回類型

ServiceBusSender

範例

從 ServiceBusClient 建立 ServiceBusSender 的新實例。


   import os
   from azure.servicebus import ServiceBusClient
   servicebus_connection_str = os.environ['SERVICEBUS_CONNECTION_STR']
   topic_name = os.environ['SERVICEBUS_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)