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
-
ServiceBusReceiverazure.servicebus.aio._base_handler_async.BaseHandlerServiceBusReceiverazure.servicebus._common.receiver_mixins.ReceiverMixinServiceBusReceiver
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
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
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.
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) -> NoneParâmetros
Tipo de retorno
Exceções
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() -> NoneExceções
complete_message
Conclua a mensagem.
Esta ação remove a mensagem da fila.
async complete_message(message: ServiceBusReceivedMessage) -> NoneParâmetros
Tipo de retorno
Exceções
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) -> NoneParâmetros
A descrição detalhada do erro para escrever a mensagem sem letras.
Tipo de retorno
Exceções
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) -> NoneParâmetros
Tipo de retorno
Exceções
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
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.
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
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
Uma lista dos números de sequência de mensagens que foram diferidas.
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
Exceções
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
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.
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
Exceções
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) -> datetimeParâmetros
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
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
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
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários