示例：使用适用于 Python 的 Azure 库来访问 Azure 存储

项目
10/07/2024

本文介绍如何在 Python 应用程序代码中使用 Azure 客户端库将文件上传到 Azure Blob 存储容器。本文假定已创建示例：创建 Azure 存储中所示的资源。

除非另行说明，否则本文中的所有资源在 Linux/macOS bash 和 Windows 命令行界面上的工作方式相同。

1. 设置本地开发环境

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

使用 venv 或所选工具来配置 Python 虚拟环境。可在本地或 Azure Cloud Shell 中创建虚拟环境，然后在其中运行代码。请务必激活此虚拟环境以开始使用。
使用 Conda 环境。
在 Visual Studio Code 或 GitHub Codespaces 中使用开发容器。

2. 安装库包

在 requirements.txt 文件中，添加所需的客户端库包行，然后保存文件。

azure-storage-blob
azure-identity

然后，在终端或命令提示符中安装规定的内容。

pip install -r requirements.txt

3. 创建要上传的文件

创建名为 sample-source.txt 的源文件。此文件名为该代码所需的内容。

Hello there, Azure Storage. I'm a friendly file ready to be stored in a blob.

4. 从应用代码使用 Blob 存储

本部分演示了访问在示例：创建 Azure 存储中创建的 blob 容器中数据的两种方法。要访问 blob 容器中的数据，应用必须能够与 Azure 进行身份验证，并获得授权才能访问容器中的数据。本部分将介绍这两种方法：

无密码（推荐）方法通过使用 DefaultAzureCredential 来对应用进行身份验证。 DefaultAzureCredential 是一种链式凭据，可以使用一系列不同的凭据（包括开发人员工具凭据、应用程序服务主体和托管身份）对应用（或用户）进行身份验证。
连接字符串方法使用连接字符串来直接访问存储帐户。

出于以下原因，我们建议尽可能使用无密码方法：

连接字符串将验证连接代理与存储帐户的关系，而不是与该帐户中的单个资源的关系。因此，连接字符串授予的授权范围可能会超出所需的范围。通过 DefaultAzureCredential，可以使用 Azure RBAC 向应用运行身份授予更细粒度、权限最小的存储资源权限。
由于连接字符串包含纯文本形式的访问信息，因此如果未正确构造或保护该连接字符串，则可能存在潜在漏洞。如果公开此类连接字符串，则可使用它来访问存储帐户下的各种资源。
连接字符串通常存储在环境变量中，因此，如果攻击者获取了环境访问权限，就很容易对其进行破坏。 DefaultAzureCredential 支持的许多凭据类型都不需要在环境中存储机密。

无密码（推荐）
连接字符串

DefaultAzureCredential 是一个固定的预配置凭据链。它旨在支持许多环境，以及最常见的身份验证流和开发人员工具。 DefaultAzureCredential 的实例会根据其运行环境、某些已知的环境变量的值以及传入其构造器的参数（可选）来决定尝试为哪些凭据类型获取令牌。

在以下步骤中，将配置应用程序服务主体作为应用程序身份。应用程序服务主体既适用于本地开发，也适用于内部托管的应用程序。要配置 DefaultAzureCredential 以使用应用程序服务主体，则需要设置以下环境变量：AZURE_CLIENT_ID，AZURE_TENANT_ID 和 AZURE_CLIENT_SECRET。

请注意，客户机密已配置。这对于应用程序服务主体来说是必要的，但根据具体情况，也可以将 DefaultAzureCredential 配置为使用无需在环境变量中设置机密或密码的凭据。

例如，在本地开发中，如果 DefaultAzureCredential 无法使用配置的环境变量来获取令牌，它就会尝试使用（已经）登录到 Azure CLI 等开发工具的用户来获取令牌；对于托管在 Azure 中的应用，DefaultAzureCredential 可以配置为使用托管身份。在所有情况下，应用中的代码都保持不变，只是配置和/或运行环境发生了变化。

使用以下代码创建一个名为“use_blob_auth py”的文件。注释对步骤进行了说明。

import os
import uuid

from azure.identity import DefaultAzureCredential

# Import the client object from the SDK library
from azure.storage.blob import BlobClient

credential = DefaultAzureCredential()

# Retrieve the storage blob service URL, which is of the form
# https://<your-storage-account-name>.blob.core.windows.net/
storage_url = os.environ["AZURE_STORAGE_BLOB_URL"]

# Create the client object using the storage URL and the credential
blob_client = BlobClient(
    storage_url,
    container_name="blob-container-01",
    blob_name=f"sample-blob-{str(uuid.uuid4())[0:5]}.txt",
    credential=credential,
)

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

参考链接：

创建名为 AZURE_STORAGE_BLOB_URL 的环境变量：
- cmd
- bash
```
set AZURE_STORAGE_BLOB_URL=https://pythonazurestorage12345.blob.core.windows.net
```
```
AZURE_STORAGE_BLOB_URL=https://pythonazurestorage12345.blob.core.windows.net
```
将“pythonazurestorage12345”替换为存储帐户的名称。

AZURE_STORAGE_BLOB_URL 环境变量仅由此示例使用。 Azure 库不会使用它。
使用 az ad sp create-for-rbac 命令为应用创建新的服务主体。该命令会同时为应用创建应用注册。为服务主体指定所选名称。
```
az ad sp create-for-rbac --name <service-principal-name>
```
此命令的输出如下所示。记下这些值或使此窗口保持打开状态，因为在下一步中需使用这些值，且无法再次查看密码（客户端密码）值。但是，如果需要，可稍后添加新密码，而不会使服务主体或现有密码失效。
```
{
  "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "displayName": "<service-principal-name>",
  "password": "Aa1Bb~2Cc3.-Dd4Ee5Ff6Gg7Hh8Ii9_Jj0Kk1Ll2",
  "tenant": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
}
```
可以在 Azure Cloud Shell 中或装有 Azure CLI 的工作站上运行 Azure CLI 命令。

为应用程序服务主体创建环境变量：

使用上一命令输出中的值创建以下环境变量。这些变量会指示 DefaultAzureCredential 使用应用程序服务主体。

AZURE_CLIENT_ID → 应用 ID 值。
AZURE_TENANT_ID → 租户 ID 值。
AZURE_CLIENT_SECRET → 为应用生成的密码/凭据。

cmd
bash

set AZURE_CLIENT_ID=00001111-aaaa-2222-bbbb-3333cccc4444
set AZURE_TENANT_ID=aaaabbbb-0000-cccc-1111-dddd2222eeee
set AZURE_CLIENT_SECRET=Aa1Bb~2Cc3.-Dd4Ee5Ff6Gg7Hh8Ii9_Jj0Kk1Ll2

AZURE_CLIENT_ID=00001111-aaaa-2222-bbbb-3333cccc4444
AZURE_TENANT_ID=aaaabbbb-0000-cccc-1111-dddd2222eeee
AZURE_CLIENT_SECRET=Aa1Bb~2Cc3.-Dd4Ee5Ff6Gg7Hh8Ii9_Jj0Kk1Ll2

尝试运行代码（有意失败）：
```
python use_blob_auth.py
```
请注意错误“此请求无权使用此权限执行该操作”。由于正在使用的本地服务主体尚无权访问 Blob 容器，因此会出现此错误。
使用 az role assignment create Azure CLI 命令在 Blob 容器上向服务主体人授予存储 Blob 数据参与者权限：
```
az role assignment create --assignee <AZURE_CLIENT_ID> \
    --role "Storage Blob Data Contributor" \
    --scope "/subscriptions/<AZURE_SUBSCRIPTION_ID>/resourceGroups/PythonAzureExample-Storage-rg/providers/Microsoft.Storage/storageAccounts/pythonazurestorage12345/blobServices/default/containers/blob-container-01"
```
--assignee 参数标识了服务主体。将 <AZURE_CLIENT_ID> 占位符替换为服务主体的应用 ID。

--scope 参数标识此角色分配适用的位置。在此示例中，向名为“blob-container-01”的容器的服务主体授予“存储 Blob 数据参与者”角色。
- 将 PythonAzureExample-Storage-rg 和 pythonazurestorage12345 分别替换为包含存储帐户的资源组以及存储帐户的实际名称。此外，如有必要，请调整 Blob 容器的名称。如果使用错误名称，会发现错误“无法对嵌套资源执行请求的操作。找不到父资源‘pythonazurestorage12345’”。
- 将 <AZURE_SUBSCRIPTION_ID> 占位符替换为 Azure 订阅 ID。（可运行 az account show 命令，然后从输出中的 id 属性获取订阅 ID。）
提示

如果使用 bash shell 时角色分配命令返回错误“找不到连接适配器”，则请尝试设置 export MSYS_NO_PATHCONV=1 以避免路径转换。有关详细信息，请参阅此问题。
花一两分钟时间等待权限传播，然后再次运行该代码，验证它现在是否正常工作。如果再次看到权限错误，请等待更长的时间，然后重试代码。

有关角色分配的详细信息，请参阅如何使用 Azure CLI 分配角色权限。

重要

在前面的步骤中，你的应用是在应用程序服务主体下运行的。应用程序服务主体在配置中需要一个客户机密。但是，可以使用相同的代码在不同的凭据类型下运行应用程序，而无需在环境中显式配置密码或机密。例如，在开发过程中，DefaultAzureCredential 可以使用开发人员工具凭据，如用于通过 Azure CLI 登录的凭据；或者，对于在 Azure 中托管的应用，可以使用托管身份。要了解更多信息，请参阅使用 Azure SDK for Python 向 Azure 服务验证 Python 应用身份。

连接字符串包括存储帐户访问密钥，并使用它来授权请求。请始终小心，不要在不安全的位置公开密钥。

创建包含以下代码的名为“use_blob_conn_string.py”的 Python 文件。注释对步骤进行了说明。

import os
import uuid

# Import the client object from the SDK library
from azure.storage.blob import BlobClient

# Retrieve the connection string from an environment variable. Note that a
# connection string grants all permissions to the caller, making it less
# secure than obtaining a BlobClient object using credentials.
conn_string = os.environ["AZURE_STORAGE_CONNECTION_STRING"]

# Create the client object for the resource identified by the connection
# string, indicating also the blob container and the name of the specific
# blob we want.
blob_client = BlobClient.from_connection_string(
    conn_string,
    container_name="blob-container-01",
    blob_name=f"sample-blob-{str(uuid.uuid4())[0:5]}.txt",
)

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

创建一个名为 AZURE_STORAGE_CONNECTION_STRING 的环境变量，其值是存储帐户的完整连接字符串。（此环境变量也被各种 Azure CLI 注释使用。）可通过运行 az storage account show-connection-string 命令来获取存储帐户的连接字符串。
```
az storage account show-connection-string --resource-group PythonAzureExample-Storage-rg --name pythonazurestorage12345
```
将 PythonAzureExample-Storage-rg 和 pythonazurestorage12345 分别替换为包含存储帐户的资源组以及存储帐户的实际名称。

设置此环境变量时，请使用输出中 connectionString 属性的整个值（包括引号）。
运行代码：
```
python use_blob_conn_string.py
```

同样，虽然此方法很简单，但连接字符串会授权存储帐户中的所有操作。对于生产代码，最好使用上一节中所述的特定权限。

重要

应谨慎使用帐户访问密钥。如果帐户访问密钥丢失或意外放置在不安全的位置，服务可能会变得易受攻击。具有访问密钥的任何人都可以授权针对存储帐户的请求，并且实际上有权访问所有数据。 DefaultAzureCredential 提供增强的安全功能和优势，是管理 Azure 服务授权的推荐方法。

5：验证 Blob 创建

运行任一方法的代码后，转到 Azure 门户，导航到 Blob 容器以验证是否存在其内容与 sample-source.txt 文件相同且名为 ssample-blob-{random}.txt 的新 Blob：

blob 容器的 Azure 门户页面，显示已上传的文件

如果已创建名为 AZURE_STORAGE_CONNECTION_STRING 的环境变量，则还可使用 Azure CLI 并通过 az storage blob list 命令来验证该 Blob 是否存在：

az storage blob list --container-name blob-container-01

如果按照说明使用了无密码身份验证，则可以在前面的命令中添加 --connection-string 参数，并在其中输入存储帐户的连接字符串。要获取连接字符串，请使用 az storage account show-connection-string 命令。

az storage account show-connection-string --resource-group PythonAzureExample-Storage-rg --name pythonazurestorage12345 --output tsv

使用整个连接字符串作为 --connection-string 参数的值。

注意

如果 Azure 用户帐户在容器上具有“存储 Blob 数据参与者”角色，则可以使用以下命令列出容器中的 Blob：

az storage blob list --container-name blob-container-01 --account-name pythonazurestorage12345 --auth-mode login

6.清理资源

如果无需保留在此示例中使用的资源组和存储资源，则请运行 az group delete 命令。资源组不会在订阅中产生任何持续费用，但资源组中的资源（如存储帐户）则可能会继续产生费用。最好清理未主动使用的所有组。 --no-wait 参数允许命令立即返回，而不是等到操作完成再返回。

az group delete -n PythonAzureExample-Storage-rg  --no-wait

你还可以使用 ResourceManagementClient.resource_groups.begin_delete 方法从代码中删除资源组。示例：创建资源组中的代码演示了相关用法。

如果按照说明使用了无密码身份验证，则最好删除已创建的应用程序服务主体。可使用 az ad app delete 命令。将 <AZURE_CLIENT_ID> 占位符替换为服务主体的应用 ID。

az ad app delete --id <AZURE_CLIENT_ID>

通过