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

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

Начало работы с клиентской библиотекой хранилища очередей Azure для Python. Хранилище очередей Azure — это служба для хранения большого количества сообщений для последующего извлечения и обработки. Выполните приведенные здесь действия, чтобы установить пакет и протестировать пример кода для выполнения базовых задач.

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

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

  • Создать очередь
  • Добавление сообщений в очередь
  • Просмотр сообщений в очереди
  • Обновление сообщения в очереди
  • Получите длину очереди
  • Получение сообщений из очереди
  • Удаление сообщений из очереди
  • Удаление очереди

Предпосылки

Настройка

В этом разделе описывается подготовка проекта для работы с клиентской библиотекой хранилища очередей Azure для Python.

Создание проекта

Создайте приложение Python с именем queues-quickstart.

  1. В окне консоли (например, cmd, PowerShell или Bash) создайте новый каталог для проекта.

    mkdir queues-quickstart

  2. Перейдите в только что созданный каталог queues-quickstart .

    cd queues-quickstart

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

В каталоге проекта установите клиентскую библиотеку для хранилища очередей Azure из пакета Python с помощью команды pip install. Пакет azure-identity необходим для бессерверных подключений к службам Azure.

pip install azure-storage-queue azure-identity

Настройте структуру приложения

  1. Откройте новый текстовый файл в редакторе кода.

  2. Добавление import инструкций

  3. Создайте структуру программы, включая простую обработку исключений.

    Вот этот код:

    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. Сохраните новый файл как queues-quickstart.py в каталоге queues-quickstart .

Аутентификация в Azure

Запросы приложений к большинству служб Azure должны быть авторизованы. Использование класса DefaultAzureCredential, предоставленного клиентской библиотекой Azure Identity, является рекомендуемым подходом для реализации подключений к службам Azure без пароля в вашем коде.

Вы также можете авторизовать запросы к службам Azure с помощью паролей, строк подключения или других учетных данных напрямую. Однако этот подход следует использовать с осторожностью. Разработчики должны быть старательными, чтобы никогда не предоставлять эти секреты в небезопасном расположении. Любой, кто получает доступ к паролю или секретному ключу, может пройти проверку подлинности. DefaultAzureCredential предлагает улучшенные преимущества управления и безопасности по сравнению с ключом учетной записи, чтобы разрешить проверку подлинности без пароля. Оба варианта показаны в следующем примере.

DefaultAzureCredential — это класс, предоставляемый клиентской библиотекой удостоверений Azure для Python. Чтобы подробнее узнать о DefaultAzureCredential, смотрите обзор DefaultAzureCredential. DefaultAzureCredential поддерживает несколько методов проверки подлинности и определяет, какой метод следует использовать во время выполнения. Этот подход позволяет приложению использовать различные методы проверки подлинности в разных средах (локальной среде и рабочей среде) без реализации кода для конкретной среды.

Например, приложение может пройти проверку подлинности с помощью учетных данных входа Visual Studio Code в локальной среде, а затем использовать управляемое удостоверение после развертывания в Azure. Для этого перехода изменения кода не требуются.

При разработке локально убедитесь, что учетная запись пользователя, которая обращается к данным очереди, имеет правильные разрешения. Вам потребуется Контрибьютор данных очереди хранилища для чтения и записи данных очереди. Чтобы назначить себе эту роль, вам потребуется назначить роль администратора доступа пользователей или другую роль, включающую действие Microsoft.Authorization/roleAssignments/write . Роли Azure RBAC можно назначить пользователю с помощью портала Azure, Azure CLI или Azure PowerShell. Дополнительные сведения о доступных областях назначения ролей можно узнать на странице обзора области.

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

В следующем примере роль участника данных очереди хранилища назначается учетной записи пользователя, которая предоставляет доступ для чтения и записи к данным очереди в учетной записи хранения.

Это важно

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

  1. На портале Azure найдите свою учетную запись хранения, воспользовавшись основной панелью поиска или областью навигации слева.

  2. На странице обзора учетной записи хранилища выберите Управление доступом (IAM) в меню слева.

  3. На странице Контроль доступа (IAM) откройте вкладку Назначения ролей.

  4. Выберите +Добавить из верхнего меню и добавьте назначение ролей из результирующего раскрывающегося меню.

Снимок экрана, на котором продемонстрировано назначение роли.

  1. Используйте поле поиска, чтобы отфильтровать результаты для отображения нужной роли. В этом примере найдите участника данных очереди хранилища и выберите соответствующий результат, а затем нажмите кнопку "Далее".

  2. В разделе Назначение доступа выберите Пользователь, группа или сервисный принципал, а затем нажмите + Выбрать участников.

  3. В диалоговом окне найдите имя пользователя Microsoft Entra (обычно ваш адрес электронной почты user@domain), а затем выберите Select в нижней части диалогового окна.

  4. Нажмите кнопку Проверить и назначить, чтобы перейти на последнюю страницу, а затем еще раз Проверить и назначить, чтобы завершить процесс.

Объектная модель

Азурное хранилище сообщений — это служба для хранения большого количества сообщений. Сообщение очереди может быть размером до 64 КБ. Очередь может содержать миллионы сообщений до общего ограничения емкости учетной записи хранения. Очереди обычно используются для создания очереди задач для асинхронной обработки. Хранилище очередей предлагает три типа ресурсов:

  • Учетная запись хранения. Все доступ к службе хранилища Azure осуществляется с помощью учетной записи хранения. Дополнительные сведения об учетных записях хранения см. в обзоре учетной записи хранения.
  • Очередь: очередь содержит набор сообщений. Все сообщения должны находиться в очереди. Обратите внимание: имя очереди должно быть написано строчными буквами. Дополнительные сведения об именовании очередей см. в разделе Именование очередей и метаданных.
  • Сообщение: сообщение в любом формате до 64 КБ. Сообщение может оставаться в очереди не более 7 дней. Для версии 2017-07-29 или более поздней версии максимальное время жизни может быть любым положительным числом или -1, указывая, что сообщение не истекает. Если этот параметр опущен, время жизни по умолчанию — семь дней.

На следующей схеме показана связь между этими ресурсами.

Схема архитектуры хранилища очередей

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

  • QueueServiceClient: QueueServiceClient позволяет управлять всеми очередями в вашей учетной записи хранения.
  • QueueClient: класс QueueClient позволяет управлять и манипулировать отдельной очередью и её сообщениями.
  • QueueMessage QueueMessage: класс представляет отдельные объекты, возвращаемые при вызове receive_messages на очереди.

Примеры кода

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

Авторизация доступа и создание клиентского объекта

Убедитесь, что вы выполнили аутентификацию с той же учетной записью Microsoft Entra, которую вы назначили роли. Вы можете пройти проверку подлинности с помощью Azure CLI, Visual Studio Code или Azure PowerShell.

Войдите в Azure с помощью Azure CLI, выполнив следующую команду:

az login

После проверки подлинности вы можете создать объект QueueClient и авторизовать его, используя DefaultAzureCredential, чтобы получить доступ к данным очереди в учетной записи хранения. DefaultAzureCredential автоматически обнаруживает и использует учетную запись, с которой вы вошли в систему на предыдущем шаге.

Чтобы авторизовать использование DefaultAzureCredential, убедитесь, что вы добавили пакет azure-identity , как описано в разделе "Установка пакетов". Кроме того, обязательно добавьте следующую инструкцию импорта в файл queues-quickstart.py :

from azure.identity import DefaultAzureCredential

Определите имя очереди и создайте экземпляр QueueClient класса, используя DefaultAzureCredential для авторизации. Этот клиентский объект используется для создания и взаимодействия с ресурсом очереди в учетной записи хранения.

Это важно

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

Добавьте следующий код в блок try и обязательно замените значение заполнителя <storage-account-name>.

    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)

Сообщения очереди хранятся в виде текста. Если вы хотите хранить двоичные данные, настройте функции кодирования и декодирования Base64 перед размещением сообщения в очереди.

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

Создать очередь

Для создания очереди в вашей аккаунте хранения вызовите метод QueueClient с помощью объекта create_queue.

Добавьте этот код в конец try блока:

    print("Creating queue: " + queue_name)

    # Create the queue
    queue_client.create_queue()

Добавление сообщений в очередь

Следующий фрагмент кода добавляет сообщения в очередь, вызывая метод send_message. Он также сохраняет возвращенный QueueMessage из третьего send_message вызова. saved_message используется для последующего обновления содержимого сообщения в программе.

Добавьте этот код в конец try блока:

    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")

Просмотр сообщений в очереди

Для просмотра сообщений в очереди вызовите метод peek_messages. Этот метод извлекает одно или несколько сообщений из передней части очереди, но не изменяет видимость сообщения.

Добавьте этот код в конец try блока:

    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)

Обновление сообщения в очереди

Обновите содержимое сообщения, вызвав update_message метод. Этот метод может изменить время видимости (timeout) и содержимое сообщения. Содержимое сообщения должно быть закодированной строкой UTF-8 размером до 64 КБ. Наряду с новым содержимым передайте значения из сообщения, сохраненного ранее в коде. Значения saved_message определяют, какое сообщение нужно обновить.

    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")

Получите длину очереди

Вы можете получить оценку количества сообщений в очереди.

Метод get_queue_properties возвращает свойства очереди, включая approximate_message_count.

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

Результат приблизительный, так как сообщения можно добавлять или удалять после ответа службы на запрос.

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

Вы можете скачать ранее добавленные сообщения, вызвав receive_messages метод.

Добавьте этот код в конец try блока:

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

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

При вызове receive_messages метода можно дополнительно указать значение max_messagesдля , которое является числом сообщений, извлекаемых из очереди. Значение по умолчанию — 1 сообщение, а максимальное — 32 сообщения. Можно также указать значение visibility_timeout, которое скрывает сообщения от других операций в течение периода ожидания. Значение по умолчанию — 30 секунд.

Удаление сообщений из очереди

Удалите сообщения из очереди после их получения и обработки. В этом случае обработка лишь заключается в отображении сообщения на консоли.

Приложение приостанавливает работу для ввода данных пользователем, вызывая input перед тем, как обработает и удалит сообщения. Убедитесь, что ресурсы были созданы правильно на портале Azure перед их удалением. Все сообщения, которые явно не удалены, в конечном итоге становятся видимыми в очереди еще раз, чтобы еще один шанс обработать их.

Добавьте этот код в конец try блока:

    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)

Удаление очереди

Следующий код очищает ресурсы, созданные приложением, удалив очередь с помощью delete_queue метода.

Добавьте этот код в конец try блока и сохраните файл:

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

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

    print("Done")

Запустите код

Это приложение создает и добавляет три сообщения в очередь Azure. Код перечисляет сообщения в очереди, а затем извлекает и удаляет их, прежде чем окончательно удалить очередь.

В окне консоли перейдите в каталог, содержащий файл queues-quickstart.py , а затем выполните следующую python команду для запуска приложения.

python queues-quickstart.py

Выходные данные приложения похожи на следующий пример:

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

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

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

Дальнейшие шаги

Из этого краткого руководства вы узнали, как создать очередь и добавить в нее сообщения с помощью кода Python. Затем вы узнали, как просмотреть, извлечь и удалить сообщения. Наконец, вы узнали, как удалить очередь сообщений.

Для получения доступа к руководствам, примерам, кратким руководствам и другой документации посетите:

Azure for Python developers (Azure для разработчиков Python).

  • Last updated on