Jak používat Azure Queue Storage z PythonuHow to use Azure Queue Storage from Python

PřehledOverview

Tento článek popisuje běžné scénáře použití služby Azure Queue Storage.This article demonstrates common scenarios using the Azure Queue Storage service. Mezi zahrnuté scénáře patří vkládání, prohlížení, získávání a odstraňování zpráv fronty.The scenarios covered include inserting, peeking, getting, and deleting queue messages. Kód pro vytváření a odstraňování front je také pokrytý.Code for creating and deleting queues is also covered.

Příklady v tomto článku jsou napsané v Pythonu a používají klientskou knihovnu Azure Queue Storage pro Python.The examples in this article are written in Python and use the Azure Queue Storage client library for Python. Další informace o frontách najdete v části Další kroky .For more information on queues, see the Next steps section.

Co je Queue Storage?What is 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.Azure Queue storage is a service for storing large numbers of messages that can be accessed from anywhere in the world via authenticated calls using HTTP or 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ě.A single queue message can be up to 64 KB in size, and a queue can contain millions of messages, up to the total capacity limit of a storage account. Fronta úložiště se často používá k vytvoření nevyřízených položek pro asynchronní zpracování.Queue storage is often used to create a backlog of work to process asynchronously.

Služba front konceptyQueue service concepts

Služba front Azure obsahuje následující komponenty:The Azure Queue service contains the following components:

Součásti Azure Služba front

  • Účet úložiště: Veškerý přístup ke službě Azure Storage se provádí prostřednictvím účtu úložiště.Storage Account: All access to Azure Storage is done through a storage account. Další informace o účtech úložiště najdete v tématu Přehled účtu úložiště.For more information about storage accounts, see Storage account overview.

  • Fronta: Fronta obsahuje sadu zpráv.Queue: A queue contains a set of messages. Všechny zprávy musí být ve frontě.All messages must be in a queue. Upozorňujeme, že název fronty musí být psaný malými písmeny.Note that the queue name must be all lowercase. Informace o pojmenování front najdete v tématu Pojmenování front a metadata.For information on naming queues, see Naming Queues and Metadata.

  • Zpráva: Zprávu v libovolném formátu o velikosti až 64 kB.Message: A message, in any format, of up to 64 KB. Maximální doba, po kterou může zpráva zůstat ve frontě, je 7 dní.The maximum time that a message can remain in the queue is 7 days. V případě verze 2017-07-29 nebo novější může být maximální doba do živého kladného čísla nebo-1, což znamená, že platnost zprávy nevyprší.For version 2017-07-29 or later, the maximum time-to-live can be any positive number, or -1 indicating that the message doesn't expire. Pokud je tento parametr vynechán, výchozí hodnota TTL (Time to Live) je sedm dní.If this parameter is omitted, the default time-to-live is seven days.

  • Formát adresy URL: Fronty jsou adresovatelné v následujícím formátu adresy URL: http:// <storage account> . Queue.Core.Windows.NET/<queue>URL format: Queues are addressable using the following URL format: http://<storage account>.queue.core.windows.net/<queue>

    Následující adresa URL odkazuje na frontu v diagramu:The following URL addresses a queue in the diagram:

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

Vytvoření účtu úložiště AzureCreate an Azure storage account

Nejjednodušší způsob, jak vytvořit první účet úložiště Azure, je pomocí Azure Portal.The easiest way to create your first Azure storage account is by using the Azure portal. Další informace najdete v tématu Vytvoření účtu úložiště.To learn more, see Create a storage account.

Úč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.You can also create an Azure storage account by using Azure PowerShell, Azure CLI, or the Azure Storage Resource Provider for .NET.

Pokud nechcete v Azure v tuto chvíli vytvářet účet úložiště, můžete použít taky emulátor úložiště Azurite ke spuštění a testování kódu v místním prostředí.If you prefer not to create a storage account in Azure at this time, you can also use the Azurite storage emulator to run and test your code in a local environment. Další informace najdete v tématu použití emulátoru Azurite pro vývoj místních Azure Storage.For more information, see Use the Azurite emulator for local Azure Storage development.

Stáhnout a nainstalovat sadu SDK služby Azure Storage pro PythonDownload and install Azure Storage SDK for Python

Sada SDK Azure Storage pro Python vyžaduje Python v 2.7, v 3.3 nebo novější verzi.The Azure Storage SDK for Python requires Python v2.7, v3.3, or later.

Instalace prostřednictvím PyPIInstall via PyPI

K instalaci prostřednictvím indexu balíčku Pythonu (PyPI) zadejte:To install via the Python Package Index (PyPI), type:

pip install azure-storage-queue

Poznámka

Pokud upgradujete z Azure Storage SDK pro Python v 0.36 nebo starší verzi, odinstalujte starší sadu SDK pomocí nástroje pip uninstall azure-storage před instalací nejnovějšího balíčku.If you are upgrading from the Azure Storage SDK for Python v0.36 or earlier, uninstall the older SDK using pip uninstall azure-storage before installing the latest package.

Alternativní metody instalace najdete v tématu sada Azure SDK pro Python.For alternative installation methods, see Azure SDK for Python.

Zkopírování přihlašovacích údajů z webu Azure PortalCopy your credentials from the Azure portal

Když ukázková aplikace odešle požadavek na Azure Storage, musí být ověřena.When the sample application makes a request to Azure Storage, it must be authorized. K autorizaci žádosti přidejte do aplikace přihlašovací údaje účtu úložiště jako připojovací řetězec.To authorize a request, add your storage account credentials to the application as a connection string. Přihlašovací údaje účtu úložiště zobrazíte pomocí následujícího postupu:View your storage account credentials by following these steps:

  1. Přihlaste se k portálu Azure Portal.Sign in to the Azure portal.

  2. Vyhledejte svůj účet úložiště.Locate your storage account.

  3. V části Nastavení v přehledu účtu úložiště vyberte Přístupové klíče.In the Settings section of the storage account overview, select Access keys. Tady se zobrazí přístupové klíče vašeho účtu a úplný připojovací řetězec pro jednotlivé klíče.Here, you can view your account access keys and the complete connection string for each key.

  4. V části key1 vyhledejte hodnotu Připojovací řetězec a výběrem tlačítka Kopírovat zkopírujte připojovací řetězec.Find the Connection string value under key1, and select the Copy button to copy the connection string. V dalším kroku přidáte hodnotu připojovacího řetězce do proměnné prostředí.You will add the connection string value to an environment variable in the next step.

    Snímek obrazovky ukazující zkopírování připojovacího řetězce z webu Azure Portal

Konfigurace připojovacího řetězce úložištěConfigure your storage connection string

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 aplikaci spouštíte.After you have copied your connection string, write it to a new environment variable on the local machine running the application. Proměnnou prostředí nastavíte tak, že otevřete okno konzoly a budete postupovat podle pokynů pro váš operační systém.To set the environment variable, open a console window, and follow the instructions for your operating system. Nahraďte <yourconnectionstring> skutečným připojovacím řetězcem.Replace <yourconnectionstring> with your actual connection string.

WindowsWindows

setx 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.After you add the environment variable in Windows, you must start a new instance of the command window.

LinuxLinux

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

macOSmacOS

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Restartovat programyRestart programs

Po přidání proměnné prostředí restartujte všechny spuštěné programy, které budou muset číst proměnnou prostředí.After you add the environment variable, restart any running programs that will need to read the environment variable. Před pokračováním například restartujte vývojové prostředí nebo editor.For example, restart your development environment or editor before continuing.

Konfigurace aplikace pro přístup k Queue StorageConfigure your application to access Queue Storage

QueueClientObjekt vám umožní pracovat s frontou.The QueueClient object lets you work with a queue. V horní části každého souboru Pythonu, ve kterém chcete programově přistupovat ke frontě Azure, přidejte následující kód:Add the following code near the top of any Python file in which you wish to programmatically access an Azure queue:

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

import os, uuid

osBalíček poskytuje podporu pro načtení proměnné prostředí.The os package provides support to retrieve an environment variable. uuidBalíček poskytuje podporu pro vygenerování jedinečného identifikátoru pro název fronty.The uuid package provides support for generating a unique identifier for a queue name.

Vytvoření frontyCreate a queue

Připojovací řetězec je načten z AZURE_STORAGE_CONNECTION_STRING dříve nastavené proměnné prostředí.The connection string is retrieved from the AZURE_STORAGE_CONNECTION_STRING environment variable set earlier.

Následující kód vytvoří QueueClient objekt pomocí připojovacího řetězce úložiště.The following code creates a QueueClient object using the storage connection string.

# 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.Azure queue messages are stored as text. Pokud chcete uložit binární data, nastavte funkce kódování a dekódování Base64 před vložením zprávy do fronty.If you want to store binary data, setup Base64 encoding and decoding functions before putting a message in the queue.

Při vytváření objektu klienta nakonfigurujte funkce kódování a dekódování base64.Configure Base64 encoding and decoding functions when creating the client object.

# 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 frontyInsert a message into a queue

Chcete-li vložit zprávu do fronty, použijte send_message metodu.To insert a message into a queue, use the send_message method.

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

Prohlížet zprávyPeek at messages

Můžete prohlížet zprávy bez jejich odebrání z fronty voláním peek_messages metody.You can peek at messages without removing them from the queue by calling the peek_messages method. Ve výchozím nastavení tato metoda prohlédne jednu zprávu.By default, this method peeks at a single message.

# 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ěChange the contents of a queued message

Podle potřeby můžete změnit obsah zprávy přímo ve frontě.You can change the contents of a message in-place in the queue. Pokud zpráva představuje úkol, můžete tuto funkci použít k aktualizaci stavu úlohy.If the message represents a task, you can use this feature to update the status of the task.

Následující kód používá update_message metodu k aktualizaci zprávy.The following code uses the update_message method to update a message. Časový limit viditelnosti je nastavený na 0, což znamená, že se zpráva zobrazuje hned a obsah se aktualizuje.The visibility timeout is set to 0, meaning the message appears immediately and the content is updated.

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 frontyGet the queue length

Podle potřeby můžete získat odhadovaný počet zpráv ve frontě.You can get an estimate of the number of messages in a queue.

Metoda get_queue_properties vrátí vlastnosti fronty včetně approximate_message_count .The get_queue_properties method returns queue properties including the 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 je možné přidat nebo odebrat zprávy poté, co služba odpoví na vaši žádost.The result is only approximate because messages can be added or removed after the service responds to your request.

Vyřadit zprávy z frontyDequeue messages

Odeberte zprávu z fronty ve dvou krocích.Remove a message from a queue in two steps. Pokud kód nedokáže zpracovat zprávu, tento proces se dvěma kroky zajistí, že můžete získat stejnou zprávu a zkusit to znovu.If your code fails to process a message, this two-step process ensures that you can get the same message and try again. Zavolejte delete_message po úspěšném zpracování zprávy.Call delete_message after the message has been successfully processed.

Když zavoláte receive_messages, ve výchozím nastavení se ve frontě zobrazí další zpráva.When you call receive_messages, you get the next message in the queue by default. Zpráva vrácená z receive_messages se bude neviditelná pro jakýkoliv jiný kód, který čte zprávy z této fronty.A message returned from receive_messages becomes invisible to any other code reading messages from this queue. Ve výchozím nastavení tato zpráva zůstává neviditelná po dobu 30 sekund.By default, this message stays invisible for 30 seconds. Chcete-li dokončit odebrání zprávy z fronty, je nutné také volat delete_message.To finish removing the message from the queue, you must also call 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.There are two ways you can customize message retrieval from a queue. Za prvé si můžete načíst dávku zpráv (až 32).First, you can get a batch of messages (up to 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.Second, you can set a longer or shorter invisibility timeout, allowing your code more or less time to fully process each message.

Následující příklad kódu používá receive_messages metodu k získání zpráv v dávkách.The following code example uses the receive_messages method to get messages in batches. Potom zpracuje každou zprávu v rámci každé dávky pomocí vnořené for smyčky.Then it processes each message within each batch by using a nested for loop. Také se pro každou zprávu nastaví časový limit neviditelnosti 5 minut.It also sets the invisibility timeout to five minutes for each message.

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í frontyDelete a queue

Pokud chcete odstranit frontu a všechny zprávy, které jsou v ní obsažené, zavolejte delete_queue metodu.To delete a queue and all the messages contained in it, call the delete_queue method.

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

Tip

Vyzkoušení Microsoft Azure Storage ExploreruTry the Microsoft Azure Storage Explorer

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.Microsoft Azure Storage Explorer is a free, standalone app from Microsoft that enables you to work visually with Azure Storage data on Windows, macOS, and Linux.

Další krokyNext steps

Teď, když jste se naučili základy Queue Storage, přečtěte si následující odkazy, kde najdete další informace.Now that you've learned the basics of Queue Storage, follow these links to learn more.