使用 Java 列出 Blob

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

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

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

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

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

添加以下 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 时，可以指定选项来管理如何从 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)

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

• 列出 Blob (REST API)

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

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

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