使用 Java 列出 Blob

• .NET
• Java
• JavaScript
• TypeScript
• Python
• Go

本文說明如何使用適用於 Java 的 Azure 儲存體用戶端程式庫列出 Blob。

必要條件

• Azure 訂用帳戶 - 建立免費帳戶
• Azure 儲存體帳戶 - 建立儲存體帳戶
• JAVA 開發套件 (JDK) 第 8 版或更新版本 (建議使用第 17 版以獲得最佳體驗)
• 在此範例中，Apache Maven 用於專案管理

設定您的環境

如果沒有現有的專案，本章節會說明如何設定專案以使用適用於 JAVA 的 Azure Blob 儲存體用戶端程式庫。 如需詳細資訊，請參閱開始使用 Azure Blob 儲存體和 JAVA (部分機器翻譯)。

若要使用本文中的程式碼範例，請遵循下列步驟來設定您的專案。

注意

本文使用 Maven 建置工具來建置和執行範例程式碼。 Gradle 等其他建置工具也能與適用於 Java 的 Azure SDK 搭配運作。

安裝套件

在文字編輯器中開啟 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.windows.net/")
        .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 個結果，但您可以指定要讓每個列出作業傳回的結果數目。 本文中顯示的範例會說明如何在頁面中傳回結果。 若要深入了解分頁概念，請參閱使用 Azure SDK for Java 進行分頁。

使用前置詞篩選結果

若要篩選 Blob 清單，請將字串當作 prefix 參數傳遞至 ListBlobsOptions.setPrefix(String prefix)。 前置詞字串可包含一或多個字元。 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

注意

顯示的範例輸出假設您具有採用一般命名空間的儲存體帳戶。 如果您已為儲存體帳戶啟用階層命名空間功能，目錄就不是虛擬的。 此時，目錄會是具體、獨立的物件。 因此，目錄會以零長度 Blob 的形式出現在清單中。

如需使用階層命名空間時的替代清單選項，請參閱列出目錄內容 (Azure Data Lake Storage)。

使用階層式清單

當以階層方式呼叫清單作業時，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

注意

Blob 快照集不能列在階層式清單作業中。

資源

若要深入了解如何使用適用於 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 應用程式的完整開發人員指南文章清單。