你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 Python 的 Azure 存储 Blob 客户端库 - 版本 12.19.0

项目
11/09/2023

Azure Blob 存储是 Microsoft 提供的适用于云的对象存储解决方案。 Blob 存储最适合存储巨量的非结构化数据，例如文本或二进制数据。

Blob 存储最适合用于：

直接向浏览器提供图像或文档
存储文件以供分布式访问
对视频和音频进行流式处理
存储用于备份和还原、灾难恢复及存档的数据
存储数据以供本地或 Azure 托管服务执行分析

入门

先决条件

使用此包需要 Python 3.7 或更高版本。有关更多详细信息，请阅读有关 Azure SDK for Python 版本支持策略的页面。
必须具有 Azure 订阅和 Azure 存储帐户才能使用此包。

安装包

使用 pip 安装适用于 Python 的 Azure 存储 Blob 客户端库：

pip install azure-storage-blob

创建存储帐户

如果要创建新的存储帐户，可以使用 Azure 门户、Azure PowerShell或 Azure CLI：

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

创建客户端

使用适用于 Python 的 Azure 存储 Blob 客户端库，可以与三种类型的资源进行交互：存储帐户本身、Blob 存储容器和 Blob。与这些资源的交互从客户端的实例开始。若要创建客户端对象，需要存储帐户的 Blob 服务帐户 URL 和可用于访问存储帐户的凭据：

from azure.storage.blob import BlobServiceClient

service = BlobServiceClient(account_url="https://<my-storage-account-name>.blob.core.windows.net/", credential=credential)

查找帐户 URL

可以使用 Azure 门户、Azure PowerShell或 Azure CLI 查找存储帐户的 Blob 服务 URL：

# Get the blob service account url for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.blob"

凭据类型

参数 credential 可能以多种不同的形式提供，具体取决于要使用的授权类型：

若要使用 Azure Active Directory (AAD) 令牌凭据，请提供从 azure 标识库获取的所需凭据类型的实例。例如， DefaultAzureCredential 可用于对客户端进行身份验证。

这需要一些初始设置：
- 安装 azure-identity
- 注册新的 AAD 应用程序并授予访问 Azure 存储的权限
- 在 Azure 门户中使用 RBAC 授予对 Azure Blob 数据的访问权限
- 将 AAD 应用程序的客户端 ID、租户 ID 和客户端密码的值设置为环境变量：AZURE_TENANT_ID、AZURE_CLIENT_ID、AZURE_CLIENT_SECRET
使用返回的令牌凭据对客户端进行身份验证：
```
    from azure.identity import DefaultAzureCredential
    from azure.storage.blob import BlobServiceClient
    token_credential = DefaultAzureCredential()

    blob_service_client = BlobServiceClient(
        account_url="https://<my_account_name>.blob.core.windows.net",
        credential=token_credential
    )
```

若要使用共享访问签名 (SAS) 令牌，请以字符串的形式提供令牌。如果帐户 URL 包含 SAS 令牌，请省略凭据参数。可以从 Azure 门户的“共享访问签名”下生成 SAS 令牌，或使用其中 generate_sas() 一个函数为存储帐户、容器或 Blob 创建 sas 令牌：

from datetime import datetime, timedelta
from azure.storage.blob import BlobServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

blob_service_client = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential=sas_token)

若要使用存储帐户共享密钥 (又名帐户密钥或访问密钥) ，请以字符串的形式提供密钥。这可以在 Azure 门户的“访问密钥”部分下找到，也可以通过运行以下 Azure CLI 命令找到：

az storage account keys list -g MyResourceGroup -n MyStorageAccount

使用密钥作为凭据参数对客户端进行身份验证：
```
from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential="<account_access_key>")
```
如果使用 自定义 url (这意味着 url 不是此格式 <my_account_name>.blob.core.windows.net) ，请使用以下凭据实例化客户端：
```
from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", 
   credential={"account_name": "<your_account_name>", "account_key":"<account_access_key>"})
```
若要使用匿名公共读取访问权限，只需省略凭据参数。

从连接字符串创建客户端

根据用例和授权方法，你可能更喜欢使用存储连接字符串初始化客户端实例，而不是单独提供帐户 URL 和凭据。为此，请将存储连接字符串传递给客户端的 from_connection_string 类方法：

from azure.storage.blob import BlobServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = BlobServiceClient.from_connection_string(conn_str=connection_string)

存储帐户的连接字符串可以在 Azure 门户的“访问密钥”部分下找到，也可以通过运行以下 CLI 命令找到：

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

关键概念

以下组件构成 Azure Blob 服务：

存储帐户本身
存储帐户中的容器
容器中的 Blob

使用适用于 Python 的 Azure 存储 Blob 客户端库，可以使用专用客户端对象来与其中每个组件进行交互。

客户端

提供了四个不同的客户端来与 Blob 服务的各个组件进行交互：

BlobServiceClient - 此客户端表示与 Azure 存储帐户本身的交互，并允许你获取预配置的客户端实例以访问其中的容器和 Blob。它提供检索和配置帐户属性以及列出、创建和删除帐户中的容器的操作。若要对特定容器或 Blob 执行操作，请使用 get_container_client 或 get_blob_client 方法检索客户端。
ContainerClient - 此客户端表示与特定容器 (交互，该容器) 尚不存在，并允许获取预配置的客户端实例以访问其中的 blob。它提供创建、删除或配置容器的操作，并包括列出、上传和删除容器中的 Blob 的操作。若要对容器中的特定 Blob 执行操作，请使用 get_blob_client 方法检索客户端。
BlobClient - 此客户端表示与特定 blob (交互，该 blob 尚不存在) 。它提供上传、下载、删除和创建 Blob 快照的操作，以及每个 Blob 类型的特定操作。
BlobLeaseClient - 此客户端表示与 ContainerClient 或 BlobClient的租用交互。它提供获取、续订、释放、更改和中断指定资源租约的操作。

异步客户端

此库包含 Python 3.5+ 上支持的完整异步 API。若要使用它，必须先安装异步传输，例如 aiohttp。有关详细信息，请参阅 azure-core 文档。

不再需要异步客户端和凭据时，应将其关闭。这些对象是异步上下文管理器并定义异步 close 方法。

Blob 类型

初始化客户端后，可以从不同类型的 Blob 中进行选择：

块 Blob 存储文本和二进制数据，最大约为 4.75 TiB。块 Blob 由可以单独管理的数据块组成
与块 Blob 一样，追加 Blob 也由块构成，但针对追加操作进行了优化。追加 Blob 非常适合用于记录虚拟机中的数据等方案
页 Blob 用于存储最大 8 TiB 的随机访问文件。页 blob (VHD) 文件存储虚拟硬盘驱动器，并用作 Azure 虚拟机的磁盘

示例

以下部分提供了几个代码片段，涵盖了一些最常见的存储 Blob 任务，包括：

创建容器
上传 Blob
下载 Blob
枚举 Blob

请注意，必须先创建容器，然后才能上传或下载 Blob。

创建容器

创建可从中上传或下载 Blob 的容器。

from azure.storage.blob import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

container_client.create_container()

使用异步客户端上传 Blob

from azure.storage.blob.aio import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

await container_client.create_container()

上传 Blob

将 Blob 上传到容器

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    blob.upload_blob(data)

使用异步客户端上传 Blob

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    await blob.upload_blob(data)

下载 Blob

从容器下载 Blob

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    blob_data = blob.download_blob()
    blob_data.readinto(my_blob)

异步下载 Blob

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    stream = await blob.download_blob()
    data = await stream.readall()
    my_blob.write(data)

枚举 Blob

列出容器中的 Blob

from azure.storage.blob import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = container.list_blobs()
for blob in blob_list:
    print(blob.name + '\n')

异步列出 Blob

from azure.storage.blob.aio import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = []
async for blob in container.list_blobs():
    blob_list.append(blob)
print(blob_list)

可选配置

可选关键字 (keyword) 可在客户端和每个操作级别传入的参数。

重试策略配置

在实例化客户端时使用以下关键字 (keyword) 参数来配置重试策略：

retry_total (int) ：允许的重试总数。优先于其他计数。 retry_total=0如果不想对请求重试，请传入。默认值为 10。
retry_connect (int) ：重试多少个与连接相关的错误。默认值为 3。
retry_read (int) ：读取错误时重试的次数。默认值为 3。
retry_status (int) ：对错误状态代码重试的次数。默认值为 3。
retry_to_secondary (bool) ：是否应将请求重试到辅助数据库（如果可以）。应仅启用 RA-GRS 帐户，并可以处理可能过时的数据。默认为 False。

加密配置

实例化客户端时使用以下关键字 (keyword) 参数来配置加密：

require_encryption (bool) ：如果设置为 True，将强制对对象进行加密和解密。
encryption_version (str) ：指定要使用的加密版本。当前选项为 '2.0' 或 '1.0' ，默认值为 '1.0'。版本 1.0 已弃用， 强烈建议 使用版本 2.0。
key_encryption_key (对象) ：用户提供的 key-encryption-key。实例必须实现以下方法：
- wrap_key(key)--使用用户选择的算法包装指定的密钥。
- get_key_wrap_algorithm()--返回用于包装指定对称密钥的算法。
- get_kid()--返回此 key-encryption-key 的字符串密钥 ID。
key_resolver_function (可调用) ：用户提供的密钥解析程序。使用子字符串返回实现上面定义的接口的 key-encryption-key。

其他客户端/每操作配置

其他可选配置关键字 (keyword) 可在客户端或每个操作上指定的参数。

客户端关键字 (keyword) 参数：

connection_timeout (int) ：客户端将等待与服务器建立连接的秒数。默认为 20 秒。
read_timeout (int) ：客户端在连续读取操作之间等待服务器响应的秒数。这是套接字级别超时，不受整体数据大小的影响。客户端读取超时将自动重试。默认值为 60 秒。
传输 (任何) ：用户提供的用于发送 HTTP 请求的传输。

每个操作关键字 (keyword) 参数：

raw_response_hook (可调用) ：给定回调使用从服务返回的响应。
raw_request_hook (可调用) ：给定回调在发送到服务之前使用请求。
client_request_id (str) ：请求的可选用户指定标识。
user_agent (str) ：将自定义值追加到要随请求发送的用户代理标头。
logging_enable (bool) ：在 DEBUG 级别启用日志记录。默认为 False。还可以在客户端级别传入以为所有请求启用它。
logging_body (bool) ：启用记录请求和响应正文。默认为 False。还可以在客户端级别传入以为所有请求启用它。
标头 (dict) ：将自定义标头作为键、值对传入。例如 headers={'CustomValue': value}

疑难解答

常规

存储 Blob 客户端引发 Azure Core 中定义的异常。

此列表可用于引用以捕获引发的异常。若要获取异常的特定错误代码，请使用 error_code 属性，即 exception.error_code。

日志记录

此库使用标准日志记录库进行日志记录。有关 HTTP 会话 (URL、标头等 ) 的基本信息记录在信息级别。

可以使用参数在客户端 logging_enable 上启用详细的 DEBUG 级别日志记录，包括请求/响应正文和未执行的标头：

import sys
import logging
from azure.storage.blob import BlobServiceClient

# Create a logger for the 'azure.storage.blob' SDK
logger = logging.getLogger('azure.storage.blob')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = BlobServiceClient.from_connection_string("your_connection_string", logging_enable=True)

同样，即使没有为客户端启用详细日志记录，logging_enable 也可以为单个操作启用：

service_client.get_service_stats(logging_enable=True)

后续步骤

其他文档

有关 Azure Blob 存储的更多文档，请参阅有关 docs.microsoft.com 的 Azure Blob 存储文档。

贡献

本项目欢迎贡献和建议。大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。有关详细信息，请访问 https://cla.microsoft.com 。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。直接按机器人提供的说明操作。只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与联系。