ServiceBusReceiver Classe
La classe ServiceBusReceiver définit une interface de haut niveau pour la réception de messages à partir de l’abonnement file d’attente ou de rubrique Azure Service Bus.
Les deux principaux canaux de réception de message sont receive() pour effectuer une seule demande de messages et async pour le message dans le destinataire : pour recevoir en continu les messages entrants.
Utilisez la get_<queue/subscription>_receiver méthode ~azure.servicebus.aio.ServiceBusClient pour créer une instance ServiceBusReceiver.
- Héritage
-
ServiceBusReceiverazure.servicebus.aio._base_handler_async.BaseHandlerServiceBusReceiverazure.servicebus._common.receiver_mixins.ReceiverMixinServiceBusReceiver
Constructeur
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)Paramètres
- fully_qualified_namespace
- str
Nom d’hôte complet de l’espace de noms Service Bus. Le format de l’espace de noms est : .servicebus.windows.net.
- credential
- AsyncTokenCredential ou AzureSasCredential ou AzureNamedKeyCredential
Objet d’informations d’identification utilisé pour l’authentification qui implémente une interface particulière pour obtenir des jetons. Il accepte les objets d’informations d’identification générés par la bibliothèque azure-identity et les objets qui implémentent la méthode *get_token(self, scopes), ou une instance AzureSasCredential peut également être fournie.
- queue_name
- str
Chemin d’accès de la file d’attente Service Bus spécifique à laquelle le client se connecte.
- topic_name
- str
Chemin d’accès d’une rubrique Service Bus spécifique qui contient l’abonnement auquel le client se connecte.
- subscription_name
- str
Chemin d’accès d’un abonnement Service Bus spécifique sous la rubrique spécifiée à laquelle le client se connecte.
- receive_mode
- Union[ServiceBusReceiveMode, str]
Mode avec lequel les messages seront récupérés de l’entité. Les deux options sont PEEK_LOCK et RECEIVE_AND_DELETE. Les messages reçus avec PEEK_LOCK doivent être réglés dans une période de verrouillage donnée avant d’être supprimés de la file d’attente. Les messages reçus avec RECEIVE_AND_DELETE sont immédiatement supprimés de la file d’attente et ne peuvent pas être abandonnés ou ré-reçus si le client ne parvient pas à traiter le message. Le mode par défaut est PEEK_LOCK.
Délai d’expiration en secondes entre les messages reçus après lequel le récepteur cesse automatiquement de recevoir. La valeur par défaut est None, c’est-à-dire aucun délai d’expiration.
- logging_enable
- bool
Indique si les journaux de trace réseau doivent être générés dans l’enregistreur d’événements. La valeur par défaut est False.
- transport_type
- TransportType
Type de protocole de transport qui sera utilisé pour communiquer avec le service Service Bus. La valeur par défaut est TransportType.Amqp.
- http_proxy
- Dict
Paramètres du proxy HTTP. Il doit s’agir d’un dictionnaire avec les clés suivantes : « proxy_hostname » (valeur str) et « proxy_port » (valeur int). En outre, les clés suivantes peuvent également être présentes : « nom d’utilisateur », « mot de passe ».
- user_agent
- str
Si elle est spécifiée, elle est ajoutée devant la chaîne d’agent utilisateur intégrée.
- auto_lock_renewer
- Optional[AutoLockRenewer]
Un ~azure.servicebus.aio.AutoLockRenewer peut être fourni de telle sorte que les messages soient automatiquement enregistrés à la réception. Si le récepteur est un récepteur de session, il s’applique à la session à la place.
- prefetch_count
- int
Nombre maximal de messages à mettre en cache avec chaque demande adressée au service. Ce paramètre est uniquement destiné au réglage avancé des performances. L’augmentation de cette valeur améliore les performances de débit des messages, mais augmente le risque que les messages expirent pendant leur mise en cache s’ils ne sont pas traités assez rapidement. La valeur par défaut est 0, ce qui signifie que les messages sont reçus du service et traités un par un. Dans le cas où prefetch_count est 0, ServiceBusReceiver.receive tente de mettre en cache max_message_count (s’il est fourni) dans sa demande au service.
- client_identifier
- str
Identificateur basé sur une chaîne permettant d’identifier de manière unique le client instance. Service Bus l’associe à certains messages d’erreur pour faciliter la corrélation des erreurs. S’il n’est pas spécifié, un ID unique est généré.
- socket_timeout
- float
Durée en secondes pendant laquelle le socket sous-jacent sur la connexion doit attendre lors de l’envoi et de la réception de données avant d’expirer. La valeur par défaut est 0,2 pour TransportType.Amqp et 1 pour TransportType.AmqpOverWebsocket. Si des erreurs de connexion se produisent en raison d’un délai d’attente d’écriture, une valeur supérieure à la valeur par défaut peut être passée.
Variables
- fully_qualified_namespace
- str
Nom d’hôte complet de l’espace de noms Service Bus. Le format de l’espace de noms est . servicebus.windows.net.
- entity_path
- str
Chemin d’accès de l’entité à laquelle le client se connecte.
Méthodes
| abandon_message |
Abandonnez le message. Ce message sera retourné à la file d’attente et mis à disposition pour être à nouveau reçu. |
| close | |
| complete_message |
Complétez le message. Cela supprime le message de la file d’attente. |
| dead_letter_message |
Déplacez le message dans la file d’attente Lettres mortes. La file d’attente lettres mortes est une sous-file d’attente qui peut être utilisée pour stocker les messages qui n’ont pas pu être traités correctement ou qui nécessitent une inspection ou un traitement supplémentaire. La file d’attente peut également être configurée pour envoyer des messages expirés à la file d’attente lettres mortes. |
| defer_message |
Reporte le message. Ce message reste dans la file d’attente, mais doit être demandé spécifiquement par son numéro de séquence pour être reçu. |
| peek_messages |
Parcourir les messages actuellement en attente dans la file d’attente. Les messages aperçus ne sont pas supprimés de la file d’attente, pas plus qu’ils ne sont verrouillés. Ils ne peuvent pas être complétés, différés ou lettre morte. |
| receive_deferred_messages |
Recevoir des messages qui ont été précédemment différés. Lors de la réception de messages différés d’une entité partitionnée, tous les numéros de séquence fournis doivent être des messages de la même partition. |
| receive_messages |
Recevoir un lot de messages à la fois. Cette approche est optimale si vous souhaitez traiter plusieurs messages simultanément ou effectuer une réception ad hoc en tant qu’appel unique. Notez que le nombre de messages récupérés dans un seul lot dépend de la définition ou non de prefetch_count pour le récepteur. Si prefetch_count n’est pas défini pour le récepteur, celui-ci tente de mettre en cache max_message_count messages (s’ils sont fournis) dans la demande au service. Cet appel donne la priorité au retour rapide plutôt qu’à une taille de lot spécifiée, et retourne donc dès qu’au moins un message est reçu et qu’il y a un écart dans les messages entrants, quelle que soit la taille de lot spécifiée. |
| renew_message_lock |
Renouvelez le verrou de message. Cela maintient le verrou sur le message pour s’assurer qu’il n’est pas retourné à la file d’attente à retraiter. Pour terminer (ou régler) le message, le verrou doit être conservé et ne peut pas déjà avoir expiré ; un verrou expiré ne peut pas être renouvelé. Les messages reçus via RECEIVE_AND_DELETE mode ne sont pas verrouillés et ne peuvent donc pas être renouvelés. Cette opération n’est disponible que pour les messages non session. |
abandon_message
Abandonnez le message.
Ce message sera retourné à la file d’attente et mis à disposition pour être à nouveau reçu.
async abandon_message(message: ServiceBusReceivedMessage) -> NoneParamètres
Type de retour
Exceptions
Exemples
Abandonner un message reçu.
messages = await servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
await servicebus_receiver.abandon_message(message)
close
async close() -> NoneExceptions
complete_message
Complétez le message.
Cela supprime le message de la file d’attente.
async complete_message(message: ServiceBusReceivedMessage) -> NoneParamètres
Type de retour
Exceptions
Exemples
Terminer un message reçu.
messages = await servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
await servicebus_receiver.complete_message(message)
dead_letter_message
Déplacez le message dans la file d’attente Lettres mortes.
La file d’attente lettres mortes est une sous-file d’attente qui peut être utilisée pour stocker les messages qui n’ont pas pu être traités correctement ou qui nécessitent une inspection ou un traitement supplémentaire. La file d’attente peut également être configurée pour envoyer des messages expirés à la file d’attente lettres mortes.
async dead_letter_message(message: ServiceBusReceivedMessage, reason: str | None = None, error_description: str | None = None) -> NoneParamètres
Description détaillée de l’erreur pour la mise en lettres mortes du message.
Type de retour
Exceptions
Exemples
Lettre morte un message reçu.
messages = await servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
await servicebus_receiver.dead_letter_message(message)
defer_message
Reporte le message.
Ce message reste dans la file d’attente, mais doit être demandé spécifiquement par son numéro de séquence pour être reçu.
async defer_message(message: ServiceBusReceivedMessage) -> NoneParamètres
Type de retour
Exceptions
Exemples
Différer la réception d’un message.
messages = await servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
await servicebus_receiver.defer_message(message)
peek_messages
Parcourir les messages actuellement en attente dans la file d’attente.
Les messages aperçus ne sont pas supprimés de la file d’attente, pas plus qu’ils ne sont verrouillés. Ils ne peuvent pas être complétés, différés ou lettre morte.
async peek_messages(max_message_count: int = 1, *, sequence_number: int = 0, timeout: float | None = None, **kwargs: Any) -> List[ServiceBusReceivedMessage]Paramètres
- max_message_count
- int
Nombre maximal de messages à essayer et à jeter un coup d’œil. La valeur par défaut est 1.
- sequence_number
- int
Numéro de séquence de message à partir duquel commencer à parcourir les messages.
Délai d’expiration total de l’opération en secondes, y compris toutes les nouvelles tentatives. La valeur doit être supérieure à 0 si elle est spécifiée. La valeur par défaut est None, c’est-à-dire aucun délai d’expiration.
Retours
Liste des objets ~azure.servicebus.ServiceBusReceivedMessage.
Type de retour
Exceptions
Exemples
Jetez un coup d’œil aux messages dans la file d’attente.
async with servicebus_receiver:
messages = await servicebus_receiver.peek_messages()
for message in messages:
print(str(message))
receive_deferred_messages
Recevoir des messages qui ont été précédemment différés.
Lors de la réception de messages différés d’une entité partitionnée, tous les numéros de séquence fournis doivent être des messages de la même partition.
async receive_deferred_messages(sequence_numbers: int | List[int], *, timeout: float | None = None, **kwargs: Any) -> List[ServiceBusReceivedMessage]Paramètres
Liste des numéros séquentiels des messages qui ont été différés.
Délai d’expiration total de l’opération en secondes, y compris toutes les nouvelles tentatives. La valeur doit être supérieure à 0 si elle est spécifiée. La valeur par défaut est None, c’est-à-dire aucun délai d’expiration.
Retours
Liste des messages reçus.
Type de retour
Exceptions
Exemples
Recevoir des messages différés de 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
Recevoir un lot de messages à la fois.
Cette approche est optimale si vous souhaitez traiter plusieurs messages simultanément ou effectuer une réception ad hoc en tant qu’appel unique.
Notez que le nombre de messages récupérés dans un seul lot dépend de la définition ou non de prefetch_count pour le récepteur. Si prefetch_count n’est pas défini pour le récepteur, celui-ci tente de mettre en cache max_message_count messages (s’ils sont fournis) dans la demande au service.
Cet appel donne la priorité au retour rapide plutôt qu’à une taille de lot spécifiée, et retourne donc dès qu’au moins un message est reçu et qu’il y a un écart dans les messages entrants, quelle que soit la taille de lot spécifiée.
async receive_messages(max_message_count: int | None = 1, max_wait_time: float | None = None) -> List[ServiceBusReceivedMessage]Paramètres
Nombre maximal de messages dans le lot. Le nombre réel retourné dépend de la taille prefetch_count et du débit de flux entrants. La définition de la valeur None dépend entièrement de la configuration de prérécupération. La valeur par défaut est 1.
Temps maximal d’attente en secondes avant l’arrivée du premier message. Si aucun message n’arrive et qu’aucun délai d’expiration n’est spécifié, cet appel ne sera pas retourné tant que la connexion n’est pas fermée. S’il est spécifié et qu’aucun message n’arrive dans le délai d’expiration, une liste vide est retournée.
Retours
Liste des messages reçus. Si aucun message n’est disponible, il s’agit d’une liste vide.
Type de retour
Exceptions
Exemples
Recevoir des messages de 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
Renouvelez le verrou de message.
Cela maintient le verrou sur le message pour s’assurer qu’il n’est pas retourné à la file d’attente à retraiter.
Pour terminer (ou régler) le message, le verrou doit être conservé et ne peut pas déjà avoir expiré ; un verrou expiré ne peut pas être renouvelé.
Les messages reçus via RECEIVE_AND_DELETE mode ne sont pas verrouillés et ne peuvent donc pas être renouvelés. Cette opération n’est disponible que pour les messages non session.
async renew_message_lock(message: ServiceBusReceivedMessage, *, timeout: float | None = None, **kwargs: Any) -> datetimeParamètres
Délai d’expiration total de l’opération en secondes, y compris toutes les nouvelles tentatives. La valeur doit être supérieure à 0 si elle est spécifiée. La valeur par défaut est None, c’est-à-dire aucun délai d’attente.
Retours
Dateheure utc à laquelle le verrou est défini pour expirer.
Type de retour
Exceptions
Exemples
Renouvelez le verrou sur un message reçu.
messages = await servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
await servicebus_receiver.renew_message_lock(message)
Attributs
client_identifier
Obtenez l’identificateur client ServiceBusReceiver associé au récepteur instance.
Type de retour
session
Obtenez l’objet ServiceBusSession lié au récepteur. La session n’est disponible que pour les entités activées pour la session. Elle retourne Aucun si elle est appelée sur un récepteur non session.
Type de retour
Exemples
Obtenir une session à partir d’un récepteur
async with servicebus_client.get_queue_receiver(queue_name=queue_name, session_id=session_id) as receiver:
session = receiver.session