ServiceBusReceiver Classe
A classe ServiceBusReceiver define uma interface de alto nível para receber mensagens da Assinatura de Fila ou Tópico do Barramento de Serviço do Azure.
Os dois canais principais para recebimento de mensagens são receive() para fazer uma única solicitação de mensagens e para a mensagem no receptor: para receber continuamente mensagens de entrada de forma contínua.
Use o método de ~azure.servicebus.ServiceBusClient get_<queue/subscription>_receiver para criar uma instância de ServiceBusReceiver.
- Herança
-
azure.servicebus._base_handler.BaseHandlerServiceBusReceiverazure.servicebus._common.receiver_mixins.ReceiverMixinServiceBusReceiver
Construtor
ServiceBusReceiver(fully_qualified_namespace: str, credential: TokenCredential | 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 do host totalmente qualificado para o namespace do Barramento de Serviço. O formato do namespace é: .servicebus.windows.net.
- credential
- TokenCredential ou AzureSasCredential ou AzureNamedKeyCredential
O objeto de credencial usado para autenticação que implementa uma interface específica para obter tokens. Ele aceita objetos de credencial gerados pela biblioteca de identidade do azure e objetos que implementam o método *get_token(self, scopes) ou, como alternativa, um AzureSasCredential também pode ser fornecido.
- queue_name
- str
O caminho da fila específica do Barramento de Serviço ao qual o cliente se conecta.
- topic_name
- str
O caminho do Tópico específico do Barramento de Serviço que contém a Assinatura à qual o cliente se conecta.
- subscription_name
- str
O caminho da assinatura específica do Barramento de Serviço no Tópico especificado ao qual o cliente se conecta.
O tempo limite em segundos entre as mensagens recebidas após as quais o receptor deixará de receber automaticamente. O valor padrão é None, o que significa que não há tempo limite.
- receive_mode
- Union[ServiceBusReceiveMode, str]
O modo com o qual as mensagens serão recuperadas da entidade. As duas opções são PEEK_LOCK e RECEIVE_AND_DELETE. As mensagens recebidas com PEEK_LOCK devem ser liquidadas dentro de um 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 reenviadas se o cliente não processar a mensagem. O modo padrão é PEEK_LOCK.
- logging_enable
- bool
Se os logs de rastreamento de rede devem ser gerados para o agente. O padrão é False.
- transport_type
- TransportType
O tipo de protocolo de transporte que será usado para se comunicar com o serviço do Barramento de Serviço. O padrão é TransportType.Amqp.
- http_proxy
- Dict
Configurações de proxy HTTP. Deve ser um dicionário com as seguintes chaves: 'proxy_hostname' (valor str) e 'proxy_port' (valor int). Além disso, as seguintes chaves também podem estar presentes: 'username', 'password'.
- user_agent
- str
Se especificado, isso será adicionado na frente da cadeia de caracteres interna do agente do usuário.
- auto_lock_renewer
- Optional[AutoLockRenewer]
Um ~azure.servicebus.AutoLockRenewer pode ser fornecido de modo que as mensagens sejam registradas automaticamente no recebimento. Se o receptor for um receptor de sessão, ele será aplicado à sessão.
- prefetch_count
- int
O número máximo de mensagens a serem armazenadas em cache com cada solicitação para o serviço. Essa configuração é apenas para ajuste avançado de desempenho. Aumentar esse valor melhorará o desempenho da taxa de transferência da mensagem, mas aumentará a chance de que as mensagens expirem enquanto são armazenadas em cache se não forem processadas com rapidez suficiente. O valor padrão é 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, ServiceBusReceiver.receive tentará armazenar em cache max_message_count (se fornecido) dentro de sua solicitação para o serviço.
- client_identifier
- str
Um identificador baseado em cadeia de caracteres para identificar exclusivamente a instância do cliente. O Barramento de Serviço o associará a algumas mensagens de erro para facilitar a correlação de erros. Se não for especificado, uma ID exclusiva será gerada.
- socket_timeout
- float
O tempo em segundos que o soquete subjacente na conexão deve aguardar ao enviar e receber dados antes de atingir o tempo limite. O valor padrão é 0,2 para TransportType.Amqp e 1 para TransportType.AmqpOverWebsocket. Se erros de conexão estiverem ocorrendo devido ao tempo limite de gravação, talvez seja necessário passar um valor maior que o padrão.
Variáveis
- fully_qualified_namespace
- str
O nome do host totalmente qualificado para o namespace do Barramento de Serviço. O formato do namespace é: .servicebus.windows.net.
- entity_path
- str
O caminho da entidade à qual o cliente se conecta.
Métodos
| abandon_message |
Abandone a mensagem. Essa mensagem será retornada para a fila e disponibilizada para ser recebida novamente. |
| close | |
| complete_message |
Conclua a mensagem. Isso remove a mensagem da fila. |
| dead_letter_message |
Mova a mensagem para a fila de Mensagens Mortas. A fila de Mensagens Mortas é uma sub-fila que pode ser usada para armazenar mensagens que falharam ao processar corretamente ou, de outra forma, exigem inspeção ou processamento adicionais. A fila também pode ser configurada para enviar mensagens expiradas para a fila de Mensagens Mortas. |
| defer_message |
Adia a mensagem. Essa mensagem permanecerá na fila, mas deverá ser solicitada especificamente pelo número de sequência para ser recebida. |
| next | |
| peek_messages |
Procurar mensagens atualmente pendentes na fila. As mensagens espiadas não são removidas da fila nem são bloqueadas. Eles não podem ser concluídos, adiados ou com mensagens mortas. |
| receive_deferred_messages |
Receber mensagens que foram adiadas anteriormente. Ao receber mensagens adiadas de uma entidade particionada, todos os números de sequência fornecidos devem ser mensagens da mesma partição. |
| receive_messages |
Receba um lote de mensagens de uma só vez. Essa abordagem é ideal se você quiser processar várias mensagens simultaneamente ou executar um recebimento ad hoc como uma única chamada. Observe que o número de mensagens recuperadas em um único lote dependerá se prefetch_count foi definido para o receptor. Se prefetch_count não estiver definido para o receptor, o receptor tentará armazenar em cache max_message_count mensagens (se fornecidas) dentro da solicitação para o serviço. Essa chamada priorizará o retorno rapidamente em vez de atender a um tamanho de lote especificado e, portanto, retornará assim que pelo menos uma mensagem for recebida e houver uma lacuna nas mensagens de entrada, independentemente do tamanho do lote especificado. |
| renew_message_lock |
Renove o bloqueio da mensagem. Isso manterá o bloqueio na mensagem para garantir que ela não seja retornada para a fila a ser reprocessada. Para concluir (ou de outra forma resolver) a mensagem, o bloqueio deve ser mantido e ainda não pode ter expirado; um bloqueio expirado não pode ser renovado. As mensagens recebidas por meio do modo RECEIVE_AND_DELETE não estão bloqueadas e, portanto, não podem ser renovadas. Essa operação só está disponível para mensagens sem sessão. |
abandon_message
Abandone a mensagem.
Essa mensagem será retornada para a fila e disponibilizada para ser recebida novamente.
abandon_message(message: ServiceBusReceivedMessage) -> NoneParâmetros
Tipo de retorno
Exceções
Exemplos
Abandone uma mensagem recebida.
messages = servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
servicebus_receiver.abandon_message(message)
close
close() -> NoneExceções
complete_message
Conclua a mensagem.
Isso remove a mensagem da fila.
complete_message(message: ServiceBusReceivedMessage) -> NoneParâmetros
Tipo de retorno
Exceções
Exemplos
Conclua uma mensagem recebida.
messages = servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
servicebus_receiver.complete_message(message)
dead_letter_message
Mova a mensagem para a fila de Mensagens Mortas.
A fila de Mensagens Mortas é uma sub-fila que pode ser usada para armazenar mensagens que falharam ao processar corretamente ou, de outra forma, exigem inspeção ou processamento adicionais. A fila também pode ser configurada para enviar mensagens expiradas para a fila de Mensagens Mortas.
dead_letter_message(message: ServiceBusReceivedMessage, reason: str | None = None, error_description: str | None = None) -> NoneParâmetros
A descrição detalhada do erro para mensagens mortas da mensagem.
Tipo de retorno
Exceções
Exemplos
Mensagem morta uma mensagem recebida.
messages = servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
servicebus_receiver.dead_letter_message(message)
defer_message
Adia a mensagem.
Essa mensagem permanecerá na fila, mas deverá ser solicitada especificamente pelo número de sequência para ser recebida.
defer_message(message: ServiceBusReceivedMessage) -> NoneParâmetros
Tipo de retorno
Exceções
Exemplos
Adiar uma mensagem recebida.
messages = servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
servicebus_receiver.defer_message(message)
next
next()Exceções
peek_messages
Procurar mensagens atualmente pendentes na fila.
As mensagens espiadas não são removidas da fila nem são bloqueadas. Eles não podem ser concluídos, adiados ou com mensagens mortas.
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 para tentar espiar. O valor padrão é 1.
- sequence_number
- int
Um número de sequência de mensagens do qual começar a procurar mensagens.
O tempo limite total da operação em segundos, incluindo todas as tentativas. O valor deve ser maior que 0 se especificado. O valor padrão é None, o que significa que não há tempo limite.
Retornos
Uma lista de ~azure.servicebus.ServiceBusReceivedMessage.
Tipo de retorno
Exceções
Exemplos
Examine as mensagens pendentes na fila.
with servicebus_receiver:
messages = servicebus_receiver.peek_messages()
for message in messages:
print(str(message))
receive_deferred_messages
Receber mensagens que foram adiadas anteriormente.
Ao receber mensagens adiadas de uma entidade particionada, todos os números de sequência fornecidos devem ser mensagens da mesma partição.
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 adiadas.
O tempo limite total da operação em segundos, incluindo todas as tentativas. O valor deve ser maior que 0 se especificado. O valor padrão é None, o que significa que não há tempo limite.
Retornos
Uma lista das instâncias ~azure.servicebus.ServiceBusReceivedMessage solicitadas.
Tipo de retorno
Exceções
Exemplos
Receber mensagens adiadas do ServiceBus.
with servicebus_receiver:
deferred_sequenced_numbers = []
messages = servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
deferred_sequenced_numbers.append(message.sequence_number)
print(str(message))
servicebus_receiver.defer_message(message)
received_deferred_msg = servicebus_receiver.receive_deferred_messages(
sequence_numbers=deferred_sequenced_numbers
)
for msg in received_deferred_msg:
servicebus_receiver.complete_message(msg)
receive_messages
Receba um lote de mensagens de uma só vez.
Essa abordagem é ideal se você quiser processar várias mensagens simultaneamente ou executar um recebimento ad hoc como uma única chamada.
Observe que o número de mensagens recuperadas em um único lote dependerá se prefetch_count foi definido para o receptor. Se prefetch_count não estiver definido para o receptor, o receptor tentará armazenar em cache max_message_count mensagens (se fornecidas) dentro da solicitação para o serviço.
Essa chamada priorizará o retorno rapidamente em vez de atender a um tamanho de lote especificado e, portanto, retornará assim que pelo menos uma mensagem for recebida e houver uma lacuna nas mensagens de entrada, independentemente do tamanho do lote especificado.
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 retornado dependerá de prefetch_count e da taxa de fluxo de entrada. A configuração como Nenhum dependerá totalmente da configuração de pré-busca. O valor padrão é 1.
Tempo máximo de espera em segundos para que a primeira mensagem chegue. Se nenhuma mensagem chegar e nenhum tempo limite for especificado, essa chamada não retornará até que a conexão seja fechada. Se especificado, nenhuma mensagem chega dentro do período de tempo limite, uma lista vazia será retornada.
Retornos
Uma lista de mensagens recebidas. Se nenhuma mensagem estiver disponível, essa será uma lista vazia.
Tipo de retorno
Exceções
Exemplos
Receber mensagens do ServiceBus.
with servicebus_receiver:
messages = servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
print(str(message))
servicebus_receiver.complete_message(message)
renew_message_lock
Renove o bloqueio da mensagem.
Isso manterá o bloqueio na mensagem para garantir que ela não seja retornada para a fila a ser reprocessada.
Para concluir (ou de outra forma resolver) a mensagem, o bloqueio deve ser mantido e ainda não pode ter expirado; um bloqueio expirado não pode ser renovado.
As mensagens recebidas por meio do modo RECEIVE_AND_DELETE não estão bloqueadas e, portanto, não podem ser renovadas. Essa operação só está disponível para mensagens sem sessão.
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 tentativas. O valor deve ser maior que 0 se especificado. O valor padrão é None, o que significa que não há tempo limite.
Retornos
O datetime utc em que o bloqueio está definido para expirar.
Tipo de retorno
Exceções
Exemplos
Renove o bloqueio em uma mensagem recebida.
messages = servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
servicebus_receiver.renew_message_lock(message)
Atributos
client_identifier
Obtenha a client_identifier ServiceBusReceiver associada à instância do receptor.
Tipo de retorno
session
Obtenha o objeto ServiceBusSession vinculado ao receptor. A sessão só está disponível para entidades habilitadas para sessão. Ela retornaria Nenhum se fosse chamada em um receptor não com sessão.
Tipo de retorno
Exemplos
Obter sessão de um receptor
with servicebus_client.get_queue_receiver(queue_name=queue_name, session_id=session_id) as receiver:
session = receiver.session