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

Azure Blob 存储和 Python 入门

• .NET
• Java
• JavaScript
• Python
• Go

本文介绍如何使用适用于 Python 的 Azure Blob 存储客户端库连接到 Azure Blob 存储。 连接后，使用开发人员指南来了解你的代码如何对 Blob 存储服务的容器、Blob 和功能进行操作。

要从完整示例入手，请参阅快速入门：适用于 Python 的 Azure Blob 存储客户端库。

API 参考 | 包 (PyPi) | 库源代码 | 示例 | 提供反馈

先决条件

• Azure 订阅 - 创建免费帐户
• Azure 存储帐户 - 创建存储帐户
• Python 3.8+

设置项目

本部分逐步指导如何准备一个项目，使其与适用于 Python 的 Azure Blob 存储客户端库配合使用。

从项目目录中，使用 pip install 命令安装 Azure Blob 存储和 Azure 标识客户端库的包。 与 Azure 服务的无密码连接需要 azure-identity 包。

pip install azure-storage-blob azure-identity

然后打开代码文件并添加必要的 import 语句。 在此示例中，我们将以下内容添加到 .py 文件：

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient, ContainerClient

Blob 客户端库信息：

• azure.storage.blob：包含可用于对服务、容器和 Blob 执行操作的主要类（客户端对象）。

异步编程

适用于 Python 的 Azure Blob 存储客户端库支持同步和异步 API。 异步 API 基于 Python 的 asyncio 库。

按照以下步骤在项目中使用异步 API：

• 安装异步传输，例如 aiohttp。 可以使用可选的依赖项安装命令来一起安装 aiohttp 和 azure-storage-blob。 在此示例中，我们使用以下 pip install 命令：

  pip install azure-storage-blob[aio]
  

• 打开代码文件并添加必要的 import 语句。 在此示例中，我们将以下内容添加到 .py 文件：

  import asyncio
  
  from azure.identity.aio import DefaultAzureCredential
  from azure.storage.blob.aio import BlobServiceClient, BlobClient, ContainerClient
  

  只有在代码中使用库时，才需要 import asyncio 语句。 为了清楚起见，此处添加了该语句，因为开发人员指南文章中的示例使用 asyncio 库。

• 使用 async with 创建客户端对象以开始使用数据资源。 只有顶级客户端需要使用 async with，因为基于它创建的其他客户端会共享同一连接池。 在此示例中，我们将使用 async with 创建 BlobServiceClient 对象，然后再创建 ContainerClient 对象：

  async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
      container_client = blob_service_client.get_container_client(container="sample-container")
  

  若要了解详细信息，请参阅授权访问和连接到 Blob 存储中的异步示例。

Blob 异步客户端库信息：

• azure.storage.blob.aio：包含可用于对服务、容器和 Blob 执行异步操作的主要类。

授予访问权限并连接到 Blob 存储

若要将应用连接到 Blob 存储，请创建 BlobServiceClient 类的实例。 此对象是在存储帐户级别与数据资源交互的起点。 可以将其用于对存储账户及其容器执行操作。 还可以使用服务客户端创建容器客户端或 blob 客户端，具体取决于需要使用的资源。

若要详细了解如何创建和管理客户端对象（包括最佳做法），请参阅创建和管理与数据资源交互的客户端对象。

你可以使用 Microsoft Entra 授权令牌、帐户访问密钥或共享访问签名 (SAS) 来为 BlobServiceClient 对象授权。 为了获得最佳安全性，Microsoft 建议使用 Microsoft Entra ID 和托管标识来授权针对 blob 数据的请求。 有关详细信息，请参阅使用 Microsoft Entra ID 授予对 blob 的访问权限。

Microsoft Entra ID（推荐）

若要通过 Microsoft Entra ID 授权，需要使用安全主体。 需要哪种类型的安全主体取决于应用的运行位置。 使用下表作为指南：

应用的运行位置	安全主体	指南
本地计算机（开发和测试）	服务主体	若要了解如何注册应用、设置 Microsoft Entra 组、分配角色和配置环境变量，请参阅使用开发人员服务主体授权访问
本地计算机（开发和测试）	用户标识	若要了解如何设置 Microsoft Entra 组、分配角色和登录到 Azure，请参阅使用开发人员凭据授权访问
在 Azure 中托管	托管标识	若要了解如何启用托管标识和分配角色，请参阅使用托管标识授权从 Azure 托管应用访问
托管在 Azure 外部（例如本地应用）	服务主体	若要了解如何注册应用、分配角色和配置环境变量，请参阅使用应用程序服务主体授权从本地应用访问

使用 DefaultAzureCredential 授权访问

要授予访问权限并连接到 Blob 存储，一种简单且安全的方法是通过创建 DefaultAzureCredential 实例来获取 OAuth 令牌。 然后就可以使用该凭据创建 BlobServiceClient 对象。

以下示例使用 DefaultAzureCredential 创建 BlobServiceClient 对象:

def get_blob_service_client_token_credential(self):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    credential = DefaultAzureCredential()

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient(account_url, credential=credential)

    return blob_service_client

如果项目使用异步 API，请使用 async with 实例化 BlobServiceClient：

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"
credential = DefaultAzureCredential()

async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
    # Work with data resources in the storage account

SAS 令牌

若要使用共享访问签名 (SAS) 令牌，请以字符串的形式提供令牌并初始化 BlobServiceClient 对象。 如果帐户 URL 包含 SAS 令牌，请省略凭据参数。

def get_blob_service_client_sas(self, sas_token: str):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    # The SAS token string can be assigned to credential here or appended to the account URL
    credential = sas_token

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient(account_url, credential=credential)

    return blob_service_client

如果项目使用异步 API，请使用 async with 实例化 BlobServiceClient：

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"

# Replace <sas_token_str> with your actual SAS token
sas_token: str = "<sas_token_str>"

async with BlobServiceClient(account_url, credential=sas_token) as blob_service_client:
    # Work with data resources in the storage account

要详细了解如何生成和管理 SAS 令牌，请参阅以下文章:

• 使用共享访问签名 (SAS) 授予对 Azure 存储资源的有限访问权限
• 使用 Python 创建帐户 SAS
• 使用 Python 创建服务 SAS
• 使用 Python 创建用户委派 SAS

注意

对于使用共享访问签名 (SAS) 的场景，Microsoft 建议使用用户委派 SAS。 用户委派 SAS 通过 Microsoft Entra 凭据（而不是帐户密钥）进行保护。

帐户密钥

若要使用存储帐户共享密钥，请以字符串的形式提供密钥并初始化 BlobServiceClient 对象。

def get_blob_service_client_account_key(self):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    shared_access_key = os.getenv("AZURE_STORAGE_ACCESS_KEY")
    credential = shared_access_key

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient(account_url, credential=credential)

    return blob_service_client

还可以使用连接字符串创建 BlobServiceClient 对象。

def get_blob_service_client_connection_string(self):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    connection_string = os.getenv("AZURE_STORAGE_CONNECTION_STRING")

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient.from_connection_string(connection_string)

    return blob_service_client

如果项目使用异步 API，请使用 async with 实例化 BlobServiceClient：

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"

shared_access_key = os.getenv("AZURE_STORAGE_ACCESS_KEY")

async with BlobServiceClient(account_url, credential=shared_access_key) as blob_service_client:
    # Work with data resources in the storage account

有关如何获取帐户密钥的信息以及正确管理和保护密钥的最佳做法指导，请参阅管理存储帐户访问密钥。

重要

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

生成应用

在生成应用以使用 Azure Blob 存储中的数据资源时，代码主要与三种资源类型进行交互：存储帐户、容器和 Blob。 若要详细了解这些资源类型、它们彼此之间的关系以及应用如何与资源交互，请参阅了解应用如何与 Blob 存储数据资源交互。

以下指南介绍了如何使用适用于 Python 的 Azure 存储客户端库来访问数据和执行特定操作：

指南	说明
配置重试策略	针对客户端操作实施重试策略。
复制 blob	将 Blob 从一个位置移复制到另一个位置。
创建容器	创建 Blob 容器。
创建用户委托 SAS	为容器或 blob 创建用户委派 SAS。
创建和管理 Blob 租用	在 Blob 上建立和管理锁。
创建和管理容器租用	在容器上建立和管理锁。
删除和还原 blob	删除 Blob 和还原已软删除的 Blob。
删除和还原容器	删除容器和还原已软删除的容器。
下载 blob	使用字符串、流和文件路径下载 Blob。
使用标记查找 Blob	设置和检索标记，以及使用标记来查找 Blob。
列出 Blob	以不同的方式列出 Blob。
列出容器	列出帐户中的容器以及可用于自定义列表的各个选项。
管理属性和元数据 (Blob)	获取和设置 Blob 的属性与元数据。
管理属性和元数据（容器）	获取和设置容器的属性与元数据。
优化数据传输性能	优化数据传输操作的性能。
设置或更改 blob 的访问层	设置或更改块 blob 的访问层。
上传 Blob	了解如何使用字符串、流、文件路径和其他方法上传 Blob。