Jak používat Azure Queue Storage z Pythonu

Článek
01/19/2023

Přehled

Tento článek ukazuje běžné scénáře použití služby Azure Queue Storage. Popsané scénáře zahrnují vkládání, náhledy, získávání a odstraňování zpráv fronty. Probírali jsme také kód pro vytváření a odstraňování front.

Příklady v tomto článku jsou napsané v Pythonu a používají klientskou knihovnu Azure Queue Storage pro Python. Další informace o frontách najdete v části Další kroky .

Co je Queue Storage?

Azure Queue Storage je služba pro ukládání velkého počtu zpráv, ke které můžete získat přístup z jakéhokoli místa na světě prostřednictvím ověřených volání s využitím protokolu HTTP nebo HTTPS. Zpráva s jednou frontou může mít velikost až 64 kB a jedna fronta můžete obsahovat miliony zpráv, až do dosažení celkové kapacity účtu úložiště. Queue Storage se často používá k vytvoření backlogu práce pro asynchronní zpracování.

Koncepty služby Fronta

Služba Azure Queue obsahuje následující komponenty:

Komponenty služby Azure Queue

Účet úložiště: Veškerý přístup ke službě Azure Storage se provádí prostřednictvím účtu úložiště. Další informace o účtech úložiště najdete v tématu Přehled účtů úložiště.
Fronta: Fronta obsahuje sadu zpráv. Všechny zprávy musí být ve frontě. Upozorňujeme, že název fronty musí být psaný malými písmeny. Informace o pojmenování front najdete v tématu Pojmenování front a metadata.
Zpráva: Zprávu v libovolném formátu o velikosti až 64 kB. Maximální doba, po kterou může zpráva zůstat ve frontě, je 7 dní. Pro verzi 2017-07-29 nebo novější může být maximální hodnota Time to Live libovolné kladné číslo nebo -1, což znamená, že platnost zprávy nevyprší. Pokud tento parametr vynecháte, výchozí hodnota TTL (Time to Live) je sedm dnů.
Formát adresy URL: Fronty jsou adresovatelné pomocí následujícího formátu adresy URL: http://<storage account>.queue.core.windows.net/<queue>

Následující adresa URL odkazuje na frontu v diagramu:

http://myaccount.queue.core.windows.net/incoming-orders

Vytvoření účtu úložiště Azure

Nejjednodušší způsob, jak vytvořit první účet úložiště Azure, je použít Azure Portal. Další informace najdete v tématu Vytvoření účtu úložiště.

Účet úložiště Azure můžete vytvořit také pomocí prostředí Azure PowerShell, rozhraní příkazového řádku Azure nebo pomocí poskytovatele prostředků služby Azure Storage pro .NET.

Pokud v tuto chvíli nechcete vytvořit účet úložiště v Azure, můžete také použít emulátor úložiště Azurite ke spuštění a testování kódu v místním prostředí. Další informace najdete v tématu Použití emulátoru Azurite pro vývoj v místním úložišti Azure Storage.

Stáhnout a nainstalovat sadu SDK služby Azure Storage pro Python

Sada Azure Storage SDK pro Python vyžaduje Python verze 2.7, v3.3 nebo novější.

Instalace přes PyPI

Pokud chcete provést instalaci prostřednictvím indexu balíčků Pythonu (PyPI), zadejte:

pip install azure-storage-queue

Poznámka

Pokud upgradujete ze sady Sdk služby Azure Storage pro Python verze 0.36 nebo starší, před instalací nejnovějšího balíčku odinstalujte starší sadu SDK pomocí příkazu pip uninstall azure-storage .

Alternativní metody instalace najdete v tématu Azure SDK pro Python.

Zkopírování přihlašovacích údajů z webu Azure Portal

Když ukázková aplikace odešle žádost do Služby Azure Storage, musí být autorizována. Pokud chcete autorizovat žádost, přidejte do aplikace přihlašovací údaje účtu úložiště jako připojovací řetězec. Přihlašovací údaje účtu úložiště zobrazíte takto:

Přihlaste se k webu Azure Portal.
Vyhledejte svůj účet úložiště.
V podokně nabídek účtu úložiště v části Zabezpečení a sítě vyberte Přístupové klíče. Tady můžete zobrazit přístupové klíče účtu a úplný připojovací řetězec pro každý klíč.
V podokně Přístupové klíče vyberte Zobrazit klíče.
V části key1 vyhledejte hodnotu Připojovací řetězec . Výběrem ikony Zkopírovat do schránky zkopírujte připojovací řetězec. Hodnotu připojovacího řetězce přidáte do proměnné prostředí v další části.

Konfigurace připojovacího řetězce úložiště

Po zkopírování připojovacího řetězce ho zapište do nové proměnné prostředí na místním počítači, na kterém aplikace běží. Proměnnou prostředí nastavíte tak, že otevřete okno konzoly a budete postupovat podle pokynů pro váš operační systém. Nahraďte <yourconnectionstring> skutečným připojovacím řetězcem.

Windows
Linux a macOS

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Po přidání proměnné prostředí v systému Windows je nutné spustit novou instanci příkazového okna.

Restartujte programy

Po přidání proměnné prostředí restartujte všechny spuštěné programy, které budou potřebovat přečíst proměnnou prostředí. Než budete pokračovat, restartujte například vývojové prostředí nebo editor.

Konfigurace aplikace pro přístup ke službě Queue Storage

Objekt QueueClient umožňuje pracovat s frontou. Do horní části libovolného souboru Pythonu, ve kterém chcete programově přistupovat k frontě Azure, přidejte následující kód:

from azure.storage.queue import (
        QueueClient,
        BinaryBase64EncodePolicy,
        BinaryBase64DecodePolicy
)

import os, uuid

Balíček os poskytuje podporu pro načtení proměnné prostředí. Balíček uuid poskytuje podporu pro generování jedinečného identifikátoru pro název fronty.

Vytvoření fronty

Připojovací řetězec se načte z AZURE_STORAGE_CONNECTION_STRING dříve nastavené proměnné prostředí.

Následující kód vytvoří QueueClient objekt pomocí připojovacího řetězce úložiště.

# Retrieve the connection string from an environment
# variable named AZURE_STORAGE_CONNECTION_STRING
connect_str = os.getenv("AZURE_STORAGE_CONNECTION_STRING")

# Create a unique name for the queue
q_name = "queue-" + str(uuid.uuid4())

# Instantiate a QueueClient object which will
# be used to create and manipulate the queue
print("Creating queue: " + q_name)
queue_client = QueueClient.from_connection_string(connect_str, q_name)

# Create the queue
queue_client.create_queue()

Zprávy fronty Azure se ukládají jako text. Pokud chcete ukládat binární data, před vložením zprávy do fronty nastavte funkce kódování a dekódování Base64.

Při vytváření objektu klienta nakonfigurujte funkce kódování a dekódování Base64.

# Setup Base64 encoding and decoding functions
base64_queue_client = QueueClient.from_connection_string(
                            conn_str=connect_str, queue_name=q_name,
                            message_encode_policy = BinaryBase64EncodePolicy(),
                            message_decode_policy = BinaryBase64DecodePolicy()
                        )

Vložení zprávy do fronty

Pokud chcete vložit zprávu do fronty, použijte metodu send_message .

message = u"Hello World"
print("Adding message: " + message)
queue_client.send_message(message)

Náhled zpráv

Voláním metody můžete zobrazit náhled zpráv, aniž byste je odebrali z fronty peek_messages . Ve výchozím nastavení tato metoda nahlédne do jedné zprávy.

# Peek at the first message
messages = queue_client.peek_messages()

for peeked_message in messages:
    print("Peeked message: " + peeked_message.content)

Změna obsahu zpráv zařazených ve frontě

Podle potřeby můžete změnit obsah zprávy přímo ve frontě. Pokud zpráva představuje úkol, můžete pomocí této funkce aktualizovat stav úkolu.

Následující kód používá metodu update_message k aktualizaci zprávy. Časový limit viditelnosti je nastavený na 0, což znamená, že se zpráva zobrazí okamžitě a obsah se aktualizuje.

messages = queue_client.receive_messages()
list_result = next(messages)

message = queue_client.update_message(
        list_result.id, list_result.pop_receipt,
        visibility_timeout=0, content=u'Hello World Again')

print("Updated message to: " + message.content)

Získání délky fronty

Podle potřeby můžete získat odhadovaný počet zpráv ve frontě.

Metoda get_queue_properties vrátí vlastnosti fronty včetně approximate_message_count.

properties = queue_client.get_queue_properties()
count = properties.approximate_message_count
print("Message count: " + str(count))

Výsledek je pouze přibližný, protože zprávy je možné přidat nebo odebrat poté, co služba odpoví na vaši žádost.

Vyřazení zpráv z fronty

Odebrání zprávy z fronty ve dvou krocích Pokud se vašemu kódu nepodaří zpracovat zprávu, tento dvoustupňový proces zajistí, že můžete získat stejnou zprávu a zkusit to znovu. Po úspěšném zpracování zprávy volejte delete_message .

Při volání receive_messages se ve výchozím nastavení zobrazí další zpráva ve frontě. Zpráva vrácená z receive_messages této fronty se stane neviditelnou pro jakýkoli jiný kód, který čte zprávy z této fronty. Ve výchozím nastavení tato zpráva zůstává neviditelná po dobu 30 sekund. Chcete-li dokončit odebrání zprávy z fronty, musíte také volat delete_message.

messages = queue_client.receive_messages()

for message in messages:
    print("Dequeueing message: " + message.content)
    queue_client.delete_message(message.id, message.pop_receipt)

Načítání zpráv z fronty si můžete přizpůsobit dvěma způsoby. Za prvé si můžete načíst dávku zpráv (až 32). Za druhé si můžete nastavit delší nebo kratší časový limit neviditelnosti, aby měl váš kód více nebo méně času na úplné zpracování jednotlivých zpráv.

Následující příklad kódu používá metodu receive_messages k získání zpráv v dávkách. Potom zpracuje každou zprávu v rámci každé dávky pomocí vnořené smyčky for . Také se pro každou zprávu nastaví časový limit neviditelnosti 5 minut.

messages = queue_client.receive_messages(messages_per_page=5, visibility_timeout=5*60)

for msg_batch in messages.by_page():
   for msg in msg_batch:
      print("Batch dequeue message: " + msg.content)
      queue_client.delete_message(msg)

Odstranění fronty

Chcete-li odstranit frontu a všechny zprávy v ní obsažené, zavolejte metodu delete_queue .

print("Deleting queue: " + queue_client.queue_name)
queue_client.delete_queue()

Tip

Vyzkoušení Microsoft Azure Storage Exploreru

Microsoft Azure Storage Explorer je bezplatná samostatná aplikace od Microsoftu, která umožňuje vizuálně pracovat s daty Azure Storage ve Windows, macOS a Linuxu.

Další kroky

Teď, když jste se seznámili se základy služby Queue Storage, najdete další informace pomocí těchto odkazů.

Související ukázky kódu s využitím zastaralých sad SDK pythonu verze 2 najdete v tématu Ukázky kódu s využitím Pythonu verze 2.

Sdílet prostřednictvím