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 canaux principaux pour la réception des messages sont receive() pour effectuer une demande unique de messages, et pour le message dans le destinataire : pour recevoir continuellement les messages entrants de manière continue.
Utilisez la get_<queue/subscription>_receiver méthode ~azure.servicebus.ServiceBusClient pour créer un instance ServiceBusReceiver.
- Héritage
-
azure.servicebus._base_handler.BaseHandlerServiceBusReceiverazure.servicebus._common.receiver_mixins.ReceiverMixinServiceBusReceiver
Constructeur
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)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
- TokenCredential 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 d’identité azure 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 de la 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.
Délai d’attente en secondes entre les messages reçus, après quoi le destinataire cesse automatiquement de recevoir. La valeur par défaut est None, c’est-à-dire aucun délai d’attente.
- receive_mode
- Union[ServiceBusReceiveMode, str]
Mode avec lequel les messages seront récupérés à partir 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.
- logging_enable
- bool
Indique s’il faut générer des journaux de trace réseau vers 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
S’il est spécifié, cela sera ajouté devant la chaîne d’agent utilisateur intégrée.
- auto_lock_renewer
- Optional[AutoLockRenewer]
Un ~azure.servicebus.AutoLockRenewer peut être fourni de manière à ce que les messages soient automatiquement enregistrés lors de 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 requête adressée au service. Ce paramètre est uniquement destiné à l’optimisation avancée des performances. L’augmentation de cette valeur améliore les performances de débit des messages, mais augmente les chances 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 seront reçus du service et traités un par un. Dans le cas où prefetch_count est 0, ServiceBusReceiver.receive essaie de mettre en cache max_message_count (s’il est fourni) dans sa demande adressée au service.
- client_identifier
- str
Identificateur basé sur des chaînes permettant d’identifier de manière unique le client instance. Service Bus l’associera à 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 transmise.
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 rendu disponible pour être à nouveau reçu. |
| close | |
| complete_message |
Terminez le message. Cela supprime le message de la file d’attente. |
| dead_letter_message |
Déplacez le message vers la file d’attente Lettre morte. 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 été 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 arrivés à expiration à 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. |
| next | |
| peek_messages |
Parcourez les messages actuellement en attente dans la file d’attente. Les messages aperçus ne sont pas supprimés de la file d’attente et ne sont pas verrouillés. Ils ne peuvent pas être complétés, différés ou lettre morte. |
| receive_deferred_messages |
Recevez des messages qui ont déjà été 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 |
Recevez 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 un seul appel. 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 essaiera de mettre en cache max_message_count messages (s’ils sont fournis) dans la demande adressée au service. Cet appel donne la priorité au retour rapide par rapport à la réunion d’une taille de lot spécifiée et retourne donc dès qu’au moins un message est reçu et qu’il existe 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 rendu disponible pour être à nouveau reçu.
abandon_message(message: ServiceBusReceivedMessage) -> NoneParamètres
Type de retour
Exceptions
Exemples
Abandonnez un message reçu.
messages = servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
servicebus_receiver.abandon_message(message)
close
close() -> NoneExceptions
complete_message
Terminez le message.
Cela supprime le message de la file d’attente.
complete_message(message: ServiceBusReceivedMessage) -> NoneParamètres
Type de retour
Exceptions
Exemples
Complétez un message reçu.
messages = servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
servicebus_receiver.complete_message(message)
dead_letter_message
Déplacez le message vers la file d’attente Lettre morte.
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 été 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 arrivés à expiration à la file d’attente Lettres mortes.
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 lettre morte du message.
Type de retour
Exceptions
Exemples
Lettre morte un message reçu.
messages = servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
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.
defer_message(message: ServiceBusReceivedMessage) -> NoneParamètres
Type de retour
Exceptions
Exemples
Différer un message reçu.
messages = servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
servicebus_receiver.defer_message(message)
next
next()Exceptions
peek_messages
Parcourez les messages actuellement en attente dans la file d’attente.
Les messages aperçus ne sont pas supprimés de la file d’attente et ne sont pas verrouillés. Ils ne peuvent pas être complétés, différés ou lettre morte.
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’attente.
Retours
Liste de ~azure.servicebus.ServiceBusReceivedMessage.
Type de retour
Exceptions
Exemples
Examinez les messages en attente dans la file d’attente.
with servicebus_receiver:
messages = servicebus_receiver.peek_messages()
for message in messages:
print(str(message))
receive_deferred_messages
Recevez des messages qui ont déjà été 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_deferred_messages(sequence_numbers: int | List[int], *, timeout: float | None = None, **kwargs: Any) -> List[ServiceBusReceivedMessage]Paramètres
Liste des numéros de séquence 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’attente.
Retours
Liste des instances ~azure.servicebus.ServiceBusReceivedMessage demandées.
Type de retour
Exceptions
Exemples
Recevez des messages différés de 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
Recevez 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 un seul appel.
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 essaiera de mettre en cache max_message_count messages (s’ils sont fournis) dans la demande adressée au service.
Cet appel donne la priorité au retour rapide par rapport à la réunion d’une taille de lot spécifiée et retourne donc dès qu’au moins un message est reçu et qu’il existe un écart dans les messages entrants, quelle que soit la taille de lot spécifiée.
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 prefetch_count et du débit de flux entrant. La définition de la valeur Aucun dépend entièrement de la configuration de prérécupération. La valeur par défaut est 1.
Délai 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é, 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
Recevez des messages de 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
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.
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 = servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
servicebus_receiver.renew_message_lock(message)
Attributs
client_identifier
Obtenez le client_identifier ServiceBusReceiver associé au instance du récepteur.
Type de retour
session
Obtenez l’objet ServiceBusSession lié au récepteur. La session n’est disponible que pour les entités compatibles avec 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
with servicebus_client.get_queue_receiver(queue_name=queue_name, session_id=session_id) as receiver:
session = receiver.session