使用 Python 列出 Blob

本文介绍如何使用适用于 Python 的 Azure 存储客户端库列出 blob。

要了解如何使用异步 API 列出 blob,请参阅异步列出 blob

先决条件

  • 本文假设已经设置了项目来使用适用于 Python 的 Azure Blob 存储客户端库。 若要了解如何设置项目(包括安装包、添加 import 语句和创建授权客户端对象),请参阅开始使用 Azure Blob 存储和 Python
  • 要通过代码使用异步 API,请参阅异步编程部分中的要求。
  • 授权机制必须具有列出 blob 的权限。 若要了解详细信息,请参阅以下 REST API 操作的授权指南:

了解 blob 列出选项

通过代码列出 Blob 时,可以指定多个选项来管理如何从 Azure 存储返回结果。 可以指定要在每个结果集中返回的结果数,然后检索后续结果集。 可以指定前缀以返回名称以该字符或字符串开头的 blob。 而且,可以在平面列表结构中列出 blob,也可以分层列出 blob。 分层列表返回 blob,就像它们被组织到文件夹中一样。

若要使用扁平列表列出容器中的 blob,请调用以下方法之一:

若要使用分层列表列出容器中的 Blob,请调用以下方法:

  • ContainerClient.walk_blobs(以及名称,你还可以选择性地包括元数据、标记以及与每个 blob 关联的其他信息)

使用前缀筛选结果

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

平面列表与分层列表

Azure 存储中的 Blob 以平面范式进行组织,而不是以分层范式(类似于经典文件系统)进行组织。 但是,可以将 Blob 组织到虚拟目录中,以便模拟文件夹结构。 虚拟目录构成 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 Gen2)

使用分层列表

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

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

以下示例使用分层列表列出指定容器中的 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
  1. 添加代码以使用asyncio.run运行程序。 此函数运行传递的协同例程(我们示例中的main()),并管理asyncio事件循环。 使用 async/await 语法声明协同例程。 在此示例中,main() 协同例程先使用 async with 创建顶级 BlobServiceClient,然后调用列出 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.chinacloudapi.cn"
    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())
  1. 添加代码以列出 blob。 下面的示例代码使用平面列表列出了 blob。 该代码与同步示例相同,但是,在声明该方法时使用了 async 关键字,调用 list_blobs 方法时使用了 async for
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 语法将本文中的其他示例实现为协同例程。

资源

若要详细了解如何使用适用于 Python 的 Azure Blob 存储客户端库来列出 blob,请参阅以下资源。

REST API 操作

Azure SDK for Python 包含基于 Azure REST API 而生成的库,允许你通过熟悉的 Python 范例与 REST API 操作进行交互。 用于列出 blob 的客户端库方法使用以下 REST API 操作:

代码示例

客户端库资源

另请参阅