用于 Python 的 Azure 库的使用模式

项目
07/26/2024

用于 Python 的 Azure SDK 由众多独立的库组成，而这些库已在 Python SDK 包索引中列出。

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

设置本地开发环境

如果尚未设置，则可设置一个能在其中运行此代码的环境。提供以下选择：

使用 venv 或所选工具来配置 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 卸载库和安装特定版本，包括预览版。有关详细信息，请参阅如何安装用于 Python 的 Azure 库包。

若要在 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 环境中检索包的最新版本。

如需详细信息，包括如何删除包或安装特定版本的包，请参阅如何安装适用于 Python 的 Azure 库包。

异步操作

异步库

众多客户端和管理库均提供异步版本 (.aio)。 asyncio 库自 Python 3.4 起便已推出，而 Python 3.5 中则引入了 async/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。

以下代码演示如何为 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 和 WebSiteManagementClient.web_apps.begin_create_or_update）会返回长期操作的轮询器 LROPoller[<type>]；其中，<type> 特定于有问题的操作。

注意

你可能会注意到库中各方法名称存在差异，而这源于版本差异。非基于 azure.core 的旧库通常会使用类似 create_or_update 的名称。基于 azure.core 的库会向方法名称添加 begin_ 前缀，从而更好地表明它们为长期轮询操作。将旧代码迁移到基于 azure.core 的新库通常意味着将 begin_ 前缀添加到方法名称中，因为大多数方法签名保持不变。

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

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

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

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

Logging

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

代理配置

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

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

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

基于 azure.core 的库的参数

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

名称	类型	默认	说明
logging_enable	bool	False	启用日志记录。有关详细信息，请参阅 Azure 库中的日志记录。
代理	dict	{}	代理服务器 URL。有关详细信息，请参阅如何配置代理。
use_env_settings	布尔	True	如果为 True，表明允许为代理使用 `HTTP_PROXY` 和 `HTTPS_PROXY` 环境变量。如果为 False，则忽略环境变量。有关详细信息，请参阅如何配置代理。
connection_timeout	int	300	建立与 Azure REST API 终结点的连接时所产生的超时时间，以秒计算。
read_timeout	int	300	完成 Azure REST API 操作（即等待响应）时所产生的超时时间，以秒计算。
retry_total	int	10	允许的 REST API 调用重试次数。使用 `retry_total=0` 禁用重试操作。
retry_mode	enum	指数	以线性或指数方式应用重试计时。如果设置为“单次”，则按固定间隔时间进行重试。如果设置为“指数”，则每次重试距离上一次重试的时间是上一次间隔时间的两倍。

各个库没有义务支持这些参数中的任何一个，因此请务必查阅每个库的参考文档以获取确切的详细信息。此外，每个库可能会支持其他参数。例如，对于特定于 Blob 存储的关键字参数，请参阅 GitHub 自述文件中的 azure-storage-blob。

对象参数的内联 JSON 模式

Azure 库中的许多操作可用于将对象参数表示为离散对象或内联 JSON。

例如，你有一个 ResourceManagementClient 对象，而通过该对象可使用其 create_or_update 方法来创建资源组。此方法的第二个参数的类型为 ResourceGroup。

若要调用 create_or_update 方法，可直接使用其必要参数（在本例中为 location）来创建一个 ResourceGroup 的离散实例：

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

后续步骤

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

通过