Библиотеки Azure для схем использования Python

Статья
10/18/2023

Пакет SDK Azure для Python состоит из множества независимых библиотек, которые перечислены в индексе пакета пакета SDK для Python.

У всех библиотек есть определенные общие характеристики и схемы использования, такие как установка и использование встроенного кода JSON для аргументов объекта.

Узнайте, как настроить локальную среду разработки

Если вы еще не сделали этого, можно настроить среду, в которой можно запустить этот код. Ниже приведено несколько вариантов:

Настройка виртуальной среды Python. Вы можете создать виртуальную среду локально или в Azure Cloud Shell и запустить код там. Обязательно активируйте виртуальную среду, чтобы начать использовать ее.
Используйте среду conda.
Используйте контейнер разработки в Visual Studio Code или GitHub Codespaces.

Чтобы установить нужный пакет библиотеки, используйте pip install:

# Install the management library for Azure Storage
pip install azure-mgmt-storage

# Install the client library for Azure Blob Storage
pip install azure-storage-blob

pip install получает последнюю версию библиотеки в текущей среде Python.

Можно также использовать команду pip, чтобы удалить библиотеку или установить определенную версию, включая предварительные версии. Дополнительные сведения см. в статье Описание установки пакетов библиотеки Azure для Python.

Чтобы установить конкретный пакет библиотеки в среде Conda, используйте conda install:

# Install the Azure management library package
conda install azure-mgmt

# Install the client library for Azure Storage
conda install azure-storage

conda install получает последнюю версию пакета в текущей среде Conda.

Дополнительные сведения, включая сведения об удалении пакетов или установке конкретных версий, см. в статье Установка пакетов библиотеки Azure для Python.

Асинхронные операции

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

Многие клиентские и административные библиотеки предоставляют асинхронные версии (.aio). Библиотека asyncio доступна с версии Python 3.4, а асинхронные и ожидаемые ключевое слово появились в Python 3.5. Асинхронные версии библиотек предназначены для использования с Python 3.5 и более поздних версий.

Примерами библиотек пакета SDK для Python Azure с асинхронными версиями являются azure.storage.blob.aio, azure.servicebus.aio, azure.mgmt.keyvault.aio и azure.mgmt.compute.aio.

Эти библиотеки нуждаются в асинхронном транспорте, например aiohttp для работы. Библиотека azure-core предоставляет асинхронный транспорт, AioHttpTransportкоторый используется асинхронными библиотеками.

В следующем коде показано, как создать клиент для асинхронной версии библиотеки Хранилище BLOB-объектов Azure:

credential = DefaultAzureCredential()

async def run():

    async with BlobClient(
        storage_url,
        container_name="blob-container-01",
        blob_name=f"sample-blob-{str(uuid.uuid4())[0:5]}.txt",
        credential=credential,
    ) as blob_client:

        # Open a local file and upload its contents to Blob Storage
        with open("./sample-source.txt", "rb") as data:
            await blob_client.upload_blob(data)
            print(f"Uploaded sample-source.txt to {blob_client.url}")

        # Close credential
        await credential.close()

asyncio.run(run())

Полный пример находится на сайте GitHub use_blob_auth_async.py. Синхронную версию этого кода см. в примере : отправка большого двоичного объекта.

Длительные операции

Некоторые операции управления, которые вызываются (например ComputeManagementClient.virtual_machines.begin_create_or_update , и WebSiteManagementClient.web_apps.begin_create_or_update возвращают опрашиватель для длительных операций, LROPoller[<type>]где <type> зависит от этой операции.

Примечание.

Вы можете заметить различия в именах методов в библиотеке, что связано с различиями версий. Старые библиотеки, которые не основаны на azure.core, обычно используют такие create_or_updateимена. Библиотеки на основе azure.core добавляют begin_ префикс в имена методов, чтобы лучше указать, что они являются длительными операциями опроса. Миграция старого кода в более новую библиотеку на базе azure.core обычно предусматривает добавление префикса begin_ в имена методов, так как большинство сигнатур методов остаются неизменными.

Тип LROPoller возвращаемого значения означает, что операция является асинхронной. Соответственно, вам нужно вызвать метод result этого модуля опроса, чтобы дождаться завершения операции и получить результат.

Следующий код, взятый из примера: создание и развертывание веб-приложения, показывает пример использования опрашителя для ожидания результата:

poller = app_service_client.web_apps.begin_create_or_update(RESOURCE_GROUP_NAME,
    WEB_APP_NAME,
    {
        "location": LOCATION,
        "server_farm_id": plan_result.id,
        "site_config": {
            "linux_fx_version": "python|3.8"
        }
    }
)

web_app_result = poller.result()

В этом случае возвращаемое значение begin_create_or_update имеет тип AzureOperationPoller[Site], что означает, что возвращаемое значение poller.result() является объектом Site.

Исключения

Как правило, библиотеки Azure генерируют исключения в тех случаях, когда операции не выполняются должным образом, в том числе при неудачных HTTP-запросах к REST API Azure. Для кода приложения можно использовать try...except блоки вокруг операций библиотеки.

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

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

В последних версиях библиотек Azure для создания выходных данных журнала используется стандартная библиотека Python logging. Вы можете задать уровень ведения журнала для отдельных библиотек, групп библиотек или всех библиотек сразу. После регистрации обработчика потока ведения журнала вы сможете включить ведение журнала для конкретного объекта клиента или конкретной операции. См. дополнительные сведения в статье Ведение журнала в библиотеках Azure.

настройки прокси-сервера;

Чтобы указать прокси-сервер, можно использовать переменные среды или необязательные аргументы. См. дополнительные сведения в статье Как конфигурировать прокси-серверы.

Необязательные аргументы для объектов и методов клиента

В справочной документации по библиотеке аргумент **kwargs или **operation_config часто встречается в сигнатурах конструктора объекта клиента или конкретного метода операции. Эти заполнители указывают на то, что объект или метод, указанный в вопросе, может поддерживать другие именованные аргументы. Как правило, справочная документация описывает конкретные аргументы, которые можно использовать. Есть также несколько общих аргументов, которые поддерживаются во многих случаях, как описано в следующих разделах.

Аргументы для библиотек на основе azure.core

Эти аргументы применяются к библиотекам, перечисленным на странице Python - New Libraries (Python — Новые библиотеки). Например, ниже приведено подмножество аргументов ключевое слово для azure-core. Полный список см. в разделе GitHub README для azure-core.

Имя.	Тип	По умолчанию.	Description
logging_enable	bool	False	Включает ведение журнала. См. дополнительные сведения в статье Ведение журнала в библиотеках Azure.
прокси-серверы;	dict	{}	URL-адреса прокси-серверов. См. дополнительные сведения в статье Как конфигурировать прокси-серверы.
use_env_settings	bool	Истина	Если указано значение True, разрешено использовать переменные среды `HTTP_PROXY` и `HTTPS_PROXY` для прокси-серверов. Если указано значение False, переменные среды игнорируются. См. дополнительные сведения в статье Как конфигурировать прокси-серверы.
connection_timeout	INT	300	Время ожидания в секундах для установки подключения к конечным точкам REST API Azure.
read_timeout	INT	300	Время ожидания в секундах для завершения операции REST API Azure (т. е. ожидания ответа).
retry_total	INT	10	Число допустимых повторных попыток при вызовах REST API. Укажите `retry_total=0`, чтобы отключить повторные попытки.
retry_mode	перечисление	exponential	Выбор линейной или экспоненциальной задержки перед выполнением повторных попыток. Если указано значение single, повторы выполняются через регулярные интервалы. Если указано значение exponential, каждая следующая повторная попытка выполняется с удвоенным временем ожидания.

Отдельные библиотеки не обязаны поддерживать какие-либо из этих аргументов, поэтому всегда обратитесь к справочной документации для каждой библиотеки для получения точных сведений. Кроме того, каждая библиотека может поддерживать другие аргументы. Например, для конкретных аргументов хранилища BLOB-объектов ключевое слово см. GitHub README для azure-storage-blob.

Встроенная структура данных JSON для аргументов объектов

Библиотеки Azure позволяют выражать аргументы объектов в виде отдельных объектов или как встроенную структуру данных JSON.

Например, предположим, что у вас есть ResourceManagementClient объект, с помощью которого создается группа ресурсов с его create_or_update методом. Второй аргумент для этого метода имеет тип ResourceGroup.

Чтобы вызвать create_or_update метод, можно создать дискретный экземпляр ResourceGroup непосредственно с необходимыми аргументами (location в данном случае):

# Provision the resource group.
rg_result = resource_client.resource_groups.create_or_update(
    "PythonSDKExample-rg",
    ResourceGroup(location="centralus")
)

Второй способ — это передать эти параметры в виде встроенной структуры данных JSON:

# Provision the resource group.
rg_result = resource_client.resource_groups.create_or_update(
    "PythonAzureExample-rg", {"location": "centralus"}
)

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

Объекты также могут иметь вложенные аргументы объектов. В этом случае можно также использовать встроенную структуру данных JSON.

Предположим, что у вас есть экземпляр объекта KeyVaultManagementClient и вы вызываете его метод create_or_update. В этом случае третий аргумент имеет тип VaultCreateOrUpdateParameters, который содержит аргумент типа VaultProperties. В свою очередь VaultProperties содержит аргументы объекта типа Sku и list[AccessPolicyEntry]. Sku содержит объект SkuName, а каждый AccessPolicyEntry содержит объект Permissions.

Для вызова begin_create_or_update с внедренными объектами используется следующий код (предполагаетсяtenant_idobject_id, что он LOCATION уже определен). Кроме того, необходимые объекты можно создать перед вызовом функции.

# Provision a Key Vault using inline parameters
poller = keyvault_client.vaults.begin_create_or_update(
    RESOURCE_GROUP_NAME,
    KEY_VAULT_NAME_A,
    VaultCreateOrUpdateParameters(
        location = LOCATION,
        properties = VaultProperties(
            tenant_id = tenant_id,
            sku = Sku(
                name="standard",
                family="A"
            ),            
            access_policies = [
                AccessPolicyEntry(
                    tenant_id = tenant_id,
                    object_id = object_id,
                    permissions = Permissions(
                        keys = ['all'],
                        secrets = ['all']
                    )
                )
            ]
        )
    )
)

key_vault1 = poller.result()

Этот же вызов с помощью встроенной структуры данных JSON выглядит следующим образом:

# Provision a Key Vault using inline JSON
poller = keyvault_client.vaults.begin_create_or_update(
    RESOURCE_GROUP_NAME,
    KEY_VAULT_NAME_B,
    {
        'location': LOCATION,
        'properties': {
            'sku': {
                'name': 'standard',
                'family': 'A'
            },
            'tenant_id': tenant_id,
            'access_policies': [{
                'tenant_id': tenant_id,
                'object_id': object_id,                
                'permissions': {
                    'keys': ['all'],
                    'secrets': ['all']
                }
            }]
        }
    }
)

key_vault2 = poller.result()

Так как оба способа дают одинаковый результат, вы можете выбрать любой или даже совместить их. (Полный код для этих примеров можно найти на GitHub.)

Если json не сформирован должным образом, обычно возникает ошибка "DeserializationError: не удается десериализировать для объекта: type, AttributeError: объект str не имеет атрибута get". Как правило, причина этой ошибки заключается в том, что вы предоставляете одну строку для свойства, тогда как библиотека ожидает вложенный объект JSON. Например, использование 'sku': 'standard' в предыдущем примере приводит к возникновению этой ошибки, так как параметр sku является объектом Sku, который ожидает встроенный объект JSON, в нашем случае {'name': 'standard'}, соответствующий соответствует ожидаемому типу SkuName.

Следующие шаги

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