使用 Python 列出 Blob 容器

通过代码列出 Azure 存储帐户中的容器时，可以指定多个选项来管理如何从 Azure 存储返回结果。 本文介绍如何使用适用于 Python 的 Azure 存储客户端库列出容器。

若要了解如何使用异步 API 列出 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

授权

授权机制必须具有列出 Blob 容器所需的权限。 若要使用 Microsoft Entra ID 进行授权（建议），需有 Azure RBAC 内置角色“存储 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.chinacloudapi.cn"
credential = DefaultAzureCredential()

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

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

关于容器列出选项

通过代码列出容器时，可以指定选项来管理如何从 Azure 存储返回结果。 可以指定要在每个结果集中返回的结果数，然后检索后续结果集。 还可以按前缀筛选结果，并将容器元数据与结果一起返回。 后续部分将介绍这些选项。

若要列出存储帐户中的容器，请调用以下方法：

• BlobServiceClient.list_containers

此方法返回 ContainerProperties 类型的可迭代项。 容器按名称的字典顺序排序。

管理要返回的结果数

默认情况下，列出操作每次最多返回 5000 个结果。 若要返回较小的结果集，请为 results_per_page 关键字自变量提供非零值。

使用前缀筛选结果

若要筛选容器列表，请为 name_starts_with 关键字自变量指定字符串或字符。 前缀字符串可以包含一个或多个字符。 然后，Azure 存储只返回其名称以该前缀开头的容器。

包括容器元数据

若要在结果中包含容器元数据，请将 include_metadata 关键字自变量设置为 True。 Microsoft Azure 存储包含返回的每个容器的元数据，因此无需单独提取容器元数据。

包括已删除的容器

若要在结果中包含软删除的器，请将 include_deleted 关键字自变量设置为 True。

代码示例

以下示例列出所有容器和元数据。 可以通过将 include_metadata 设置为 True 来包括容器元数据：

def list_containers(self, blob_service_client: BlobServiceClient):
    containers = blob_service_client.list_containers(include_metadata=True)
    for container in containers:
        print(container['name'], container['metadata'])

以下示例仅列出以 name_starts_with 参数中指定的前缀开头的容器：

def list_containers_prefix(self, blob_service_client: BlobServiceClient):
    containers = blob_service_client.list_containers(name_starts_with='test-')
    for container in containers:
        print(container['name'])

你还可以指定每页结果数限制。 此示例传入 results_per_page 并分页显示结果：

def list_containers_pages(self, blob_service_client: BlobServiceClient):
    i=0
    all_pages = blob_service_client.list_containers(results_per_page=5).by_page()
    for container_page in all_pages:
        i += 1
        print(f"Page {i}")
        for container in container_page:
            print(container['name'])

异步列出容器

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

按照以下步骤使用异步 API 列出容器：

1. 添加以下 import 语句：

import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient

1. 添加代码以使用asyncio.run运行程序。 此函数运行传递的协同例程（我们示例中的main()），并管理asyncio事件循环。 使用 async/await 语法声明协同例程。 在此示例中，main() 协同例程先使用 async with 创建顶级 BlobServiceClient，然后调用列出容器的方法。 请注意，只有顶级客户端需要使用async with，因为基于它创建的其他客户端会共享同一连接池。

async def main():
    sample = ContainerSamples()

    # 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_containers(blob_service_client)

if __name__ == '__main__':
    asyncio.run(main())

1. 添加代码以列出容器。 该代码与同步示例相同，但是，在声明该方法时使用了 async 关键字，调用 list_containers 方法时使用了 async for。

async def list_containers(self, blob_service_client: BlobServiceClient):
    async for container in blob_service_client.list_containers(include_metadata=True):
        print(container['name'], container['metadata'])

有了此基本设置，即可使用 async/await 语法将本文中的其他示例实现为协同例程。

资源

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

代码示例

• 查看本文中的同步或异步代码示例 (GitHub)

REST API 操作

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

• 列出容器 (REST API)

客户端库资源

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

另请参阅

• 枚举 Blob 资源

相关内容

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