ServiceBusReceiver Třída
ServiceBusReceiver Třída definuje rozhraní vysoké úrovně pro příjem zpráv z Azure Service Bus fronty nebo odběru tématu.
Dva primární kanály pro příjem zpráv jsou receive() pro vytvoření jednoho požadavku na zprávy a pro zprávy v příjemci: průběžné přijímání příchozích zpráv průběžným způsobem.
K vytvoření instance ServiceBusReceiver použijte get_<queue/subscription>_receiver metodu ~azure.servicebus.ServiceBusClient.
- Dědičnost
-
azure.servicebus._base_handler.BaseHandlerServiceBusReceiverazure.servicebus._common.receiver_mixins.ReceiverMixinServiceBusReceiver
Konstruktor
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)Parametry
- fully_qualified_namespace
- str
Plně kvalifikovaný název hostitele pro obor názvů služby Service Bus. Formát oboru názvů je .servicebus.windows.net.
- credential
- TokenCredential nebo AzureSasCredential nebo AzureNamedKeyCredential
Objekt přihlašovacích údajů používaný k ověřování, který implementuje konkrétní rozhraní pro získávání tokenů. Přijímá objekty přihlašovacích údajů vygenerované knihovnou azure-identity a objekty, které implementují metodu *get_token(self, scopes), případně je možné poskytnout také AzureSasCredential.
- queue_name
- str
Cesta konkrétní fronty služby Service Bus, ke které se klient připojuje.
- topic_name
- str
Cesta ke konkrétnímu tématu služby Service Bus, která obsahuje předplatné, ke kterému se klient připojuje.
- subscription_name
- str
Cesta konkrétního předplatného služby Service Bus v zadaném tématu, ke které se klient připojuje.
Časový limit v sekundách mezi přijatými zprávami, po kterém příjemce automaticky přestane přijímat. Výchozí hodnota je Žádný, což znamená žádný časový limit.
- receive_mode
- Union[ServiceBusReceiveMode, str]
Režim, pomocí kterého se budou zprávy načítat z entity. Tyto dvě možnosti jsou PEEK_LOCK a RECEIVE_AND_DELETE. Zprávy přijaté s PEEK_LOCK musí být vyřešeny v daném období uzamčení, než se odeberou z fronty. Zprávy přijaté s RECEIVE_AND_DELETE budou okamžitě odebrány z fronty a nelze je následně opustit nebo znovu obdržet, pokud klient zprávu nezpracuje. Výchozí režim je PEEK_LOCK.
- logging_enable
- bool
Zda se mají protokoly trasování sítě vypisovat do protokolovacího nástroje. Výchozí hodnota je False.
- transport_type
- TransportType
Typ přenosového protokolu, který se použije pro komunikaci se službou Service Bus. Výchozí hodnota je TransportType.Amqp.
- http_proxy
- Dict
Nastavení proxy serveru HTTP. Musí se jednat o slovník s následujícími klíči: "proxy_hostname" (hodnota str) a "proxy_port" (hodnota int). Kromě toho můžou být k dispozici také následující klíče: uživatelské jméno, heslo.
- user_agent
- str
Pokud je zadaný, přidá se před předdefinovaný řetězec uživatelského agenta.
- auto_lock_renewer
- Optional[AutoLockRenewer]
Je možné poskytnout ~azure.servicebus.AutoLockRenewer tak, aby se zprávy automaticky zaregistrovaly při přijetí. Pokud je příjemcem relace, použije se místo toho na relaci.
- prefetch_count
- int
Maximální počet zpráv, které se mají ukládat do mezipaměti s jednotlivými požadavky na službu. Toto nastavení je určené pouze pro pokročilé ladění výkonu. Zvýšením této hodnoty se zvýší výkon propustnosti zpráv, ale zvýší se pravděpodobnost, že platnost zpráv vyprší, když se uloží do mezipaměti, pokud se nezpracují dostatečně rychle. Výchozí hodnota je 0, což znamená, že zprávy se budou přijímat ze služby a zpracovávat je po jednom. V případě prefetch_count 0 se ServiceBusReceiver.receive pokusí uložit do mezipaměti max_message_count (pokud je k dispozici) v rámci své žádosti do služby.
- client_identifier
- str
Identifikátor založený na řetězci pro jedinečnou identifikaci instance klienta. Service Bus ji přidruží k některým chybovým zprávm, aby se usnadnila korelace chyb. Pokud není zadáno, vygeneruje se jedinečné ID.
- socket_timeout
- float
Čas v sekundách, kdy by měl podkladový soket na připojení čekat při odesílání a příjmu dat před vypršením časového limitu. Výchozí hodnota je 0,2 pro TransportType.Amqp a 1 pro TransportType.AmqpOverWebsocket. Pokud dochází k chybám připojení kvůli vypršení časového limitu zápisu, může být potřeba předat větší než výchozí hodnotu.
Proměnné
- fully_qualified_namespace
- str
Plně kvalifikovaný název hostitele pro obor názvů služby Service Bus. Formát oboru názvů je .servicebus.windows.net.
- entity_path
- str
Cesta k entitě, ke které se klient připojuje.
Metody
| abandon_message |
Opusťte zprávu. Tato zpráva se vrátí do fronty a zpřístupní se k opětovnému přijetí. |
| close | |
| complete_message |
Dokončete zprávu. Tím se zpráva odebere z fronty. |
| dead_letter_message |
Přesuňte zprávu do fronty Nedoručených zpráv. Fronta nedoručených zpráv je podsepis, kterou lze použít k ukládání zpráv, které se nepodařilo správně zpracovat nebo jinak vyžadují další kontrolu nebo zpracování. Frontu lze také nakonfigurovat tak, aby odesílala zprávy s prošlou platností do fronty nedoručených zpráv. |
| defer_message |
Odsudí zprávu. Tato zpráva zůstane ve frontě, ale aby byla přijata, musí být požadována konkrétně podle jejího pořadového čísla. |
| next | |
| peek_messages |
Umožňuje procházet zprávy, které čekají ve frontě. Náhledy zpráv se z fronty neodeberou, ani nejsou uzamčené. Nelze je dokončit, odložit ani nedoručovat. |
| receive_deferred_messages |
Příjem zpráv, které byly dříve odloženy. Při přijímání odložených zpráv z dělené entity musí být všechna zadaná pořadová čísla zprávy ze stejného oddílu. |
| receive_messages |
Příjem dávky zpráv najednou Tento přístup je optimální, pokud chcete zpracovat více zpráv současně nebo provést ad hoc příjem jako jedno volání. Všimněte si, že počet zpráv načtených v jedné dávce bude záviset na tom, jestli byla pro příjemce nastavena prefetch_count. Pokud prefetch_count není nastavena pro příjemce, příjemce se pokusí uložit do mezipaměti max_message_count (pokud jsou k dispozici) zprávy v rámci požadavku na službu. Toto volání upřednostní rychlé vrácení před schůzkou se zadanou velikostí dávky, a tak se vrátí, jakmile se přijme alespoň jedna zpráva a v příchozích zprávách bude mezera bez ohledu na zadanou velikost dávky. |
| renew_message_lock |
Obnovte zámek zprávy. Tím se zachová zámek zprávy, aby se zajistilo, že se nevrátí do fronty, která se má znovu zpracovat. Chcete-li dokončit (nebo jinak vyrovnat) zprávu, musí být zámek zachován a již nemůže mít platnost; zámek, jehož platnost vypršela, nelze obnovit. Zprávy přijaté prostřednictvím režimu RECEIVE_AND_DELETE nejsou uzamčeny, a proto je nelze obnovit. Tato operace je dostupná jenom pro zprávy, které nejsou v relaci. |
abandon_message
Opusťte zprávu.
Tato zpráva se vrátí do fronty a zpřístupní se k opětovnému přijetí.
abandon_message(message: ServiceBusReceivedMessage) -> NoneParametry
Návratový typ
Výjimky
Příklady
Opuštění přijaté zprávy
messages = servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
servicebus_receiver.abandon_message(message)
close
close() -> NoneVýjimky
complete_message
Dokončete zprávu.
Tím se zpráva odebere z fronty.
complete_message(message: ServiceBusReceivedMessage) -> NoneParametry
Návratový typ
Výjimky
Příklady
Dokončete přijatou zprávu.
messages = servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
servicebus_receiver.complete_message(message)
dead_letter_message
Přesuňte zprávu do fronty Nedoručených zpráv.
Fronta nedoručených zpráv je podsepis, kterou lze použít k ukládání zpráv, které se nepodařilo správně zpracovat nebo jinak vyžadují další kontrolu nebo zpracování. Frontu lze také nakonfigurovat tak, aby odesílala zprávy s prošlou platností do fronty nedoručených zpráv.
dead_letter_message(message: ServiceBusReceivedMessage, reason: str | None = None, error_description: str | None = None) -> NoneParametry
Návratový typ
Výjimky
Příklady
Nedoručených zpráv přijaté zprávy.
messages = servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
servicebus_receiver.dead_letter_message(message)
defer_message
Odsudí zprávu.
Tato zpráva zůstane ve frontě, ale aby byla přijata, musí být požadována konkrétně podle jejího pořadového čísla.
defer_message(message: ServiceBusReceivedMessage) -> NoneParametry
Návratový typ
Výjimky
Příklady
Odložení přijaté zprávy
messages = servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
servicebus_receiver.defer_message(message)
next
next()Výjimky
peek_messages
Umožňuje procházet zprávy, které čekají ve frontě.
Náhledy zpráv se z fronty neodeberou, ani nejsou uzamčené. Nelze je dokončit, odložit ani nedoručovat.
peek_messages(max_message_count: int = 1, *, sequence_number: int = 0, timeout: float | None = None, **kwargs: Any) -> List[ServiceBusReceivedMessage]Parametry
- max_message_count
- int
Maximální počet zpráv, které se mají vyzkoušet a zobrazit. Výchozí hodnota je 1.
- sequence_number
- int
Pořadové číslo zprávy, ze kterého chcete začít procházet zprávy.
Celkový časový limit operace v sekundách včetně všech opakování. Hodnota musí být větší než 0, pokud je zadána. Výchozí hodnota je Žádný, což znamená žádný časový limit.
Návraty
Seznam ~azure.servicebus.ServiceBusReceivedMessage.
Návratový typ
Výjimky
Příklady
Podívejte se na čekající zprávy ve frontě.
with servicebus_receiver:
messages = servicebus_receiver.peek_messages()
for message in messages:
print(str(message))
receive_deferred_messages
Příjem zpráv, které byly dříve odloženy.
Při přijímání odložených zpráv z dělené entity musí být všechna zadaná pořadová čísla zprávy ze stejného oddílu.
receive_deferred_messages(sequence_numbers: int | List[int], *, timeout: float | None = None, **kwargs: Any) -> List[ServiceBusReceivedMessage]Parametry
Seznam pořadových čísel zpráv, které byly odloženy.
Celkový časový limit operace v sekundách včetně všech opakování. Hodnota musí být větší než 0, pokud je zadána. Výchozí hodnota je Žádný, což znamená žádný časový limit.
Návraty
Seznam požadovaných instancí ~azure.servicebus.ServiceBusReceivedMessage
Návratový typ
Výjimky
Příklady
Příjem zpráv s odloženým odkladem ze služby 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
Příjem dávky zpráv najednou
Tento přístup je optimální, pokud chcete zpracovat více zpráv současně nebo provést ad hoc příjem jako jedno volání.
Všimněte si, že počet zpráv načtených v jedné dávce bude záviset na tom, jestli byla pro příjemce nastavena prefetch_count. Pokud prefetch_count není nastavena pro příjemce, příjemce se pokusí uložit do mezipaměti max_message_count (pokud jsou k dispozici) zprávy v rámci požadavku na službu.
Toto volání upřednostní rychlé vrácení před schůzkou se zadanou velikostí dávky, a tak se vrátí, jakmile se přijme alespoň jedna zpráva a v příchozích zprávách bude mezera bez ohledu na zadanou velikost dávky.
receive_messages(max_message_count: int | None = 1, max_wait_time: float | None = None) -> List[ServiceBusReceivedMessage]Parametry
Maximální počet zpráv v dávce. Skutečný vrácený počet bude záviset na rychlosti prefetch_count a příchozího datového proudu. Nastavení na Žádný bude plně záviset na konfiguraci předběžného načtení. Výchozí hodnota je 1.
Maximální doba čekání na doručení první zprávy v sekundách Pokud nedorazí žádné zprávy a není zadaný žádný časový limit, toto volání se nevrátí, dokud se připojení neuzavře. Pokud je tato možnost zadána, během časového limitu nedorazí žádná zpráva, vrátí se prázdný seznam.
Návraty
Seznam přijatých zpráv. Pokud nejsou k dispozici žádné zprávy, bude to prázdný seznam.
Návratový typ
Výjimky
Příklady
Příjem zpráv ze služby 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
Obnovte zámek zprávy.
Tím se zachová zámek zprávy, aby se zajistilo, že se nevrátí do fronty, která se má znovu zpracovat.
Chcete-li dokončit (nebo jinak vyrovnat) zprávu, musí být zámek zachován a již nemůže mít platnost; zámek, jehož platnost vypršela, nelze obnovit.
Zprávy přijaté prostřednictvím režimu RECEIVE_AND_DELETE nejsou uzamčeny, a proto je nelze obnovit. Tato operace je dostupná jenom pro zprávy, které nejsou v relaci.
renew_message_lock(message: ServiceBusReceivedMessage, *, timeout: float | None = None, **kwargs: Any) -> datetimeParametry
Celkový časový limit operace v sekundách včetně všech opakování. Hodnota musí být větší než 0, pokud je zadána. Výchozí hodnota je Žádný, což znamená žádný časový limit.
Návraty
Datum UTC a čas, na který je zámek nastavený tak, aby vypršel.
Návratový typ
Výjimky
Příklady
Obnovte zámek u přijaté zprávy.
messages = servicebus_receiver.receive_messages(max_wait_time=5)
for message in messages:
servicebus_receiver.renew_message_lock(message)
Atributy
client_identifier
session
Získejte objekt ServiceBusSession propojený s příjemcem. Relace je dostupná pouze pro entity s povolenými relacemi. Pokud by byla volána na přijímači bez relace, vrátila by hodnotu None.
Návratový typ
Příklady
Získání relace od příjemce
with servicebus_client.get_queue_receiver(queue_name=queue_name, session_id=session_id) as receiver:
session = receiver.session