Поделиться через

Клиентская библиотека очередей службы хранилища Azure для Python версии 12.9.0

  • Статья

Хранилище очередей Azure — это служба для хранения большого количества сообщений, к которым можно получить доступ практически из любой точки мира с помощью вызовов с проверкой подлинности по протоколам HTTP или HTTPS. Размер одного сообщения очереди может составлять до 64 КиБ, а очередь может содержать миллионы сообщений до общего ограничения емкости учетной записи хранения.

Наиболее частые способы использования хранилища очередей включают:

  • создание списка невыполненных работ для асинхронной обработки;
  • Передача сообщений между разными частями распределенного приложения

Исходный код | Пакет (PyPI) | Пакет (Conda) | Справочная документация по | APIДокументация по продукту | Образцы

Начало работы

Предварительные требования

Установка пакета

Установите клиентую библиотеку очередей службы хранилища Azure для Python с помощью pip:

pip install azure-storage-queue

Создание учетной записи хранения

Если вы хотите создать учетную запись хранения, можно использовать портал Azure, Azure PowerShell или Azure CLI:

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

Создание клиента

Клиентская библиотека очередей службы хранилища Azure для Python позволяет взаимодействовать с тремя типами ресурсов: самой учетной записью хранения, очередями и сообщениями. Взаимодействие с этими ресурсами начинается с экземпляра клиента. Чтобы создать клиентский объект, вам потребуется URL-адрес конечной точки службы очереди учетной записи хранения и учетные данные, позволяющие получить доступ к учетной записи хранения:

from azure.storage.queue import QueueServiceClient

service = QueueServiceClient(account_url="https://<my-storage-account-name>.queue.core.windows.net/", credential=credential)

Поиск URL-адреса учетной записи

URL-адрес службы очередей учетной записи хранения можно найти с помощью портала Azure, Azure PowerShell или Azure CLI:

# Get the queue service URL for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.queue"

Типы учетных данных

Параметр credential может быть предоставлен в различных формах в зависимости от типа авторизации , которую вы хотите использовать:

  1. Чтобы использовать маркер подписанного URL-адреса (SAS), укажите маркер в виде строки. Если URL-адрес учетной записи содержит маркер SAS, опустите параметр учетных данных. Вы можете создать маркер SAS на портале Azure в разделе "Подписанный URL-адрес" или использовать одну из generate_sas() функций для создания маркера SAS для учетной записи хранения или очереди:

    from datetime import datetime, timedelta
from azure.storage.queue import QueueServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    start=datetime.utcnow(),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

queue_service_client = QueueServiceClient(account_url="https://<my_account_name>.queue.core.windows.net", credential=sas_token)

  2. Чтобы использовать общий ключ учетной записи хранения (он же ключ учетной записи или ключ доступа), укажите ключ в виде строки. Их можно найти на портале Azure в разделе "Ключи доступа" или с помощью следующей команды Azure CLI:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    Используйте ключ в качестве параметра учетных данных для проверки подлинности клиента:

    from azure.storage.queue import QueueServiceClient
service = QueueServiceClient(account_url="https://<my_account_name>.queue.core.windows.net", credential="<account_access_key>")

  3. Чтобы использовать учетные данные маркера Azure Active Directory (AAD), укажите экземпляр нужного типа учетных данных, полученных из библиотеки azure-identity . Например, для проверки подлинности клиента можно использовать DefaultAzureCredential .

    Для этого требуется некоторая начальная настройка:

    Используйте возвращенные учетные данные маркера для проверки подлинности клиента:

        from azure.identity import DefaultAzureCredential
    from azure.storage.queue import QueueServiceClient
    token_credential = DefaultAzureCredential()

    queue_service_client = QueueServiceClient(
        account_url="https://<my_account_name>.queue.core.windows.net",
        credential=token_credential
    )

Создание клиента из строка подключения

В зависимости от варианта использования и метода авторизации можно инициализировать экземпляр клиента с помощью строка подключения хранилища вместо того, чтобы отдельно указывать URL-адрес учетной записи и учетные данные. Для этого передайте строка подключения хранилища методу класса клиентаfrom_connection_string:

from azure.storage.queue import QueueServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = QueueServiceClient.from_connection_string(conn_str=connection_string)

Строка подключения учетной записи хранения можно найти на портале Azure в разделе "Ключи доступа" или с помощью следующей команды CLI:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

Основные понятия

Служба очередей Azure состоит из следующих компонентов:

  • Сама учетная запись хранения
  • Очередь в учетной записи хранения, которая содержит набор сообщений.
  • Сообщение в очереди в любом формате до 64 КиБ

Клиентская библиотека очередей службы хранилища Azure для Python позволяет взаимодействовать с каждым из этих компонентов с помощью выделенного клиентского объекта.

Асинхронные клиенты

Эта библиотека включает полный асинхронный API, поддерживаемый в Python 3.5 и более поздних версий. Чтобы использовать его, необходимо сначала установить асинхронный транспорт, например aiohttp. Дополнительные сведения см. в документации по azure-core .

Асинхронные клиенты и учетные данные должны быть закрыты, если они больше не нужны. Эти объекты являются диспетчерами асинхронного контекста и определяют асинхронные close методы.

Клиенты

Для взаимодействия с различными компонентами службы очередей предоставляются два разных клиента:

  1. QueueServiceClient — этот клиент представляет взаимодействие с самой учетной записью хранения Azure и позволяет получать предварительно настроенные экземпляры клиента для доступа к очередям внутри. Он предоставляет операции по получению и настройке свойств учетной записи, а также перечислению, созданию и удалению очередей в учетной записи. Чтобы выполнить операции с определенной очередью, получите клиент с помощью get_queue_client метода .
  2. QueueClient — этот клиент представляет взаимодействие с определенной очередью (которая еще не должна существовать). Он предоставляет операции по созданию, удалению или настройке очереди и включает операции по отправке, получению, просмотру, удалению и обновлению сообщений в ней.

Сообщения

  • Отправить — добавляет сообщение в очередь и при необходимости устанавливает время ожидания видимости для сообщения.
  • Получение — извлекает сообщение из очереди и делает его невидимым для других потребителей.
  • Обзор — извлекает сообщение из передней части очереди без изменения видимости сообщения.
  • Обновление — Обновления время ожидания видимости сообщения и (или) его содержимого.
  • Удалить — удаляет указанное сообщение из очереди.
  • Очистить — удаляет все сообщения из очереди.

Примеры

В следующих разделах представлено несколько фрагментов кода, охватывающих некоторые из наиболее распространенных задач очереди хранилища, в том числе:

Создание очереди

Создание очереди в учетной записи хранения

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
queue.create_queue()

Создание очереди с помощью асинхронного клиента

from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
await queue.create_queue()

Отправка сообщений

Отправка сообщений в очередь

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
queue.send_message("I'm using queues!")
queue.send_message("This is my second message")

Асинхронная отправка сообщений

import asyncio
from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
await asyncio.gather(
    queue.send_message("I'm using queues!"),
    queue.send_message("This is my second message")
)

Получение сообщений

Получение и обработка сообщений из очереди

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages()

for message in response:
    print(message.content)
    queue.delete_message(message)

# Printed messages from the front of the queue:
# >> I'm using queues!
# >> This is my second message

Получение и обработка сообщений в пакетах

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages(messages_per_page=10)

for message_batch in response.by_page():
    for message in message_batch:
        print(message.content)
        queue.delete_message(message)

Асинхронное получение и обработка сообщений

from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages()

async for message in response:
    print(message.content)
    await queue.delete_message(message)

Дополнительная настройка

Необязательные ключевое слово аргументы, которые можно передать на уровне клиента и на уровне операции.

Конфигурация политики повторных попыток

Используйте следующие аргументы ключевое слово при создании экземпляра клиента для настройки политики повторных попыток:

  • retry_total (int): общее количество разрешенных повторных попыток. Имеет приоритет над другими счетчиками. retry_total=0 Передайте, если вы не хотите повторять запросы. Значение по умолчанию равно 10.
  • retry_connect (int): количество ошибок, связанных с подключением, для выполнения повторных попыток. Значение по умолчанию — 3.
  • retry_read (int): количество повторов при ошибках чтения. Значение по умолчанию — 3.
  • retry_status (int): количество повторных попыток при выполнении недопустимых кодов состояния. Значение по умолчанию — 3.
  • retry_to_secondary (логическое значение) — указывает, следует ли повторно выполнять запрос в дополнительный, если это возможно. Это должно быть включено только для учетных записей RA-GRS, и могут обрабатываться потенциально устаревшие данные. По умолчанию — False.

Другая конфигурация клиента или каждой операции

Другая необязательная конфигурация ключевое слово аргументы, которые можно указать на клиенте или для каждой операции.

Аргументы ключевое слово клиента:

  • connection_timeout (int): количество секунд, в течение которых клиент ожидает подключения к серверу. Значение по умолчанию — 20 секунд.
  • read_timeout (int): количество секунд, в течение которых клиент будет ожидать ответа от сервера между последовательными операциями чтения. Это время ожидания на уровне сокета, на который не влияет общий размер данных. Время ожидания чтения на стороне клиента будет автоматически повторяться. Значение по умолчанию — 60 секунд.
  • transport (Любой): предоставленный пользователем транспорт для отправки HTTP-запроса.

Аргументы ключевое слово для каждой операции:

  • raw_response_hook (вызываемый): данный обратный вызов использует ответ, возвращенный службой.
  • raw_request_hook (вызываемый): данный обратный вызов использует запрос перед отправкой в службу.
  • client_request_id (str): необязательный идентификатор запроса, указанный пользователем.
  • user_agent (str): добавляет пользовательское значение в заголовок user-agent для отправки вместе с запросом.
  • logging_enable (bool): включает ведение журнала на уровне DEBUG. Значение по умолчанию — False. Также можно передать на уровне клиента, чтобы включить его для всех запросов.
  • logging_body (логическое значение). Включает ведение журнала текста запроса и ответа. Значение по умолчанию — False. Также можно передать на уровне клиента, чтобы включить его для всех запросов.
  • headers (dict). Передайте пользовательские заголовки в виде пар "ключ— значение". Например, headers={'CustomValue': value}

Устранение неполадок

Общие сведения

Клиенты очереди хранилища вызывают исключения, определенные в Azure Core.

Этот список можно использовать для ссылки для перехвата создаваемых исключений. Чтобы получить конкретный код ошибки исключения, используйте error_code атрибут , т. е exception.error_code. .

Ведение журнала

Эта библиотека использует стандартную библиотеку ведения журнала для ведения журнала. Основные сведения о сеансах HTTP (URL-адреса, заголовки и т. д.) регистрируются на уровне INFO.

Подробное ведение журнала на уровне DEBUG, включая тексты запросов и ответов и нередактированные заголовки, можно включить на клиенте с помощью аргумента logging_enable :

import sys
import logging
from azure.storage.queue import QueueServiceClient

# Create a logger for the 'azure.storage.queue' SDK
logger = logging.getLogger('azure.storage.queue')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = QueueServiceClient.from_connection_string("your_connection_string", logging_enable=True)

Аналогичным образом с помощью параметра logging_enable можно включить подробное журналирование для отдельной операции (даже если этот режим не включен в клиенте):

service_client.get_service_stats(logging_enable=True)

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

Больше примеров кода

Начните работу с примерами очередей.

Несколько примеров пакета SDK для Python для очередей хранилища доступны в репозитории GitHub пакета SDK. В этих примерах приведен пример кода для дополнительных сценариев, часто встречающихся при работе с очередями хранилища:

  • queue_samples_hello_world.py (асинхронная версия) — примеры, приведенные в этой статье:

    • Создание клиента
    • Создание очереди
    • Отправка сообщений
    • Получение сообщений

  • queue_samples_authentication.py (асинхронная версия) — примеры проверки подлинности и создания клиента:

    • Из строка подключения
    • Из общего ключа доступа
    • Из маркера подписанного URL-адреса
    • Из Azure Active Directory

  • queue_samples_service.py (асинхронная версия) — примеры взаимодействия со службой очередей:

    • Получение и задание свойств службы
    • Перечисление очередей в учетной записи хранения
    • Создание и удаление очереди из службы
    • Получение QueueClient

  • queue_samples_message.py (асинхронная версия) — примеры работы с очередями и сообщениями:

    • Настройка политики доступа
    • Получение и настройка метаданных очереди
    • Отправка и получение сообщений
    • Удаление указанных сообщений и удаление всех сообщений
    • Обзор и обновления сообщений

Дополнительная документация

Более подробную документацию по хранилищу очередей Azure см. в документации по хранилищу очередей Azure на docs.microsoft.com.

Участие

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.