Partilhar via


ServiceBusReceiver Classe

A classe ServiceBusReceiver define uma interface de alto nível para receber mensagens do Azure Service Bus Fila ou Subscrição de Tópico.

Os dois canais principais para o recibo de mensagens são receber() para fazer um único pedido de mensagens e assíncrono para a mensagem no recetor: para receber continuamente mensagens recebidas de forma contínua.

Utilize o método ~azure.servicebus.aio.ServiceBusClient get_<queue/subscription>_receiver para criar uma instância do ServiceBusReceiver.

Herança
ServiceBusReceiver
azure.servicebus.aio._base_handler_async.BaseHandler
ServiceBusReceiver
azure.servicebus._common.receiver_mixins.ReceiverMixin
ServiceBusReceiver

Construtor

ServiceBusReceiver(fully_qualified_namespace: str, credential: AsyncTokenCredential | AzureSasCredential | AzureNamedKeyCredential, *, queue_name: str | None = None, topic_name: str | None = None, subscription_name: str | None = None, receive_mode: ServiceBusReceiveMode | str = ServiceBusReceiveMode.PEEK_LOCK, max_wait_time: float | None = None, auto_lock_renewer: AutoLockRenewer | None = None, prefetch_count: int = 0, **kwargs: Any)

Parâmetros

fully_qualified_namespace
str
Necessário

O nome de anfitrião completamente qualificado para o espaço de nomes do Service Bus. O formato do espaço de nomes é: .servicebus.windows.net.

credential
AsyncTokenCredential ou AzureSasCredential ou AzureNamedKeyCredential
Necessário

O objeto de credencial utilizado para autenticação que implementa uma interface específica para obter tokens. Aceita objetos de credenciais gerados pela biblioteca de identidades do azure e objetos que implementam o método *get_token(auto, âmbitos) ou, em alternativa, também pode ser fornecido um AzureSasCredential.

queue_name
str

O caminho da fila específica do Service Bus à qual o cliente se liga.

topic_name
str

O caminho do Tópico específico do Service Bus que contém a Subscrição à qual o cliente se liga.

subscription_name
str

O caminho da Subscrição específica do Service Bus no Tópico especificado ao qual o cliente se liga.

receive_mode
Union[ServiceBusReceiveMode, str]

O modo com o qual as mensagens serão obtidas da entidade. As duas opções são PEEK_LOCK e RECEIVE_AND_DELETE. As mensagens recebidas com PEEK_LOCK têm de ser resolvidas num determinado período de bloqueio antes de serem removidas da fila. As mensagens recebidas com RECEIVE_AND_DELETE serão imediatamente removidas da fila e não poderão ser posteriormente abandonadas ou novamente recebidas se o cliente não conseguir processar a mensagem. O modo predefinido é PEEK_LOCK.

max_wait_time
Optional[float]

O tempo limite em segundos entre as mensagens recebidas após as quais o recetor deixará de receber automaticamente. O valor predefinido é Nenhum, o que significa que não há tempo limite.

logging_enable
bool

Se pretende gerar registos de rastreio de rede para o logger. A predefinição é Falso.

transport_type
TransportType

O tipo de protocolo de transporte que será utilizado para comunicar com o serviço Service Bus. A predefinição é TransportType.Amqp.

http_proxy
Dict

Definições de proxy HTTP. Este tem de ser um dicionário com as seguintes chaves: "proxy_hostname" (valor de str) e "proxy_port" (valor int). Além disso, também podem estar presentes as seguintes chaves: "nome de utilizador", "palavra-passe".

user_agent
str

Se especificado, este procedimento será adicionado à frente da cadeia de agente de utilizador incorporada.

auto_lock_renewer
Optional[AutoLockRenewer]

Pode ser fornecido um ~azure.servicebus.aio.AutoLockRenewer para que as mensagens sejam registadas automaticamente no recibo. Se o recetor for um recetor de sessão, será aplicado à sessão.

prefetch_count
int

O número máximo de mensagens a colocar em cache com cada pedido ao serviço. Esta definição destina-se apenas à otimização avançada do desempenho. Aumentar este valor irá melhorar o desempenho do débito de mensagens, mas aumentará a probabilidade de as mensagens expirarem enquanto forem colocadas em cache se não forem processadas com rapidez suficiente. O valor predefinido é 0, o que significa que as mensagens serão recebidas do serviço e processadas uma de cada vez. No caso de prefetch_count ser 0, o ServiceBusReceiver.receive tentaria colocar em cache max_message_count (se for fornecido) no respetivo pedido ao serviço.

client_identifier
str

Um identificador baseado em cadeias para identificar exclusivamente a instância do cliente. O Service Bus irá associá-lo a algumas mensagens de erro para facilitar a correlação de erros. Se não for especificado, será gerado um ID exclusivo.

socket_timeout
float

O tempo em segundos que o socket subjacente na ligação deve aguardar ao enviar e receber dados antes de exceder o tempo limite. O valor predefinido é 0,2 para TransportType.Amqp e 1 para TransportType.AmqpOverWebsocket. Se estiverem a ocorrer erros de ligação devido ao tempo limite de escrita, poderá ser necessário transmitir um valor maior do que o predefinido.

Variáveis

fully_qualified_namespace
str

O nome de anfitrião completamente qualificado para o espaço de nomes do Service Bus. O formato do espaço de nomes é: .servicebus.windows.net.

entity_path
str

O caminho da entidade à qual o cliente se liga.

Métodos

abandon_message

Abandone a mensagem.

Esta mensagem será devolvida à fila e disponibilizada para ser recebida novamente.

close
complete_message

Conclua a mensagem.

Esta ação remove a mensagem da fila.

dead_letter_message

Mova a mensagem para a fila Carta Morta.

A fila Letra Morta é uma sub-fila que pode ser utilizada para armazenar mensagens que não foram processadas corretamente ou que, de outro modo, requerem uma inspeção ou processamento adicionais. A fila também pode ser configurada para enviar mensagens expiradas para a fila Carta Morta.

defer_message

Adia a mensagem.

Esta mensagem permanecerá na fila, mas tem de ser pedida especificamente pelo respetivo número de sequência para ser recebida.

peek_messages

Procurar mensagens atualmente pendentes na fila.

As mensagens pré-visualizadas não são removidas da fila, nem estão bloqueadas. Não podem ser concluídas, diferidas ou não entregues.

receive_deferred_messages

Receber mensagens que tenham sido diferidas anteriormente.

Ao receber mensagens diferidas de uma entidade particionada, todos os números de sequência fornecidos têm de ser mensagens da mesma partição.

receive_messages

Receba um lote de mensagens ao mesmo tempo.

Esta abordagem é ideal se quiser processar várias mensagens em simultâneo ou efetuar uma receção ad-hoc como uma única chamada.

Tenha em atenção que o número de mensagens obtidas num único lote depende se prefetch_count foi definido para o recetor. Se prefetch_count não estiver definido para o recetor, o recetor tentará colocar em cache max_message_count (se for fornecido) mensagens no pedido ao serviço.

Esta chamada atribuirá prioridades ao retorno rápido sobre a reunião de um tamanho de lote especificado, pelo que será devolvida assim que pelo menos uma mensagem for recebida e existir uma lacuna nas mensagens recebidas, independentemente do tamanho do lote especificado.

renew_message_lock

Renove o bloqueio de mensagens.

Esta ação irá manter o bloqueio na mensagem para garantir que não é devolvido à fila para ser novamente processada.

Para concluir (ou resolver) a mensagem, o bloqueio tem de ser mantido e não pode já ter expirado; não é possível renovar um bloqueio expirado.

As mensagens recebidas através do modo RECEIVE_AND_DELETE não estão bloqueadas e, por conseguinte, não podem ser renovadas. Esta operação só está disponível para mensagens sem sessão.

abandon_message

Abandone a mensagem.

Esta mensagem será devolvida à fila e disponibilizada para ser recebida novamente.

async abandon_message(message: ServiceBusReceivedMessage) -> None

Parâmetros

message
ServiceBusReceivedMessage
Necessário

A mensagem recebida a ser abandonada.

Tipo de retorno

Exceções

azure.servicebus.exceptions.MessageAlreadySettled if the message has been settled.
azure.servicebus.exceptions.SessionLockLostError if session lock has already expired.
azure.servicebus.exceptions.ServiceBusError when errors happen.

Exemplos

Abandonar uma mensagem recebida.


       messages = await servicebus_receiver.receive_messages(max_wait_time=5)
       for message in messages:
           await servicebus_receiver.abandon_message(message)

close

async close() -> None

Exceções

azure.servicebus.exceptions.MessageAlreadySettled if the message has been settled.
azure.servicebus.exceptions.SessionLockLostError if session lock has already expired.
azure.servicebus.exceptions.ServiceBusError when errors happen.

complete_message

Conclua a mensagem.

Esta ação remove a mensagem da fila.

async complete_message(message: ServiceBusReceivedMessage) -> None

Parâmetros

message
ServiceBusReceivedMessage
Necessário

A mensagem recebida a concluir.

Tipo de retorno

Exceções

azure.servicebus.exceptions.MessageAlreadySettled if the message has been settled.
azure.servicebus.exceptions.SessionLockLostError if session lock has already expired.
azure.servicebus.exceptions.ServiceBusError when errors happen.

Exemplos

Conclua uma mensagem recebida.


       messages = await servicebus_receiver.receive_messages(max_wait_time=5)
       for message in messages:
           await servicebus_receiver.complete_message(message)

dead_letter_message

Mova a mensagem para a fila Carta Morta.

A fila Letra Morta é uma sub-fila que pode ser utilizada para armazenar mensagens que não foram processadas corretamente ou que, de outro modo, requerem uma inspeção ou processamento adicionais. A fila também pode ser configurada para enviar mensagens expiradas para a fila Carta Morta.

async dead_letter_message(message: ServiceBusReceivedMessage, reason: str | None = None, error_description: str | None = None) -> None

Parâmetros

message
ServiceBusReceivedMessage
Necessário

A mensagem recebida a ser enviada sem carta.

reason
Optional[str]
valor predefinido: None

O motivo para escrever a mensagem sem cartas.

error_description
Optional[str]
valor predefinido: None

A descrição detalhada do erro para escrever a mensagem sem letras.

Tipo de retorno

Exceções

azure.servicebus.exceptions.MessageAlreadySettled if the message has been settled.
azure.servicebus.exceptions.SessionLockLostError if session lock has already expired.
azure.servicebus.exceptions.ServiceBusError when errors happen.

Exemplos

Carta morta uma mensagem recebida.


       messages = await servicebus_receiver.receive_messages(max_wait_time=5)
       for message in messages:
           await servicebus_receiver.dead_letter_message(message)

defer_message

Adia a mensagem.

Esta mensagem permanecerá na fila, mas tem de ser pedida especificamente pelo respetivo número de sequência para ser recebida.

async defer_message(message: ServiceBusReceivedMessage) -> None

Parâmetros

message
ServiceBusReceivedMessage
Necessário

A mensagem recebida a ser diferida.

Tipo de retorno

Exceções

azure.servicebus.exceptions.MessageAlreadySettled if the message has been settled.
azure.servicebus.exceptions.SessionLockLostError if session lock has already expired.
azure.servicebus.exceptions.ServiceBusError when errors happen.

Exemplos

Adie uma mensagem recebida.


       messages = await servicebus_receiver.receive_messages(max_wait_time=5)
       for message in messages:
           await servicebus_receiver.defer_message(message)

peek_messages

Procurar mensagens atualmente pendentes na fila.

As mensagens pré-visualizadas não são removidas da fila, nem estão bloqueadas. Não podem ser concluídas, diferidas ou não entregues.

async peek_messages(max_message_count: int = 1, *, sequence_number: int = 0, timeout: float | None = None, **kwargs: Any) -> List[ServiceBusReceivedMessage]

Parâmetros

max_message_count
int
valor predefinido: 1

O número máximo de mensagens a experimentar e a pré-visualizar. O valor predefinido é 1.

sequence_number
int

Um número de sequência de mensagens a partir do qual começar a navegar mensagens.

timeout
Optional[float]

O tempo limite total da operação em segundos, incluindo todas as repetições. Se especificado, o valor tem de ser superior a 0. O valor predefinido é Nenhum, o que significa que não há tempo limite.

Devoluções

Uma lista de objetos ~azure.servicebus.ServiceBusReceivedMessage.

Tipo de retorno

Exceções

azure.servicebus.exceptions.MessageAlreadySettled if the message has been settled.
azure.servicebus.exceptions.SessionLockLostError if session lock has already expired.
azure.servicebus.exceptions.ServiceBusError when errors happen.

Exemplos

Pré-visualizar mensagens na fila.


   async with servicebus_receiver:
       messages = await servicebus_receiver.peek_messages()
       for message in messages:
           print(str(message))

receive_deferred_messages

Receber mensagens que tenham sido diferidas anteriormente.

Ao receber mensagens diferidas de uma entidade particionada, todos os números de sequência fornecidos têm de ser mensagens da mesma partição.

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

Parâmetros

sequence_numbers
Union[int, list[int]]
Necessário

Uma lista dos números de sequência de mensagens que foram diferidas.

timeout
Optional[float]

O tempo limite total da operação em segundos, incluindo todas as repetições. Se especificado, o valor tem de ser superior a 0. O valor predefinido é Nenhum, o que significa que não há tempo limite.

Devoluções

Uma lista das mensagens recebidas.

Tipo de retorno

list[<xref:azure.servicebus.aio.ServiceBusReceivedMessage>]

Exceções

azure.servicebus.exceptions.MessageAlreadySettled if the message has been settled.
azure.servicebus.exceptions.SessionLockLostError if session lock has already expired.
azure.servicebus.exceptions.ServiceBusError when errors happen.

Exemplos

Receber mensagens diferidas do ServiceBus.


   async with servicebus_receiver:
       deferred_sequenced_numbers = []
       messages = await servicebus_receiver.receive_messages(max_wait_time=5)
       for message in messages:
           deferred_sequenced_numbers.append(message.sequence_number)
           print(str(message))
           await servicebus_receiver.defer_message(message)

       received_deferred_msg = await servicebus_receiver.receive_deferred_messages(
           sequence_numbers=deferred_sequenced_numbers
       )

       for message in received_deferred_msg:
           await servicebus_receiver.complete_message(message)

receive_messages

Receba um lote de mensagens ao mesmo tempo.

Esta abordagem é ideal se quiser processar várias mensagens em simultâneo ou efetuar uma receção ad-hoc como uma única chamada.

Tenha em atenção que o número de mensagens obtidas num único lote depende se prefetch_count foi definido para o recetor. Se prefetch_count não estiver definido para o recetor, o recetor tentará colocar em cache max_message_count (se for fornecido) mensagens no pedido ao serviço.

Esta chamada atribuirá prioridades ao retorno rápido sobre a reunião de um tamanho de lote especificado, pelo que será devolvida assim que pelo menos uma mensagem for recebida e existir uma lacuna nas mensagens recebidas, independentemente do tamanho do lote especificado.

async receive_messages(max_message_count: int | None = 1, max_wait_time: float | None = None) -> List[ServiceBusReceivedMessage]

Parâmetros

max_message_count
Optional[int]
valor predefinido: 1

Número máximo de mensagens no lote. O número real devolvido dependerá do tamanho prefetch_count e da taxa de transmissão de entrada. A definição para Nenhum dependerá totalmente da configuração de pré-correspondência. O valor predefinido é 1.

max_wait_time
Optional[float]
valor predefinido: None

Tempo máximo para aguardar em segundos pela chegada da primeira mensagem. Se não forem recebidas mensagens e não for especificado nenhum tempo limite, esta chamada só será devolvida quando a ligação estiver fechada. Se for especificado e não forem apresentadas mensagens dentro do período de tempo limite, será devolvida uma lista vazia.

Devoluções

Uma lista de mensagens recebidas. Se não existirem mensagens disponíveis, esta será uma lista vazia.

Tipo de retorno

list[<xref:azure.servicebus.aio.ServiceBusReceivedMessage>]

Exceções

azure.servicebus.exceptions.MessageAlreadySettled if the message has been settled.
azure.servicebus.exceptions.SessionLockLostError if session lock has already expired.
azure.servicebus.exceptions.ServiceBusError when errors happen.

Exemplos

Receber mensagens do ServiceBus.


   async with servicebus_receiver:
       messages = await servicebus_receiver.receive_messages(max_wait_time=5)
       for message in messages:
           print(str(message))
           await servicebus_receiver.complete_message(message)

renew_message_lock

Renove o bloqueio de mensagens.

Esta ação irá manter o bloqueio na mensagem para garantir que não é devolvido à fila para ser novamente processada.

Para concluir (ou resolver) a mensagem, o bloqueio tem de ser mantido e não pode já ter expirado; não é possível renovar um bloqueio expirado.

As mensagens recebidas através do modo RECEIVE_AND_DELETE não estão bloqueadas e, por conseguinte, não podem ser renovadas. Esta operação só está disponível para mensagens sem sessão.

async renew_message_lock(message: ServiceBusReceivedMessage, *, timeout: float | None = None, **kwargs: Any) -> datetime

Parâmetros

message
ServiceBusReceivedMessage
Necessário

A mensagem para a renovação do bloqueio.

timeout
Optional[float]

O tempo limite total da operação em segundos, incluindo todas as repetições. Se especificado, o valor tem de ser superior a 0. O valor predefinido é Nenhum, o que significa que não há tempo limite.

Devoluções

O utc datetime em que o bloqueio está definido para expirar às.

Tipo de retorno

Exceções

TypeError if the message is sessionful.
azure.servicebus.exceptions.MessageAlreadySettled if the message has been settled.
azure.servicebus.exceptions.MessageLockLostError if message lock has already expired.

Exemplos

Renove o bloqueio numa mensagem recebida.


       messages = await servicebus_receiver.receive_messages(max_wait_time=5)
       for message in messages:
           await servicebus_receiver.renew_message_lock(message)

Atributos

client_identifier

Obtenha o identificador de cliente ServiceBusReceiver associado à instância do recetor.

Tipo de retorno

str

session

Ligar o objeto ServiceBusSession ao recetor. A sessão só está disponível para entidades com sessão ativada, devolveria Nenhuma se fosse chamada a um recetor sem sessão.

Tipo de retorno

Exemplos

Obter sessão de um recetor


       async with servicebus_client.get_queue_receiver(queue_name=queue_name, session_id=session_id) as receiver:
           session = receiver.session