使用 Java 列出 Blob

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

先决条件

• 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 数据读取者”或更高级别的角色。 有关详细信息，请参阅列出 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>");

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

了解 blob 列出选项

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

若要列出存储帐户中的 Blob，请调用以下方法之一：

• listBlobs
• listBlobsByHierarchy

管理要返回的结果数

默认情况下，列表操作一次最多返回 5000 个结果，但你可以指定你所希望的每个列表操作返回的结果数。 本文演示的示例说明了如何在页面中返回结果。 要详细了解分页概念，请参阅使用适用于 Java 的 Azure SDK 进行分页。

使用前缀筛选结果

要筛选 Blob 列表，请将字符串作为 prefix 参数传递给 ListBlobsOptions.setPrefix（字符串前缀）。 前缀字符串可以包含一个或多个字符。 然后，Azure 存储只返回其名称以该前缀开头的 Blob。

平面列表与分层列表

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

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

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

使用平面列出

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

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

public void listBlobsFlat(BlobContainerClient blobContainerClient) {
    System.out.println("List blobs flat:");

    blobContainerClient.listBlobs()
            .forEach(blob -> System.out.printf("Name: %s%n", blob.getName()));
}

示例输出类似于：

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

还可以指定用于筛选列表结果或显示其他信息的选项。 以下示例列出了具有指定前缀的 Blob，还列出了已删除的 Blob：

public void listBlobsFlatWithOptions(BlobContainerClient blobContainerClient) {
    ListBlobsOptions options = new ListBlobsOptions()
            .setMaxResultsPerPage(2) // Low number for demonstration purposes
            .setDetails(new BlobListDetails()
                    .setRetrieveDeletedBlobs(true));

    System.out.println("List blobs flat:");

    int i = 0;
    Iterable<PagedResponse<BlobItem>> blobPages = blobContainerClient.listBlobs(options, null).iterableByPage();
    for (PagedResponse<BlobItem> page : blobPages) {
        System.out.printf("Page %d%n", ++i);
        page.getElements().forEach(blob -> {
            System.out.printf("Name: %s, Is deleted? %b%n",
                    blob.getName(),
                    blob.isDeleted());
        });
    }
}

示例输出类似于：

List blobs flat:
Page 1
Name: file4.txt, Is deleted? false
Name: file5-deleted.txt, Is deleted? true
Page 2
Name: folderA/file1.txt, Is deleted? false
Name: folderA/file2.txt, Is deleted? false
Page 3
Name: folderA/folderB/file3.txt, Is deleted? false

使用分层列表

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

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

• listBlobsByHierarchy

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

public void listBlobsHierarchicalListing(BlobContainerClient blobContainerClient, String prefix/* ="" */) {
    String delimiter = "/";
    ListBlobsOptions options = new ListBlobsOptions()
            .setPrefix(prefix);

    blobContainerClient.listBlobsByHierarchy(delimiter, options, null)
            .forEach(blob -> {
                if (blob.isPrefix()) {
                    System.out.printf("Virtual directory prefix: %s%n", delimiter + blob.getName());
                    listBlobsHierarchicalListing(blobContainerClient, blob.getName());
                } else {
                    System.out.printf("Blob name: %s%n", blob.getName());
                }
            });
}

示例输出类似于：

List blobs hierarchical:
Blob name: file4.txt
Virtual directory prefix: /folderA/
Blob name: folderA/file1.txt
Blob name: folderA/file2.txt
Virtual directory prefix: /folderA/folderB/
Blob name: folderA/folderB/file3.txt

资源

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

代码示例

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

REST API 操作

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

• 列出 Blob (REST API)

客户端库资源

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

另请参阅

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

相关内容

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