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

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

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

Настройка локальной среды разработки

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

• Настройте виртуальную среду Python с помощью venv или выбранного средства. Чтобы начать использовать виртуальную среду, обязательно активируйте ее. Сведения об установке Python см. в разделе "Установка Python".

  • Баш
  • PowerShell

  #!/bin/bash
  # Create a virtual environment
  python -m venv .venv
  # Activate the virtual environment
  source .venv/Scripts/activate # only required for Windows (Git Bash)
  

• Используйте конда-среду. Сведения об установке Conda см. в разделе "Установка Miniconda".

• Используйте контейнер разработки в Visual Studio Code или GitHub Codespaces.

Установка библиотеки

Выберите метод установки, соответствующий средству управления средой Python, pip или conda.

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

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

REM Install the azure identity library for Azure authentication
pip install azure-identity

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

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

REM Install the azure identity library for Azure authentication
pip install azure-identity

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

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

Многие клиентские и административные библиотеки предоставляют асинхронные версии (.aio). Библиотека asyncio доступна с версии Python 3.4, а ключевые слова async/await появились в 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который используется асинхронными библиотеками, поэтому не требуется устанавливать aiohttp отдельно.

В следующем коде показано, как создать файл Python, который демонстрирует, как создать клиент для асинхронной версии библиотеки хранилища 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 и WebAppsClient.web_apps.begin_create_or_update), возвращают опрашиватель для длительных операций, LROPoller[<type>], где <type> зависит от конкретной операции.

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

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

# Step 3: With the plan in place, provision the web app itself, which is the process that can host
# whatever code we want to deploy to it.

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 используют стандартную logging библиотеку Python для создания выходных данных журнала. Вы можете задать уровень ведения журнала для отдельных библиотек, групп библиотек или всех библиотек. После регистрации обработчика потока ведения журнала можно включить ведение журнала для определенного клиентского объекта или определенной операции. Дополнительные сведения см. в разделе "Ведение логов в библиотеках Azure".

Конфигурация прокси-сервера

Чтобы указать прокси-сервер, можно использовать переменные среды или необязательные аргументы. Дополнительные сведения см. в разделе "Настройка прокси-серверов".

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

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

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

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

Отдельные библиотеки не обязаны поддерживать какие-либо из этих аргументов, поэтому всегда обратитесь к справочной документации для каждой библиотеки для получения точных сведений. Кроме того, каждая библиотека может поддерживать другие аргументы. Например, для аргументов, специфичных для ключевых слов хранения BLOB, см. README на GitHub для 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_id, object_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, ознакомьтесь со следующими автономными примерами для изучения конкретных сценариев управления и клиентской библиотеки. Эти примеры можно попробовать в любом порядке, так как они не последовательны и не взаимозависимы.

• Пример. Создание группы ресурсов

• Пример. Использование службы хранилища Azure

• Пример. Создание веб-приложения и развертывание кода

• Пример. Создание и запрос базы данных

• Пример. Создание виртуальной машины

• Использование управляемых дисков Azure с виртуальными машинами

• Краткое исследование о пакете SDK Azure для Python