Использование хранилища очередей Azure из PythonHow to use Azure Queue Storage from Python

ОбзорOverview

В этой статье описываются распространенные сценарии использования службы хранилища очередей Azure.This article demonstrates common scenarios using the Azure Queue Storage service. К рассматриваемым сценариям относятся Вставка, просмотр, получение и удаление сообщений очереди.The scenarios covered include inserting, peeking, getting, and deleting queue messages. Также рассматривается код для создания и удаления очередей.Code for creating and deleting queues is also covered.

Примеры в этой статье написаны на языке Python и используют клиентскую библиотеку хранилища очередей Azure для Python.The examples in this article are written in Python and use the Azure Queue Storage client library for Python. Дополнительные сведения об очередях см. в разделе Дальнейшие действия.For more information on queues, see the Next steps section.

Что такое хранилище очередей?What is Queue storage?

Хранилище очередей Azure — это служба для хранения большого количества сообщений, к которым можно получить доступ практически из любой точки мира с помощью вызовов с проверкой подлинности по протоколам HTTP или 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. Одно сообщение очереди может быть размером до 64 КБ, а очередь может содержать миллионы сообщений до общего ограничения емкости учетной записи хранения.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. Хранилище очередей часто используется для создания невыполненной работы для асинхронной обработки.Queue storage is often used to create a backlog of work to process asynchronously.

Основные понятия службы очередейQueue service concepts

Служба очередей Azure содержит следующие компоненты:The Azure Queue service contains the following components:

Компоненты служба очередей Azure

  • Учетная запись хранения: Весь доступ к службе хранилища Azure осуществляется через учетную запись хранения.Storage Account: All access to Azure Storage is done through a storage account. См. сведения об учетных записях хранения.For more information about storage accounts, see Storage account overview.

  • Очередь. Очередь содержит набор сообщений.Queue: A queue contains a set of messages. Все сообщения должны находиться в очереди.All messages must be in a queue. Обратите внимание: имя очереди должно содержать только строчные символы.Note that the queue name must be all lowercase. Дополнительные сведения см. в статье о присвоении имен очередям и метаданным.For information on naming queues, see Naming Queues and Metadata.

  • Сообщение. Сообщение в любом формате размером до 64 КБ.Message: A message, in any format, of up to 64 KB. Сообщение может оставаться в очереди не более 7 дней.The maximum time that a message can remain in the queue is 7 days. Начиная с версии 2017-07-29, максимальный срок жизни может быть задан любым положительным числом или значением -1, свидетельствующим о том, что срок жизни сообщения неограничен.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. Если этот параметр не указан, срок жизни по умолчанию составляет семь дней.If this parameter is omitted, the default time-to-live is seven days.

  • Формат URL-адреса: Для адресации очередей используется следующий формат 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>

    Следующий URL-адрес позволяет обратиться к очереди на схеме:The following URL addresses a queue in the diagram:

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

Создание учетной записи хранения AzureCreate an Azure storage account

Самый простой способ создать первую учетную запись хранения Azure — воспользоваться порталом Azure.The easiest way to create your first Azure storage account is by using the Azure portal. Дополнительную информацию см. в статье Об учетных записях хранения Azure.To learn more, see Create a storage account.

Кроме того, создать учетную запись хранения Azure можно с помощью Azure PowerShell, Azure CLI или поставщика ресурсов службы хранилища Azure для .NET.You can also create an Azure storage account by using Azure PowerShell, Azure CLI, or the Azure Storage Resource Provider for .NET.

Если вы не хотите создавать учетную запись хранения в Azure в настоящее время, можно также использовать эмулятор хранения Азурите для запуска и тестирования кода в локальной среде.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. Дополнительные сведения см. в статье Использование эмулятора азурите для локальной разработки службы хранилища Azure.For more information, see Use the Azurite emulator for local Azure Storage development.

Загрузите и установите пакет SDK службы хранилища Azure для Python.Download and install Azure Storage SDK for Python

Для пакета SDK службы хранилища Azure для Python требуется версия Python версии 2.7, версия 3.3 или более поздняя.The Azure Storage SDK for Python requires Python v2.7, v3.3, or later.

Установка через PyPIInstall via PyPI

Для установки с помощью индекса пакетов Python (PyPI) введите:To install via the Python Package Index (PyPI), type:

pip install azure-storage-queue

Примечание

Если вы обновляете пакет SDK для службы хранилища Azure для Python v 0.36 или более ранней версии, удалите старый пакет SDK, используя pip uninstall azure-storage перед установкой последнего пакета.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.

Альтернативные способы установки см. в статье пакет Azure SDK для Python.For alternative installation methods, see Azure SDK for Python.

Копирование учетных данных с портала AzureCopy your credentials from the Azure portal

Когда пример приложения выполняет запрос к службе хранилища Azure, он должен быть авторизован.When the sample application makes a request to Azure Storage, it must be authorized. Для авторизации запроса добавьте в приложение учетные данные учетной записи хранения в виде строки подключения.To authorize a request, add your storage account credentials to the application as a connection string. Чтобы просмотреть учетные данные учетной записи хранения, выполните следующие действия:View your storage account credentials by following these steps:

  1. Войдите на портал Azure.Sign in to the Azure portal.

  2. Перейдите к учетной записи хранения.Locate your storage account.

  3. В разделе Параметры учетной записи хранения выберите параметр Ключи доступа.In the Settings section of the storage account overview, select Access keys. На этой странице вы увидите ключи доступа к учетной записи и полную строку подключения для каждого ключа.Here, you can view your account access keys and the complete connection string for each key.

  4. Найдите значение для параметра Строка подключения в разделе Key1 и нажмите кнопку Скопировать, чтобы скопировать строку подключения.Find the Connection string value under key1, and select the Copy button to copy the connection string. На следующем этапе вы добавите значение строки подключения в переменную среды.You will add the connection string value to an environment variable in the next step.

    Снимок экрана, на котором показано, как скопировать строку подключения с портала Azure

Настройка строки подключения хранилищаConfigure your storage connection string

После копирования строки подключения запишите ее в переменной среды на локальном компьютере, где выполняется приложение.After you have copied your connection string, write it to a new environment variable on the local machine running the application. Чтобы задать переменную среды, откройте окно консоли и следуйте инструкциям для используемой операционной системы.To set the environment variable, open a console window, and follow the instructions for your operating system. Замените <yourconnectionstring> фактической строкой подключения.Replace <yourconnectionstring> with your actual connection string.

WindowsWindows

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

После добавления переменной среды в Windows вам необходимо запустить новый экземпляр командного окна.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>"

Перезапуск программRestart programs

После добавления переменной среды перезапустите все запущенные программы, которым может понадобиться считать переменную среды.After you add the environment variable, restart any running programs that will need to read the environment variable. Например, перезапустите среду разработки или редактор, прежде чем продолжить.For example, restart your development environment or editor before continuing.

Настройка приложения для доступа к хранилищу очередейConfigure your application to access Queue Storage

QueueClientОбъект позволяет работать с очередью.The QueueClient object lets you work with a queue. Добавьте следующий код в начало любого файла Python, в котором вы хотите получить программный доступ к очереди Azure: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

osПакет обеспечивает поддержку для получения переменной среды.The os package provides support to retrieve an environment variable. uuidПакет обеспечивает поддержку создания уникального идентификатора для имени очереди.The uuid package provides support for generating a unique identifier for a queue name.

Создание очередиCreate a queue

Строка подключения извлекается из AZURE_STORAGE_CONNECTION_STRING переменной среды, установленной ранее.The connection string is retrieved from the AZURE_STORAGE_CONNECTION_STRING environment variable set earlier.

Следующий код создает объект, QueueClient используя строку подключения к хранилищу.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()

Сообщения в очереди Azure хранятся в виде текста.Azure queue messages are stored as text. Если вы хотите хранить двоичные данные, настройте функции кодирования и декодирования Base64 перед помещением сообщения в очередь.If you want to store binary data, setup Base64 encoding and decoding functions before putting a message in the queue.

Настройка функций кодирования и декодирования 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()
                        )

Вставка сообщения в очередьInsert a message into a queue

Чтобы вставить сообщение в очередь, используйте send_message метод.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)

Просмотр сообщенийPeek at messages

Вы можете просматривать сообщения, не удаляя их из очереди, вызывая peek_messages метод.You can peek at messages without removing them from the queue by calling the peek_messages method. По умолчанию этот метод считывает одно сообщение.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)

Изменение содержимого сообщения в очередиChange the contents of a queued message

Вы можете изменить содержимое сообщения непосредственно в очереди.You can change the contents of a message in-place in the queue. Если сообщение представляет задачу, эту функцию можно использовать для обновления состояния задачи.If the message represents a task, you can use this feature to update the status of the task.

В следующем коде метод используется update_message для обновления сообщения.The following code uses the update_message method to update a message. Время ожидания видимости равно 0. Это означает, что сообщение появится немедленно, и содержимое обновится.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)

Получение длины очередиGet the queue length

Вы можете узнать приблизительное количество сообщений в очереди.You can get an estimate of the number of messages in a queue.

Метод get_queue_properties Возвращает свойства очереди, включая 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))

Результат является приблизительным, так как сообщения могут добавляться или удаляться после ответа службы на ваш запрос.The result is only approximate because messages can be added or removed after the service responds to your request.

Вывод сообщений из очередиDequeue messages

Удаление сообщения из очереди в два этапа.Remove a message from a queue in two steps. Если код не может обработать сообщение, этот двухэтапный процесс гарантирует, что вы получите то же сообщение и повторите попытку.If your code fails to process a message, this two-step process ensures that you can get the same message and try again. Вызов delete_message после успешной обработки сообщения.Call delete_message after the message has been successfully processed.

При вызове receive_messagesвы получаете следующее сообщение в очереди по умолчанию.When you call receive_messages, you get the next message in the queue by default. Сообщение, возвращаемое методом receive_messages, становится невидимым для другого кода, считывающего сообщения из этой очереди.A message returned from receive_messages becomes invisible to any other code reading messages from this queue. По умолчанию это сообщение остается невидимым в течение 30 секунд.By default, this message stays invisible for 30 seconds. Чтобы завершить удаление сообщения из очереди, необходимо также вызвать 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)

Способ извлечения сообщения из очереди можно настроить двумя способами.There are two ways you can customize message retrieval from a queue. Во-первых, можно получить пакет сообщений (до 32 сообщений).First, you can get a batch of messages (up to 32). Во-вторых, можно задать более длительное или короткое время ожидания видимости, чтобы предоставить коду больше или меньше времени на полную обработку каждого сообщения.Second, you can set a longer or shorter invisibility timeout, allowing your code more or less time to fully process each message.

В следующем примере кода метод используется receive_messages для получения сообщений в пакетах.The following code example uses the receive_messages method to get messages in batches. Затем он обрабатывает каждое сообщение в каждом пакете с помощью вложенного for цикла.Then it processes each message within each batch by using a nested for loop. Он также задает время ожидания невидимости 5 минут для каждого сообщения.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)

Удаление очередиDelete a queue

Чтобы удалить очередь и все сообщения, содержащиеся в ней, вызовите delete_queue метод.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()

Совет

Пробное использование обозревателя хранилищ Microsoft AzureTry the Microsoft Azure Storage Explorer

Обозреватель хранилищ Microsoft Azure — это бесплатное автономное приложение от корпорации Майкрософт, позволяющее визуализировать данные из службы хранилища Azure на платформе Windows, macOS и Linux.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.

Дальнейшие действияNext steps

Теперь, когда вы узнали основные сведения о хранилище очередей, воспользуйтесь следующими ссылками для получения дополнительных сведений.Now that you've learned the basics of Queue Storage, follow these links to learn more.