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

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

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

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

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

Необходимые компоненты

• Подписка Azure — создайте бесплатную учетную запись.
• Учетная запись хранения Azure — создайте такую учетную запись.
• Python 3.8+

Установка

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

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

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

1. В окне консоли (командная строка, 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 в каталоге очередей и кратких руководств .

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

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

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

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

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

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

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

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

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

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

Примеры кода

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

• Авторизация доступа и создание клиентского объекта
• Создание очереди
• Добавление сообщений в очередь
• Просмотр сообщений из очереди
• Обновление сообщений в очереди
• Получение длины очереди
• Получение сообщений из очереди
• Удаление сообщений из очереди
• Удаление очереди

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)

Сообщения очереди хранятся в виде текста. Если вы хотите хранить двоичные данные, настройте функции кодирования и декодирования 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. Этот метод позволяет изменить время видимости сообщения и его содержимое. Содержимое сообщение должно иметь формат строки в кодировке 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. Затем вы изучили процессы вставки, просмотра, получения и удаления сообщений. Наконец, вы узнали, как удалить очередь сообщений.

Руководства, примеры, краткие руководства и другую документацию можно найти здесь:

• Дополнительные примеры кода, использующие устаревшие пакеты SDK для Python версии 2, см. в примерах кода с помощью Python версии 2.
• Чтобы узнать больше, ознакомьтесь с библиотеками службы хранилища Azure для Python.
• Дополнительные сведения о служба хранилища примерах приложений очереди Azure см. в служба хранилища клиентской библиотеке очередей Azure для Python.