Condividi tramite

ServiceBusClient Classe

  • Riferimento

La classe ServiceBusClient definisce un'interfaccia di alto livello per ottenere ServiceBusSender e ServiceBusReceiver.

Ereditarietà
builtins.object
ServiceBusClient

Costruttore

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

Parametri

fully_qualified_namespace
str
Necessario

Nome host completo per lo spazio dei nomi del bus di servizio. Il formato dello spazio dei nomi è: .servicebus.windows.net.

credential
AsyncTokenCredential oppure AzureSasCredential oppure AzureNamedKeyCredential
Necessario

Oggetto credenziale usato per l'autenticazione che implementa una particolare interfaccia per ottenere i token. Accetta oggetti credenziali generati dalla libreria azure-identity e oggetti che implementano il metodo *get_token(self, scopes) o, in alternativa, è possibile specificare anche AzureSasCredential.

logging_enable
bool

Indica se restituire i log di traccia di rete al logger. L'impostazione predefinita è False.

transport_type
TransportType

Tipo di protocollo di trasporto che verrà utilizzato per comunicare con il servizio del bus di servizio. Il valore predefinito è TransportType.Amqp nel qual caso viene usata la porta 5671. Se la porta 5671 non è disponibile/bloccata nell'ambiente di rete, è possibile usare TransportType.AmqpOverWebsocket che usa la porta 443 per la comunicazione.

http_proxy
Dict

Impostazioni proxy HTTP. Deve essere un dizionario con le chiavi seguenti: 'proxy_hostname' (valore str) e 'proxy_port' (valore int). Inoltre, possono essere presenti le chiavi seguenti: 'username', 'password'.

user_agent
str

Se specificato, verrà aggiunto davanti alla stringa predefinita dell'agente utente.

retry_total
int

Numero totale di tentativi di rollforward di un'operazione non riuscita quando si verifica un errore. Il valore predefinito è 3.

retry_backoff_factor
float

Back-off differenziale interno nell'unità di secondo tra i tentativi. Il valore predefinito è 0,8.

retry_backoff_max
float

Intervallo massimo di back-off nell'unità di secondo. Il valore predefinito è 120.

retry_mode
str

Comportamento di ritardo tra i tentativi. I valori supportati sono "fixed" o "esponenziale", dove default è "esponenziale".

custom_endpoint_address
str

Indirizzo dell'endpoint personalizzato da usare per stabilire una connessione al servizio del bus di servizio, consentendo l'instradamento delle richieste di rete tramite qualsiasi gateway applicazione o altri percorsi necessari per l'ambiente host. L'impostazione predefinita è None. Il formato sarà simile a "sb://< custom_endpoint_hostname>:<custom_endpoint_port>". Se la porta non è specificata nel custom_endpoint_address, per impostazione predefinita verrà usata la porta 443.

connection_verify
str

Percorso del file di CA_BUNDLE personalizzato del certificato SSL usato per autenticare l'identità dell'endpoint di connessione. Il valore predefinito è Nessuno nel qual caso verrà usato certifi.where().

uamqp_transport
bool

Indica se usare la libreria uamqp come trasporto sottostante. Il valore predefinito è False e la libreria AMQP Pure Python verrà usata come trasporto sottostante.

Esempio

Creare una nuova istanza di ServiceBusClient.


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

Variabili

fully_qualified_namespace
str

Nome host completo per lo spazio dei nomi del bus di servizio. Il formato dello spazio dei nomi è: .servicebus.windows.net.

Metodi

close

Chiudere il client ServiceBus. Tutti i mittenti, i ricevitori e la connessione sottostante generati verranno arrestati.
from_connection_string

Creare un ServiceBusClient da una stringa di connessione.
get_queue_receiver

Ottenere ServiceBusReceiver per la coda specifica.
get_queue_sender

Ottenere ServiceBusSender per la coda specifica.
get_subscription_receiver

Ottenere ServiceBusReceiver per la sottoscrizione specifica nell'argomento.
get_topic_sender

Ottenere ServiceBusSender per l'argomento specifico.

close

Chiudere il client ServiceBus. Tutti i mittenti, i ricevitori e la connessione sottostante generati verranno arrestati.

async close() -> None

Restituisce

Nessuno

from_connection_string

Creare un ServiceBusClient da una stringa di connessione.

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

Parametri

conn_str
str
Necessario

Stringa di connessione di un bus di servizio.

logging_enable
bool

Indica se restituire i log di traccia di rete al logger. L'impostazione predefinita è False.

transport_type
TransportType

Tipo di protocollo di trasporto che verrà utilizzato per comunicare con il servizio del bus di servizio. Il valore predefinito è TransportType.Amqp nel qual caso viene usata la porta 5671. Se la porta 5671 non è disponibile/bloccata nell'ambiente di rete, è possibile usare TransportType.AmqpOverWebsocket che usa la porta 443 per la comunicazione.

http_proxy
Dict

Impostazioni proxy HTTP. Deve essere un dizionario con le chiavi seguenti: 'proxy_hostname' (valore str) e 'proxy_port' (valore int). Inoltre, possono essere presenti le chiavi seguenti: 'username', 'password'.

user_agent
str

Se specificato, verrà aggiunto davanti alla stringa predefinita dell'agente utente.

retry_total
int

Numero totale di tentativi di rollforward di un'operazione non riuscita quando si verifica un errore. Il valore predefinito è 3.

retry_backoff_factor
float

Back-off differenziale interno nell'unità di secondo tra i tentativi. Il valore predefinito è 0,8.

retry_backoff_max
float

Intervallo massimo di back-off nell'unità di secondo. Il valore predefinito è 120.

retry_mode
str

Comportamento di ritardo tra i tentativi. I valori supportati sono "fixed" o "esponenziale", dove il valore predefinito è "esponenziale".

custom_endpoint_address
str

Indirizzo dell'endpoint personalizzato da usare per stabilire una connessione al servizio del bus di servizio, consentendo l'instradamento delle richieste di rete tramite qualsiasi gateway applicazione o altri percorsi necessari per l'ambiente host. L'impostazione predefinita è None. Il formato sarà simile a "sb://< custom_endpoint_hostname>:<custom_endpoint_port>". Se la porta non è specificata nella custom_endpoint_address, per impostazione predefinita verrà usata la porta 443.

connection_verify
str

Percorso del file di CA_BUNDLE personalizzato del certificato SSL usato per autenticare l'identità dell'endpoint di connessione. Il valore predefinito è Nessuno nel qual caso verrà usato certifi.where().

uamqp_transport
bool

Indica se usare la libreria uamqp come trasporto sottostante. Il valore predefinito è False e la libreria AMQP Pure Python verrà usata come trasporto sottostante.

Tipo restituito

ServiceBusClient

Esempio

Creare una nuova istanza di ServiceBusClient dalla stringa di connessione.


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

get_queue_receiver

Ottenere ServiceBusReceiver per la coda specifica.

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

Parametri

queue_name
str
Necessario

Percorso di coda del bus di servizio specifico a cui si connette il client.

session_id
str oppure <xref:azure.servicebus.NEXT_AVAILABLE_SESSION> oppure None

Sessione specifica da cui ricevere. Deve essere specificato per una coda con sessione. In caso contrario, deve essere Nessuno. Per ricevere messaggi dalla sessione disponibile successiva, impostarla su ~azure.servicebus.NEXT_AVAILABLE_SESSION.

sub_queue
str oppure ServiceBusSubQueue oppure None

Se specificato, la sottoquery a cui si connetterà il ricevitore. Sono incluse le code DEAD_LETTER e TRANSFER_DEAD_LETTER, che contiene messaggi che non possono essere recapitati a nessun destinatario o a messaggi che non possono essere elaborati. Il valore predefinito è Nessuno, vale a dire connettersi alla coda primaria. È possibile assegnare valori da enumerazione ServiceBusSubQueue o valori stringa equivalenti "deadletter" e "transferdeadletter".

receive_mode
Union[ServiceBusReceiveMode, str]

Modalità con cui i messaggi verranno recuperati dall'entità. Le due opzioni sono PEEK_LOCK e RECEIVE_AND_DELETE. I messaggi ricevuti con PEEK_LOCK devono essere risolti entro un determinato periodo di blocco prima che vengano rimossi dalla coda. I messaggi ricevuti con RECEIVE_AND_DELETE verranno immediatamente rimossi dalla coda e non potranno essere successivamente rifiutati o ricevuti nuovamente se il client non riesce a elaborare il messaggio. La modalità predefinita è PEEK_LOCK.

max_wait_time
Optional[float]

Timeout in secondi tra i messaggi ricevuti dopo il quale il ricevitore smetterà di ricevere automaticamente. Il valore predefinito è None, ovvero nessun timeout. Se si verificano errori di connessione a causa del timeout della scrittura, potrebbe essere necessario regolare il valore di timeout della connessione. Per altri dettagli, vedere il parametro facoltativo socket_timeout .

auto_lock_renewer
Optional[AutoLockRenewer]

È possibile specificare ~azure.servicebus.aio.AutoLockRenewer in modo che i messaggi vengano registrati automaticamente alla ricezione. Se il ricevitore è un ricevitore di sessione, verrà applicato alla sessione.

prefetch_count
int

Numero massimo di messaggi da memorizzare nella cache con ogni richiesta al servizio. Questa impostazione è solo per l'ottimizzazione avanzata delle prestazioni. L'aumento di questo valore migliorerà le prestazioni della velocità effettiva dei messaggi, ma aumenterà la probabilità che i messaggi scadano mentre vengono memorizzati nella cache se non vengono elaborati abbastanza velocemente. Il valore predefinito è 0, ovvero i messaggi verranno ricevuti dal servizio ed elaborati uno alla volta. Nel caso di prefetch_count 0, ServiceBusReceiver.receive tenterà di memorizzare nella cache max_message_count (se specificato) all'interno della richiesta al servizio.

client_identifier
str

Identificatore basato su stringa per identificare in modo univoco l'istanza del ricevitore. Il bus di servizio lo associa ad alcuni messaggi di errore per facilitare la correlazione degli errori. Se non specificato, verrà generato un ID univoco.

socket_timeout
float

Tempo in secondi in cui il socket sottostante sulla connessione deve attendere quando si inviano e ricevono dati prima del timeout. Il valore predefinito è 0.2 per TransportType.Amqp e 1 per TransportType.AmqpOverWebsocket. Se si verificano errori di connessione a causa del timeout della scrittura, potrebbe essere necessario passare un valore maggiore di quello predefinito.

Tipo restituito

ServiceBusReceiver

Esempio

Creare una nuova istanza di ServiceBusSender da ServiceBusClient.


   import os
   from azure.servicebus.aio 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)
   async with servicebus_client:
       queue_receiver = servicebus_client.get_queue_receiver(queue_name=queue_name)

get_queue_sender

Ottenere ServiceBusSender per la coda specifica.

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

Parametri

queue_name
str
Necessario

Percorso di coda del bus di servizio specifico a cui si connette il client.

client_identifier
str

Identificatore basato su stringa per identificare in modo univoco l'istanza del mittente. Il bus di servizio lo associa ad alcuni messaggi di errore per facilitare la correlazione degli errori. Se non specificato, verrà generato un ID univoco.

socket_timeout
float

Tempo in secondi in cui il socket sottostante sulla connessione deve attendere quando si inviano e ricevono dati prima del timeout. Il valore predefinito è 0.2 per TransportType.Amqp e 1 per TransportType.AmqpOverWebsocket. Se si verificano errori di connessione a causa del timeout di scrittura, potrebbe essere necessario passare un valore maggiore di quello predefinito.

Restituisce

Mittente della coda.

Tipo restituito

ServiceBusSender

Esempio

Creare una nuova istanza di ServiceBusClient dalla stringa di connessione.


   import os
   from azure.servicebus.aio 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)
   async with servicebus_client:
       queue_sender = servicebus_client.get_queue_sender(queue_name=queue_name)

get_subscription_receiver

Ottenere ServiceBusReceiver per la sottoscrizione specifica nell'argomento.

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

Parametri

topic_name
str
Necessario

Nome dell'argomento specifico del bus di servizio a cui si connette il client.

subscription_name
str
Necessario

Nome della sottoscrizione specifica del bus di servizio nell'argomento del bus di servizio specificato.

session_id
str oppure <xref:azure.servicebus.NEXT_AVAILABLE_SESSION> oppure None

Sessione specifica da cui ricevere. Questa operazione deve essere specificata per una sottoscrizione con sessione, in caso contrario, deve essere Nessuna. Per ricevere messaggi dalla sessione successiva disponibile, impostare questa opzione su ~azure.servicebus.NEXT_AVAILABLE_SESSION.

sub_queue
str oppure ServiceBusSubQueue oppure None

Se specificato, la sottoqueue questo ricevitore si connetterà. Ciò include le code DEAD_LETTER e TRANSFER_DEAD_LETTER, contiene messaggi che non possono essere recapitati a alcun ricevitore o messaggi che non possono essere elaborati. Il valore predefinito è Nessuno, ovvero connettersi alla coda primaria. È possibile assegnare valori da ServiceBusSubQueue o valori di stringa equivalenti "deadletter" e "transferdeadletter".

receive_mode
Union[ServiceBusReceiveMode, str]

Modalità con cui verranno recuperati i messaggi dall'entità. Le due opzioni sono PEEK_LOCK e RECEIVE_AND_DELETE. I messaggi ricevuti con PEEK_LOCK devono essere risolti entro un determinato periodo di blocco prima che vengano rimossi dalla sottoscrizione. I messaggi ricevuti con RECEIVE_AND_DELETE verranno immediatamente rimossi dalla sottoscrizione e non possono essere successivamente rifiutati o re-ricevuti se il client non riesce a elaborare il messaggio. La modalità predefinita è PEEK_LOCK.

max_wait_time
Optional[float]

Timeout in secondi tra i messaggi ricevuti dopo il quale il ricevitore interrompe automaticamente la ricezione. Il valore predefinito è Nessuno, ovvero nessun timeout. Se si verificano errori di connessione a causa del timeout di scrittura, potrebbe essere necessario modificare il valore del timeout della connessione. Per altre informazioni, vedere il parametro facoltativo socket_timeout .

auto_lock_renewer
Optional[AutoLockRenewer]

È possibile specificare ~azure.servicebus.aio.AutoLockRenewer in modo che i messaggi vengano registrati automaticamente nella ricezione. Se il ricevitore è un ricevitore di sessione, verrà applicato invece alla sessione.

prefetch_count
int

Numero massimo di messaggi da memorizzare nella cache con ogni richiesta al servizio. Questa impostazione è solo per l'ottimizzazione avanzata delle prestazioni. L'aumento di questo valore migliora le prestazioni della velocità effettiva dei messaggi, ma aumenta la probabilità che i messaggi scadano mentre vengono memorizzati nella cache se non vengono elaborati abbastanza velocemente. Il valore predefinito è 0, ovvero i messaggi verranno ricevuti dal servizio e elaborati uno alla volta. Nel caso di prefetch_count 0, ServiceBusReceiver.receive tenterà di memorizzare nella cache max_message_count (se specificato) all'interno della richiesta al servizio.

client_identifier
str

Identificatore basato su stringa per identificare in modo univoco l'istanza del ricevitore. Il bus di servizio lo associa ad alcuni messaggi di errore per semplificare la correlazione degli errori. Se non specificato, verrà generato un ID univoco.

socket_timeout
float

Tempo in secondi in cui il socket sottostante sulla connessione deve attendere quando si inviano e ricevono dati prima del timeout. Il valore predefinito è 0.2 per TransportType.Amqp e 1 per TransportType.AmqpOverWebsocket. Se si verificano errori di connessione a causa del timeout di scrittura, potrebbe essere necessario passare un valore maggiore di quello predefinito.

Tipo restituito

ServiceBusReceiver

Esempio

Creare una nuova istanza di ServiceBusReceiver da ServiceBusClient.


   import os
   from azure.servicebus.aio 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)
   async with servicebus_client:
       subscription_receiver = servicebus_client.get_subscription_receiver(
           topic_name=topic_name,
           subscription_name=subscription_name,
       )

get_topic_sender

Ottenere ServiceBusSender per l'argomento specifico.

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

Parametri

topic_name
str
Necessario

Percorso di un argomento specifico del bus di servizio a cui si connette il client.

client_identifier
str

Identificatore basato su stringa per identificare in modo univoco l'istanza del mittente. Il bus di servizio lo associa ad alcuni messaggi di errore per semplificare la correlazione degli errori. Se non specificato, verrà generato un ID univoco.

socket_timeout
float

Tempo in secondi in cui il socket sottostante sulla connessione deve attendere quando si inviano e ricevono dati prima del timeout. Il valore predefinito è 0.2 per TransportType.Amqp e 1 per TransportType.AmqpOverWebsocket. Se si verificano errori di connessione a causa del timeout di scrittura, potrebbe essere necessario passare un valore maggiore di quello predefinito.

Restituisce

Mittente di argomenti.

Tipo restituito

ServiceBusSender

Esempio

Creare una nuova istanza di ServiceBusSender da ServiceBusClient.


   import os
   from azure.servicebus.aio 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)
   async with servicebus_client:
       topic_sender = servicebus_client.get_topic_sender(topic_name=topic_name)