用于 Python 的 Azure 库使用模式

用于 Python 的 Azure SDK 由许多独立库组成，这些库列在 Python SDK 包索引上。

所有库共享某些常见特征和使用模式，例如安装和对对象参数使用内联 JSON。

设置本地开发环境

如果尚未设置，可以设置可以运行此代码的环境。 下面是一些选项：

• 使用 venv 或所选工具配置 Python 虚拟环境。 若要开始使用虚拟环境，请务必激活它。 若要安装 python，请参阅 “安装 Python”。

  • Bash
  • 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 环境。 若要安装 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 起已推出，Python 3.5 中引入了异步/await 关键字。 库的异步版本旨在与 Python 3.5 及更高版本一起使用。

具有异步版本的 Azure Python SDK 库的示例包括： azure.storage.blob.aio、 azure.servicebus.aio、 azure.mgmt.keyvault.aio 和 azure.mgmt.compute.aio。

这些库需要一个异步传输，例如aiohttp才能正常工作。 该azure-core库提供了一个异步传输AioHttpTransport，它被异步库使用，因此你可能不需要单独安装aiohttp。

以下代码演示如何创建 Python 文件，该文件演示如何为 Azure Blob 存储库的异步版本创建客户端：

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。 有关此代码的同步版本，请参阅示例：上传 blob。

长时间运行的操作

调用的一些管理操作（如 ComputeManagementClient.virtual_machines.begin_create_or_update 和 WebAppsClient.web_apps.begin_create_or_update）返回运行时间较长的操作的轮询器 LROPoller[<type>]，其中 <type> 特定于相关操作。

返回类型LROPoller表示该操作是异步的。 相应地，必须调用该轮询器的 result 方法，以等待操作完成并获取结果。

以下代码取自 示例：创建和部署 Web 应用，演示了使用轮询器等待结果的示例：

# 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 库会引发异常，包括 Azure REST API 的 HTTP 请求失败。 对于应用代码，可以在库操作周围使用 try...except 块。

有关可能引发的异常类型的详细信息，请参阅相关操作的文档。

伐木业

最新的 Azure 库使用 Python 标准 logging 库生成日志输出。 可以为单个库、库组或所有库设置日志记录级别。 注册日志记录流处理程序后，可以为特定客户端对象或特定作启用日志记录。 有关详细信息，请参阅 Azure 库中的日志记录。

代理配置

若要指定代理，可以使用环境变量或可选参数。 有关详细信息，请参阅 如何配置代理。

客户端对象和方法的可选参数

在库参考文档中，通常会在客户端对象构造函数或特定操作方法的签名中看到 **kwargs 或 **operation_config 参数。 这些占位符表明所讨论的对象或方法可能支持其他命名参数。 通常，参考文档指示可以使用的特定参数。 此外，通常还支持一些常规参数，后面部分中对此进行了介绍。

基于 azure.core 的库的参数

这些参数适用于 Python 上列出的库 - 新库。 例如，下面是关键字 azure-core参数的子集。 有关完整列表，请参阅 Azure 核心版的 GitHub 自述文件。

各个库不强制支持其中任何参数，因此请始终查阅每个库的参考文档以获取确切的详细信息。 此外，每个库可能支持其他参数。 例如，有关 Blob 存储特定关键字参数，请参阅 适用于 azure-storage-blob 的 GitHub 自述文件。

对象参数的内联 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 参数是一个需要内联对象 JSON 的 Sku 对象，在本例中为 {'name': 'standard'}，它映射到所需的 SkuName 类型。

后续步骤

了解使用适用于 Python 的 Azure 库的常见模式后，请参阅以下独立示例来探索特定的管理和客户端库方案。 可以按任何顺序尝试这些示例，因为它们不是按顺序或相互依赖的。

• 示例：创建资源组

• 示例：使用 Azure 存储

• 示例：创建 Web 应用并部署代码

• 示例：创建和查询数据库

• 示例：创建虚拟机

• 将 Azure 托管磁盘用于虚拟机

• 进行一项有关 Azure SDK for Python 的简短调查