使用 Python 列出 Blob

• .NET
• Java
• JavaScript
• Python
• Go

本文展示了如何使用Python的Azure 存储客户端库来列出blob。

要了解如何使用异步 API 列出 Blob，请参见“异步列出 Blob”。

先决条件

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

设置你的环境

如果没有现有项目，请查看本部分，其中介绍如何设置项目来使用适用于 Python 的 Azure Blob 存储客户端库。 有关更多详细信息，请参阅 Azure Blob 存储和 Python 入门。

要使用本文中的代码示例，请按照以下步骤设置项目。

安装包

使用 pip install 安装以下包：

pip install azure-storage-blob azure-identity

添加 import 语句

添加以下 import 语句：

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

授权

授权机制必须具有列出 Blob 所需的权限。 要使用 Microsoft Entra ID 进行授权（推荐），你需要具有 Azure RBAC 内置角色 Storage Blob Data Reader 或更高级别的角色。 有关详细信息，请参阅列出 Blob (REST API) 的授权指南。

创建客户端对象

若要将应用连接到 Blob 存储，请创建 BlobServiceClient 的实例。 以下示例演示如何使用 DefaultAzureCredential 创建客户端对象以进行授权：

# 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)

你还可以为特定容器或 Blob 创建客户端对象，不管是直接创建还是通过 BlobServiceClient 对象创建。 若要详细了解如何创建和管理客户端对象，请参阅创建和管理与数据资源交互的客户端对象。

关于 Blob 列出选项

当你在代码中列出 Blob 时，可以指定许多选项来控制 Azure 存储返回结果的方式。 可以指定要在每个结果集中返回的结果数，然后检索后续结果集。 可以指定前缀以返回名称以该字符或字符串开头的 blob。 你可以用平面列表结构或层级方式列出blobs。 分层列表返回 Blob，如同它们组织为文件夹一样。

要使用平面列表列出容器中的blob，请调用以下方法之一：

• ContainerClient.list_blobs （除名称外，可选地包含与每个blob相关的元数据、标签及其他信息）
• ContainerClient.list_blob_names（仅返回 blob 名称）

要通过层级列表列出容器中的blob，调用以下方法：

• ContainerClient.walk_blobs （除了名称外，可选地包含与每个 blob 相关的元数据、标签及其他信息）

使用前缀筛选结果

若要筛选 Blob 列表，请为 name_starts_with 关键字参数指定一个字符串。 前缀字符串可以包含一个或多个字符。 Azure 存储只返回以该前缀开头的blobs。

平面列表与分层列表

Azure 存储中的 Blob 以平面范式进行组织，而不是以分层范式（类似于经典文件系统）进行组织。 不过，你可以将blobs组织成 虚拟目录 ，模拟文件夹结构。 虚拟目录构成 blob 名称的一部分，并由分隔符表示。

若要将 blob 组织为虚拟目录，请在 blob 名称中使用分隔符。 默认分隔符是正斜杠 (/)，但你可以指定任何字符作为分隔符。

如果使用分隔符来为 Blob 命名，则可以选择按层级列出 Blob。 对于分层列出操作，Azure 存储将返回父对象下的所有虚拟目录和 blob。 可以递归方式调用列出操作来遍历层次结构，类似于以编程方式遍历经典文件系统。

使用平面列表

默认情况下，列出操作在平面列表中返回 Blob。 在平面列表中，Blob 不会按虚拟目录进行组织。

以下示例通过平面列表列出指定容器中的blob：

def list_blobs_flat(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    blob_list = container_client.list_blobs()

    for blob in blob_list:
        print(f"Name: {blob.name}")

示例输出类似于：

List blobs flat:
Name: file4.txt
Name: folderA/file1.txt
Name: folderA/file2.txt
Name: folderA/folderB/file3.txt

你还可以指定筛选结果列表或显示更多信息的选项。 下面的示例列出了 Blob 和 Blob 标记：

def list_blobs_flat_options(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    blob_list = container_client.list_blobs(include=['tags'])

    for blob in blob_list:
        print(f"Name: {blob['name']}, Tags: {blob['tags']}")

示例输出类似于：

List blobs flat:
Name: file4.txt, Tags: None
Name: folderA/file1.txt, Tags: None
Name: folderA/file2.txt, Tags: None
Name: folderA/folderB/file3.txt, Tags: {'tag1': 'value1', 'tag2': 'value2'}

注意

所显示的示例输出假定你有一个带平面命名空间的存储帐户。 如果你为存储账户启用了分层命名空间功能，目录就不是虚拟的。 相反，它们是具体的、独立的物体。 因此，目录会在列表中显示为零长度 Blob。

有关使用分层命名空间时的备用列表选项，请参阅列出目录内容 (Azure Data Lake Storage)。

使用分层列表

以分层方式调用列出操作时，Azure 存储将返回位于层次结构第一级别的虚拟目录和 Blob。

若要按层次结构列出 Blob，请使用以下方法：

• ContainerClient.walk_blobs

以下示例使用分层列表列出指定容器中的 Blob：

depth = 0
indent = "  "
def list_blobs_hierarchical(self, container_client: ContainerClient, prefix):
    for blob in container_client.walk_blobs(name_starts_with=prefix, delimiter='/'):
        if isinstance(blob, BlobPrefix):
            # Indentation is only added to show nesting in the output
            print(f"{self.indent * self.depth}{blob.name}")
            self.depth += 1
            self.list_blobs_hierarchical(container_client, prefix=blob.name)
            self.depth -= 1
        else:
            print(f"{self.indent * self.depth}{blob.name}")

示例输出类似于：

folderA/
  folderA/folderB/
    folderA/folderB/file3.txt
  folderA/file1.txt
  folderA/file2.txt
file4.txt

注意

Blob 快照无法在分层列出操作中列出。

异步列出 Blob

适用于 Python 的 Azure Blob 存储客户端库支持异步列出 Blob。 要详细了解项目设置要求，请参阅异步编程。

按照以下步骤，使用异步 API 列出 Blob：

1. 添加以下 import 语句：

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

2. 通过使用 asyncio.run添加运行程序的代码。 该函数运行传入的协程（此示例中为 main()），并管理 asyncio 事件循环。 协程使用 async/await 语法来声明。 在这个例子中，main() 协程首先使用 BlobServiceClient 创建顶级 async with，然后调用列出这些 blob 的方法。 只有顶级客户端需要使用 async with，因为基于它创建的其他客户端会共享同一连接池。

   async def main():
       sample = BlobSamples()
   
       # 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:
           await sample.list_blobs_flat(blob_service_client, "sample-container")
   
   if __name__ == '__main__':
       asyncio.run(main())
   

3. 添加代码以列出 Blob。 以下代码示例演示了如何使用平面列出方式列出 Blob。 该代码与同步示例相同，不同之处在于方法通过使用 async 关键字声明，并在 async for 调用 list_blobs 该方法时使用。

   async def list_blobs_flat(self, blob_service_client: BlobServiceClient, container_name):
       container_client = blob_service_client.get_container_client(container=container_name)
   
       async for blob in container_client.list_blobs():
           print(f"Name: {blob.name}")
   

有了这个基本配置后，你就可以使用 async/await 语法，将本文中的其他示例作为协程来实现。

以 Apache Arrow 格式列出 Blob（预览）

Important

Apache Arrow格式的blob列表目前处于 预览阶段。 此场景需要Python Azure Blob 存储客户端库的测试版（预览azure-storage-blob版），例如12.31.0b1或更高版本的预览版。 预览版功能在没有服务级别协议的情况下提供，不建议用于生产工作负荷。 有些功能可能不被支持，或者功能受限。 有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。

该功能基于现有 List Blobs API。 它没有使用默认的 XML，而是使用紧凑的列状 Apache Arrow 格式作为线路上的响应格式。 你可以通过在容器列表调用中设置一个选项来启用它。 Python SDK 在幕后解码 Apache Arrow，仍然返回相同的BlobProperties对象。 这种方法在枚举大型容器时提高了列表吞吐量并减少客户端 CPU。 它保留了应用程序所依赖的响应合同。

Warning

在启用层级命名空间（Azure Data Lake Storage）的存储账户上，不支持Apache Arrow格式的blob列表。

要请求Apache Arrow格式的结果，请将关键词参数设置为response_format"arrow"调用ContainerClient.list_blobs或ContainerClient.list_blob_names时。 使用 Apache Arrow 输出时，你还可以设置 start_from 和 end_before 关键字参数来控制返回路径的范围。

注意

使用 response_format="arrow" 时需要安装 nanoarrow 软件包。

以下示例列出容器中的blobs，并请求以Apache Arrow格式获取结果：

# response_format="arrow" requires the nanoarrow package to be installed
blob_list = container_client.list_blobs(
    name_starts_with="folderA/",
    response_format="arrow",
)

for blob in blob_list:
    print("Name: " + blob.name)

资源

想了解如何使用Python的Azure Blob 存储客户端库来列出blob，请参见以下资源。

代码示例

• 查看本文（GitHub）中的同步或异步代码示例。

REST API 操作

Azure SDK for Python包含基于Azure REST API构建的库。 通过使用这些库，你可以通过熟悉的 Python 范式与 REST API 操作交互。 用于列出 Blob 的客户端库方法使用以下 REST API 操作：

• 列出 Blob (REST API)

客户端库资源

• 客户端库参考文档
• 客户端库源代码
• 包 (PyPi)

另请参阅

• 枚举 Blob 资源
• Blob 版本控制

相关内容

• 本文是 Python 版 Blob 存储开发人员指南的一部分。 若要了解详细信息，请参阅构建 Python 应用中的完整开发人员指南文章列表。