使用 Java 列出 Blob 容器

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

先决条件

• Azure 订阅 - 创建试用订阅。
• Azure 存储帐户 - 创建存储帐户
• Java 开发工具包 (JDK) 8 或更高版本（我们建议使用版本 17 以获得最佳体验）
• 在本示例中，Apache Maven 用于项目管理

设置你的环境

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

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

安装包

在文本编辑器中打开 pom.xml 文件。 通过包括 BOM 文件或包括直接依赖项来安装包。

添加 import 语句

添加以下 import 语句：

import com.azure.core.http.rest.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;

授权

授权机制必须具有列出 Blob 容器所需的权限。 若要使用 Microsoft Entra ID 进行授权（建议），需有 Azure RBAC 内置角色“存储 Blob 数据参与者”或更高级别的角色。 有关详细信息，请参阅列出容器 (REST API) 的授权指南。

创建客户端对象

若要将应用连接到 Blob 存储，请创建 BlobServiceClient 的实例。

以下示例使用 BlobServiceClientBuilder 生成一个使用 DefaultAzureCredential 的 BlobServiceClient 对象，并演示如何创建容器和 Blob 客户端（如果需要）：

// Azure SDK client builders accept the credential as a parameter
// TODO: Replace <storage-account-name> with your actual storage account name
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .endpoint("https://<storage-account-name>.blob.core.chinacloudapi.cn/")
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

// If needed, you can create a BlobContainerClient object from the BlobServiceClient
BlobContainerClient containerClient = blobServiceClient
        .getBlobContainerClient("<container-name>");

// If needed, you can create a BlobClient object from the BlobContainerClient
BlobClient blobClient = containerClient
        .getBlobClient("<blob-name>");

要详细了解如何创建和管理客户端对象，请参阅 创建和管理与数据资源交互的客户端对象。

关于容器列出选项

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

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

• listBlobContainers

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

管理要返回的结果数

默认情况下，列出操作每次最多返回 5000 个结果。 若要返回更小的结果集，请为要返回的结果页的大小提供非零值。 可以使用以下方法设置此值：

• ListBlobContainersOptions.setMaxResultsPerPage

本文演示的示例说明了如何在页面中返回结果。 要详细了解分页概念，请参阅使用适用于 Java 的 Azure SDK 进行分页。

使用前缀筛选结果

若要筛选容器列表，请为 prefix 参数指定一个字符串。 前缀字符串可以包含一个或多个字符。 然后，Azure 存储只返回其名称以该前缀开头的容器。 可以使用以下方法设置此值：

• ListBlobContainersOptions.setPrefix

包含容器元数据

若要在结果中包含容器元数据，请创建一个 BlobContainerListDetails 实例，并将 true 传递给以下方法：

• BlobContainerListDetails.setRetrieveMetadata

然后将 BlobContainerListDetails 对象传递给以下方法：

• ListBlobContainersOptions.setDetails

包含已删除的容器

若要在结果中包含软删除的容器，请创建一个 BlobContainerListDetails 实例，并将 true 传递给以下方法：

• BlobContainerListDetails.setRetrieveDeleted

然后将 BlobContainerListDetails 对象传递给以下方法：

• ListBlobContainersOptions.setDetails

代码示例

以下示例列出容器，并按指定的前缀筛选结果：

public void listContainers(BlobServiceClient blobServiceClient) {
    // Set a prefix to filter results based on a specified character or string
    ListBlobContainersOptions options = new ListBlobContainersOptions()
            .setPrefix("container-");

    System.out.println("List containers:");
    for (BlobContainerItem blobContainerItem : blobServiceClient.listBlobContainers(options, null)) {
        System.out.printf("Container name: %s%n", blobContainerItem.getName());
    }
}

还可以通过指定要返回的结果页的大小来返回更小的结果集：

public void listContainersWithPaging(BlobServiceClient blobServiceClient) {
    // Set a prefix to filter results and specify a page limit
    ListBlobContainersOptions options = new ListBlobContainersOptions()
            .setMaxResultsPerPage(2)  // Low number for demonstration purposes
            .setPrefix("container-");

    int i = 0;
    Iterable<PagedResponse<BlobContainerItem>> blobContainerPages = blobServiceClient
            .listBlobContainers(options, null).iterableByPage();
    for (PagedResponse<BlobContainerItem> page : blobContainerPages) {
        System.out.printf("Page %d%n", ++i);
        page.getElements().forEach(container -> {
            System.out.printf("Name: %s%n", container.getName());
        });
    }
}

资源

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

代码示例

• 查看本文中的代码示例 (GitHub)

REST API 操作

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

• 列出容器 (REST API)

客户端库资源

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

另请参阅

• 枚举 Blob 资源

相关内容

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