Azure Storage Blobs客户端库（Python版）

Azure Blob存储是微软的云对象存储解决方案。Blob存储针对存储大量非结构化数据进行了优化，例如文本或二进制数据。

Blob存储非常适合

• 直接向浏览器提供图像或文档
• 存储分布式访问的文件
• 流式传输视频和音频
• 存储用于备份、恢复、灾难恢复和存档的数据
• 存储用于由本地或Azure托管的服务分析的数据

源代码 | 包（PyPI） | 包（Conda） | API参考文档 | 产品文档 | 示例

入门

先决条件

• 使用此包需要Python 3.8或更高版本。有关更多详细信息，请参阅我们关于Azure SDK for Python版本支持策略的页面。
• 您必须拥有Azure订阅和Azure存储账户才能使用此包。

安装包

使用pip安装Azure Storage Blobs客户端库

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 Storage Blobs客户端库允许您与三种类型的资源进行交互：存储账户本身、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参数可以以多种形式提供。

1. 要使用Azure Active Directory (AAD)令牌凭据，请提供一个从azure-identity库获取的所需凭据类型的实例。例如，可以使用DefaultAzureCredential来验证客户端。

   这需要一些初始设置

   • 安装azure-identity
   • 注册新的AAD应用程序并授予其访问Azure存储的权限
   • 在Azure门户中授予访问权限
   • 将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
       )
   

2. 要使用共享访问签名(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)
   

3. 要使用存储账户共享密钥(也称为账户密钥或访问密钥)，请提供作为字符串的密钥。这可以在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>"})
   

4. 要使用 匿名公共读取访问，只需省略凭证参数。

从连接字符串创建客户端

根据您的用例和授权方法，您可能更愿意使用存储连接字符串初始化客户端实例，而不是分别提供帐户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

Azure Storage Blobs Python客户端库允许您通过使用专用客户端对象与这些组件交互。

客户端

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

1. BlobServiceClient - 此客户端表示与Azure存储帐户的交互，允许您获取预配置的客户端实例以访问容器和blob。它提供检索和配置帐户属性的操作，以及列出、创建和删除帐户中的容器。要对特定容器或blob执行操作，请使用 get_container_client 或 get_blob_client 方法检索客户端。
2. ContainerClient - 此客户端表示与特定容器的交互（该容器可能尚不存在），允许您获取预配置的客户端实例以访问其中的blob。它提供创建、删除或配置容器的操作，以及列出、上传和删除其中blob的操作。要对容器中的特定blob执行操作，请使用 get_blob_client 方法检索客户端。
3. BlobClient - 此客户端表示与特定blob的交互（该blob可能尚不存在）。它提供上传、下载、删除blob以及创建blob快照的操作，以及针对每种blob类型的特定操作。
4. 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()

使用异步客户端创建容器

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)

可选配置

可以在客户端和每个操作级别传递的可选关键字参数。

重试策略配置

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

• 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。

加密配置

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

• require_encryption (bool): 如果设置为 True，将强制加密对象并对其进行解密。
• encryption_version (str): 指定要使用的加密版本。当前选项是 '2.0' 或 '1.0'，默认值为 '1.0'。版本 1.0 已弃用，强烈建议使用版本 2.0。
• key_encryption_key (object): 用户提供的密钥加密密钥。该实例必须实现以下方法
  • wrap_key(key) -- 使用用户选择的算法包装指定的密钥。
  • get_key_wrap_algorithm() -- 返回用于包装指定的对称密钥的算法。
  • get_kid() -- 返回该密钥加密密钥的字符串密钥 ID。
• key_resolver_function (callable): 用户提供的密钥解析器。使用 kid 字符串返回实现上述接口的密钥加密密钥。

其他客户端/每个操作配置

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

客户端关键字参数

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

每个操作关键字参数

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

故障排除

常规

存储 Blob 客户端抛出在 Azure Core 中定义的异常。

此列表可用于参考以捕获抛出的异常。要获取异常的具体错误代码，请使用 error_code 属性，即 exception.error_code。

日志记录

此库使用标准的 logging 库进行日志记录。基本信息（URL、头等）以 INFO 级别记录。

启用详细的 DEBUG 级别日志记录，包括请求/响应体和未脱敏的头，可以通过客户端的 logging_enable 参数启用

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)

下一步

更多示例代码

从我们的 Blob 示例 开始。

在 SDK 的 GitHub 存储库中，您可以找到多个 Storage Blobs Python SDK 示例。这些示例提供了在处理存储 Blob 时常见场景的示例代码。

• blob_samples_container_access_policy.py (异步版本) - 设置访问策略的示例

  • 设置容器访问策略

• blob_samples_hello_world.py (异步版本) - 常见 Storage Blob 任务的示例

  • 设置容器
  • 创建块、页或追加 Blob
  • 上传 Blob
  • 下载 Blob
  • 删除 Blob

• blob_samples_authentication.py (异步版本) - 验证和创建客户端的示例

  • 从连接字符串
  • 从共享访问键
  • 从共享访问签名令牌
  • 从活动目录

• blob_samples_service.py (异步版本) - 与 Blob 服务交互的示例

  • 获取帐户信息
  • 获取和设置服务属性
  • 获取服务统计信息
  • 创建、列出和删除容器
  • 获取 Blob 或容器客户端

• blob_samples_containers.py (异步版本) - 与容器交互的示例

  • 创建容器和删除容器
  • 在容器上设置元数据
  • 获取容器属性
  • 在容器上获取租约
  • 在容器上设置访问策略
  • 在容器中上传、列出和删除 Blob
  • 获取 Blob 客户端以与特定 Blob 交互

• blob_samples_common.py (异步版本) - 适用于所有类型 Blob 的通用示例

  • 创建快照
  • 删除 Blob 快照
  • 软删除 Blob
  • 撤销删除 Blob
  • 获取Blob的租赁
  • 从URL复制Blob

• blob_samples_directory_interface.py - 以文件系统中的目录方式与Blob存储交互的示例

  • 复制（上传或下载）单个文件或目录
  • 列出单级或递归目录下的文件或目录
  • 删除单个文件或递归删除目录

其他文档

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

贡献

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

当您提交拉取请求时，CLA机器人将自动确定您是否需要提供CLA，并相应地装饰PR（例如，标签、注释）。只需遵循机器人提供的说明即可。您只需在整个使用我们的CLA的repo中进行一次操作。

本项目已采用Microsoft开源行为准则。有关更多信息，请参阅行为准则FAQ或通过opencode@microsoft.com联系以获取任何额外的问题或评论。