用于 Python 的 Azure 库的使用模式

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

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

设置本地开发环境

如果尚未设置，可以设置可以运行此代码的环境。 提供以下选择：

• 配置 Python 虚拟环境。 可以在本地或 Azure Cloud Shell 中创建虚拟环境，并在其中运行代码。 请务必激活虚拟环境以开始使用它。

• 使用 conda 环境。

• 在 Visual Studio Code 或 GitHub Codespaces 中使用开发容器。

库安装

pip

若要安装特定的库包，请使用 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 环境中安装特定的库包，请使用 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 中引入异步/await 关键字 (keyword)。 库的异步版本旨在与 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 库操作周围的块。

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

日志记录

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

代理配置

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

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

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

基于 azure.core 的库的参数

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

名称	类型	默认	说明
logging_enable	bool	False	启用日志记录。 有关详细信息，请参阅 Azure 库中的日志记录。
代理	dict	{}	代理服务器 URL。 有关详细信息，请参阅如何配置代理。
use_env_settings	bool	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 存储关键字 (keyword)参数，请参阅适用于 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 的简短调查