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 para a mensagem no recetor: para receber continuamente mensagens recebidas de forma contínua.
Utilize o método ~azure.servicebus.ServiceBusClient get_<queue/subscription>_receiver para criar uma instância 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 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
- TokenCredential 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 do Service Bus específica no Tópico especificado ao qual o cliente se liga.
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.
- 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.
- logging_enable
- bool
Se pretende exportar 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. Tem de ser um dicionário com as seguintes chaves: "proxy_hostname" (valor 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 for especificado, será adicionado à frente da cadeia de agente de utilizador incorporada.
- auto_lock_renewer
- Optional[AutoLockRenewer]
Pode ser fornecido ~azure.servicebus.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 a otimização avançada do desempenho. Aumentar este valor 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, 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 de 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 superior ao 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 Não Entregue. A fila de Mensagens Não Entregues é uma sub-fila que pode ser utilizada para armazenar mensagens que não foram processadas corretamente ou que requerem uma inspeção ou processamento adicionais. A fila também pode ser configurada para enviar mensagens expiradas para a fila de Mensagens Não Entregues. |
| 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. |
| next | |
| 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 |
Receber 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 priorizará o retorno rápido em relação ao cumprimento 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.
abandon_message(message: ServiceBusReceivedMessage) -> NoneParâmetros
Tipo de retorno
Exceções
Exemplos
Abandonar 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.
Esta ação 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 Carta Não Entregue.
A fila de Mensagens Não Entregues é uma sub-fila que pode ser utilizada para armazenar mensagens que não foram processadas corretamente ou que requerem uma inspeção ou processamento adicionais. A fila também pode ser configurada para enviar mensagens expiradas para a fila de Mensagens Não Entregues.
dead_letter_message(message: ServiceBusReceivedMessage, reason: str | None = None, error_description: str | None = None) -> NoneParâmetros
A descrição detalhada do erro para enviar a mensagem sem mensagens.
Tipo de retorno
Exceções
Exemplos
Carta não entregue 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.
Esta mensagem permanecerá na fila, mas tem de ser pedida especificamente pelo respetivo número de sequência para ser recebida.
defer_message(message: ServiceBusReceivedMessage) -> NoneParâmetros
Tipo de retorno
Exceções
Exemplos
Diferir 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 pré-visualizadas não são removidas da fila, nem estão bloqueadas. Não podem ser concluídas, diferidas ou não entregues.
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 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 for especificado, o valor tem de ser maior do que 0. O valor predefinido é Nenhum, o que significa que não há tempo limite.
Devoluções
Uma lista de ~azure.servicebus.ServiceBusReceivedMessage.
Tipo de retorno
Exceções
Exemplos
Observe 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 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_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 for especificado, o valor tem de ser maior do que 0. O valor predefinido é Nenhum, o que significa que não há tempo limite.
Devoluções
Uma lista das instâncias de ~azure.servicebus.ServiceBusReceivedMessage pedidas.
Tipo de retorno
Exceções
Exemplos
Receber mensagens diferidas 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
Receber 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 priorizará o retorno rápido em relação ao cumprimento 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.
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á da prefetch_count e da taxa de transmissão de entrada. A definição como Nenhum dependerá totalmente da configuração de pré-bloqueio. O valor predefinido é 1.
Tempo máximo para aguardar em segundos até chegar a primeira mensagem. Se não forem recebidas mensagens e não for especificado nenhum tempo limite, esta chamada não será devolvida até que a ligação seja fechada. Se for especificado, será devolvida uma lista vazia sem mensagens dentro do período de tempo limite.
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.
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 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.
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 for especificado, o valor tem de ser maior do que 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 = 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 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 num recetor sem sessão.
Tipo de retorno
Exemplos
Obter sessão de um recetor
with servicebus_client.get_queue_receiver(queue_name=queue_name, session_id=session_id) as receiver:
session = receiver.session