Rychlý start: Klientská knihovna Azure Queue Storage pro Python

Začínáme s klientskou knihovnou Azure Queue Storage pro Python Azure Queue Storage je služba pro ukládání velkého počtu zpráv pro pozdější načtení a zpracování. Pomocí těchto kroků nainstalujte balíček a vyzkoušejte si ukázkový kód pro základní úlohy.

Referenční dokumentace k | rozhraní API – Ukázka balíčku zdrojového kódu | knihovny (index balíčků Pythonu) |

Pomocí klientské knihovny Azure Queue Storage pro Python můžete:

• Vytvořit frontu
• Přidání zpráv do fronty
• Náhled zpráv ve frontě
• Aktualizace zprávy ve frontě
• Získání délky fronty
• Příjem zpráv z fronty
• Odstranění zpráv z fronty
• Odstranění fronty

Požadavky

• Předplatné Azure – vytvoření bezplatného předplatného
• Účet služby Azure Storage – Vytvoření účtu úložiště
• Python 3.8 nebo novější

Nastavení

Tato část vás provede přípravou projektu pro práci s klientskou knihovnou Azure Queue Storage pro Python.

Vytvoření projektu

Vytvořte aplikaci v Pythonu s názvem queues-quickstart.

1. V okně konzoly (například cmd, PowerShell nebo Bash) vytvořte pro projekt nový adresář.

   mkdir queues-quickstart
   

2. Přepněte do nově vytvořeného adresáře queues-quickstart .

   cd queues-quickstart
   

Instalace balíčků

Z adresáře projektu pomocí příkazu nainstalujte klientskou knihovnu Azure Queue Storage pro balíček Pythonu pip install . Balíček azure-identity je potřeba pro připojení bez hesla ke službám Azure.

pip install azure-storage-queue azure-identity

Nastavení architektury aplikace

1. Otevření nového textového souboru v editoru kódu

2. Add import – příkazy

3. Vytvoření struktury pro program, včetně základního zpracování výjimek

   Tady je kód:

   import os, uuid
   from azure.identity import DefaultAzureCredential
   from azure.storage.queue import QueueServiceClient, QueueClient, QueueMessage, BinaryBase64DecodePolicy, BinaryBase64EncodePolicy
   
   try:
       print("Azure Queue storage - Python quickstart sample")
       # Quickstart code goes here
   except Exception as ex:
       print('Exception:')
       print(ex)
   
   

4. Uložte nový soubor jako queues-quickstart.py v adresáři queues-quickstart .

Ověřování v Azure

Žádosti o aplikace na většinu služeb Azure musí být autorizované. DefaultAzureCredential Použití třídy poskytované klientskou knihovnou Azure Identity je doporučeným přístupem k implementaci připojení bez hesel ke službám Azure ve vašem kódu.

Žádosti o služby Azure můžete také autorizovat pomocí hesel, připojovací řetězec nebo jiných přihlašovacích údajů přímo. Tento přístup by však měl být používán s opatrností. Vývojáři musí být usilovní, aby tyto tajné kódy nikdy nezpřístupnili v nezabezpečeném umístění. Každý, kdo získá přístup k heslu nebo tajnému klíči, se může ověřit. DefaultAzureCredential nabízí vylepšené výhody správy a zabezpečení oproti klíči účtu, které umožňují ověřování bez hesla. Obě možnosti jsou demonstrována v následujícím příkladu.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

az role assignment create --assignee "<user@domain>" \
    --role "Storage Queue Data Contributor" \
    --scope "<your-resource-id>"

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Queue Data Contributor" `
    -Scope <yourStorageAccountId>

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Objektový model

Azure Queue Storage je služba pro ukládání velkých objemů zpráv. Zpráva fronty může mít velikost až 64 kB. Fronta může obsahovat miliony zpráv až do celkového limitu kapacity účtu úložiště. Fronty se běžně používají k vytvoření backlogu práce pro asynchronní zpracování. Queue Storage nabízí tři typy prostředků:

• Úč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 účtu ú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. Zpráva může zůstat ve frontě maximálně 7 dní. Pro verzi 2017-07-29 nebo novější může být maximální doba k živému přenosu libovolné kladné číslo nebo -1 označující, že platnost zprávy nevyprší. Pokud tento parametr vynecháte, výchozí hodnota time-to-live je sedm dní.

Na následujícím diagramu jsou vztahy těchto prostředků.

K interakci s těmito prostředky použijte následující třídy Pythonu:

• QueueServiceClient: Umožňuje QueueServiceClient spravovat všechny fronty ve vašem účtu úložiště.
• QueueClient: Třída QueueClient umožňuje spravovat a manipulovat s jednotlivými fronty a jejími zprávami.
• QueueMessage: Třída QueueMessage představuje jednotlivé objekty vrácené při volání receive_messages do fronty.

Příklady kódu

Tyto ukázkové fragmenty kódu ukazují, jak pomocí klientské knihovny Azure Queue Storage pro Python provést následující akce:

• Autorizace přístupu a vytvoření objektu klienta
• Vytvoření fronty
• Přidání zpráv do fronty
• Náhled zpráv ve frontě
• Aktualizace zprávy ve frontě
• Získání délky fronty
• Příjem zpráv z fronty
• Odstranění zpráv z fronty
• Odstranění fronty

az login

az login

Connect-AzAccount

from azure.identity import DefaultAzureCredential

    print("Azure Queue storage - Python quickstart sample")

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

    account_url = "https://<storageaccountname>.queue.core.windows.net"
    default_credential = DefaultAzureCredential()

    # Create the QueueClient object
    # We'll use this object to create and interact with the queue
    queue_client = QueueClient(account_url, queue_name=queue_name ,credential=default_credential)

    print("Azure Queue storage - Python quickstart sample")

    # Retrieve the connection string for use with the application. The storage
    # connection string is stored in an environment variable on the machine
    # running the application called AZURE_STORAGE_CONNECTION_STRING. If the
    # environment variable is created after the application is launched in a
    # console or with Visual Studio, the shell or application needs to be
    # closed and reloaded to take the environment variable into account.
    connect_str = os.getenv('AZURE_STORAGE_CONNECTION_STRING')

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

    print("Creating queue: " + queue_name)

    # Instantiate a QueueClient which will be
    # used to create and manipulate the queue
    queue_client = QueueClient.from_connection_string(connect_str, queue_name)

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

Při vytváření objektu klienta můžete nakonfigurovat kódování a dekódování funkcí 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()
                        )

Vytvořit frontu

Pomocí objektu QueueClient zavolejte metodu create_queue pro vytvoření fronty v účtu úložiště.

Přidejte tento kód na konec try bloku:

    print("Creating queue: " + queue_name)

    # Create the queue
    queue_client.create_queue()

Přidání zpráv do fronty

Následující fragment kódu přidá zprávy do fronty voláním send_message metody. Uloží také vrácené QueueMessage volání z třetího send_message volání. Slouží saved_message k aktualizaci obsahu zprávy později v programu.

Přidejte tento kód na konec try bloku:

    print("\nAdding messages to the queue...")

    # Send several messages to the queue
    queue_client.send_message(u"First message")
    queue_client.send_message(u"Second message")
    saved_message = queue_client.send_message(u"Third message")

Náhled zpráv ve frontě

Prohlédněte si zprávy ve frontě voláním peek_messages metody. Tato metoda načte jednu nebo více zpráv z přední části fronty, ale nezmění viditelnost zprávy.

Přidejte tento kód na konec try bloku:

    print("\nPeek at the messages in the queue...")

    # Peek at messages in the queue
    peeked_messages = queue_client.peek_messages(max_messages=5)

    for peeked_message in peeked_messages:
        # Display the message
        print("Message: " + peeked_message.content)

Aktualizace zprávy ve frontě

Aktualizujte obsah zprávy voláním update_message metody. Tato metoda může změnit časový limit viditelnosti a obsah zprávy. Obsah zprávy musí být řetězec s kódováním UTF-8, který má velikost až 64 kB. Spolu s novým obsahem předejte hodnoty ze zprávy, která byla uložena dříve v kódu. Hodnoty saved_message identifikují, která zpráva se má aktualizovat.

    print("\nUpdating the third message in the queue...")

    # Update a message using the message saved when calling send_message earlier
    queue_client.update_message(saved_message, pop_receipt=saved_message.pop_receipt, \
        content="Third message has been updated")

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 přibližný, protože zprávy je možné přidat nebo odebrat poté, co služba odpoví na vaši žádost.

Příjem zpráv z fronty

Dříve přidané zprávy si můžete stáhnout voláním receive_messages metody.

Přidejte tento kód na konec try bloku:

    print("\nReceiving messages from the queue...")

    # Get messages from the queue
    messages = queue_client.receive_messages(max_messages=5)

Při volání receive_messages metody můžete volitelně zadat hodnotu pro max_messages, což je počet zpráv, které se mají načíst z fronty. Výchozí hodnota je 1 zpráva a maximum je 32 zpráv. Můžete také zadat hodnotu pro visibility_timeout, která skryje zprávy z jiných operací pro období časového limitu. Výchozí hodnota je 30 sekund.

Odstranění zpráv z fronty

Po přijetí a zpracování odstraňte zprávy z fronty. V tomto případě se při zpracování jenom zobrazí zpráva v konzole.

Aplikace se pozastaví pro uživatelský vstup voláním input předtím, než zpracuje a odstraní zprávy. Před odstraněním ověřte na webu Azure Portal , že se prostředky správně vytvořily. Všechny zprávy, které se explicitně neodstraní, se nakonec znovu zviditelní ve frontě, aby se daly zpracovat.

Přidejte tento kód na konec try bloku:

    print("\nPress Enter key to 'process' messages and delete them from the queue...")
    input()

    for msg_batch in messages.by_page():
            for msg in msg_batch:
                # "Process" the message
                print(msg.content)
                # Let the service know we're finished with
                # the message and it can be safely deleted.
                queue_client.delete_message(msg)

Odstranění fronty

Následující kód vyčistí prostředky vytvořené aplikací odstraněním fronty delete_queue pomocí metody.

Přidejte tento kód na konec try bloku a soubor uložte:

    print("\nPress Enter key to delete the queue...")
    input()

    # Clean up
    print("Deleting queue...")
    queue_client.delete_queue()

    print("Done")

Spuštění kódu

Tato aplikace vytvoří a přidá do fronty Azure tři zprávy. Kód zobrazí seznam zpráv ve frontě a potom je načte a odstraní, a teprve potom frontu odstraní.

V okně konzoly přejděte do adresáře obsahujícího soubor queues-quickstart.py a pak pomocí následujícího python příkazu spusťte aplikaci.

python queues-quickstart.py

Výstup aplikace je podobný následujícímu příkladu:

Azure Queue Storage client library - Python quickstart sample
Creating queue: quickstartqueues-<UUID>

Adding messages to the queue...

Peek at the messages in the queue...
Message: First message
Message: Second message
Message: Third message

Updating the third message in the queue...

Receiving messages from the queue...

Press Enter key to 'process' messages and delete them from the queue...

First message
Second message
Third message has been updated

Press Enter key to delete the queue...

Deleting queue...
Done

Když se aplikace pozastaví před příjmem zpráv, zkontrolujte svůj účet úložiště na webu Azure Portal. Ověřte, že jsou zprávy ve frontě.

Stisknutím klávesy Enter zprávy přijmete a odstraníte. Po zobrazení výzvy znovu stisknutím klávesy Enter odstraňte frontu a dokončete ukázku.

Další kroky

V tomto rychlém startu jste zjistili, jak vytvořit frontu a přidat do ní zprávy pomocí kódu Pythonu. Pak jste se naučili zobrazit, načíst a odstranit zprávy. Nakonec jste zjistili, jak odstranit frontu zpráv.

Kurzy, ukázky, rychlé starty a další dokumentace najdete tady:

• Související ukázky kódu s využitím zastaralých sad SDK pro Python verze 2 najdete v ukázkách kódu s využitím Pythonu verze 2.
• Další informace najdete v knihovnách Azure Storage pro Python.
• Další ukázkové aplikace Azure Queue Storage najdete v klientské knihovně Azure Queue Storage pro Python – ukázky.