使用 .NET 列出 Blob

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

必要條件

Azure 訂用帳戶 - 建立免費帳戶
Azure 儲存體帳戶 - 建立儲存體帳戶
適用於您作業系統的最新 .NET SDK。請務必下載 SDK，而不是執行階段。

設定您的環境

如果沒有現有的專案，本章節會說明如何設定專案以使用適用於 .NET 的 Azure Blob 儲存體用戶端程式庫。這些步驟包括封裝安裝、新增 using 指示詞，以及建立已授權的用戶端物件。如需詳細資訊，請參閱開始使用 Azure Blob 儲存體和 .NET。

安裝套件

從您的專案目錄中，使用 dotnet add package 命令安裝 Azure Blob 儲存體和 Azure 身分識別客戶端程式庫的套件。需要 Azure.Identity 套件才能對 Azure 服務進行無密碼連線。

dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity

新增 `using` 指示詞

將這些 using 指示詞新增至程式碼檔案頂端：

using Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;

本文中的某些程式碼範例可能需要其他using指示詞。

建立用戶端物件

若要將應用程式連線至 Blob 儲存體，請建立 BlobServiceClient類別的執行個體。下列範例示範如何使用 DefaultAzureCredential 來建立用戶端物件以進行授權：

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

您可以在 .NET 應用程式中註冊相依性插入的服務用戶端。

您也可以為特定容器或 Blob 建立客戶端物件。若要進一步了解如何建立及管理與資料資源互動的用戶端物件，請參閱建立及管理與資料資源互動的用戶端物件。

授權

授權機制必須具有列出 Blob 的必要權限。若要使用 Microsoft Entra ID 進行授權（建議），您需要 Azure RBAC 內建角色 Storage Blob Data Reader 或更高層級的角色。若要深入了解，請參閱列出 Blob (REST API) 的授權指引。

關於 Blob 清單選項

當從程式碼列出 Blob 時，即可指定數個選項來管理從 Azure 儲存體傳回結果的方式。您可指定要在每一組結果中傳回的結果數目，然後擷取後續集合。您可以指定前置詞，以傳回名稱以該字元或字串開頭的 Blob。您可以用簡單清單結構列出 Blob，或以階層方式列出 Blob。階層式清單會透過將 Blob 組織成資料夾的方式傳回 Blob。

若要列出儲存體帳戶中的 Blob 物件，請呼叫下列其中一個方法：

管理傳回的結果數目

根據預設，列出作業一次最多會傳回 5000 個結果，但您可以指定要讓每個列出作業傳回的結果數目。本文中顯示的範例會說明如何在頁面中傳回結果。若要深入了解分頁概念，請參閱使用 Azure SDK for .NET 進行分頁。

使用前置詞篩選結果

若要篩選 Blob 清單，請指定 prefix 參數的字串。前置詞字串可包含一或多個字元。 Azure 儲存體接著只會傳回名稱開頭為該前置詞的 Blob。

傳回中繼資料

您可以為 BlobTraits 列舉指定中繼資料值，以在結果中一併傳回 Blob 中繼資料。

簡單列表與階層式清單

Azure 儲存體中的 Blob 是以簡單架構進行組織，而不是階層式架構 (例如傳統檔案系統)。不過，您可將 Blob 組織成「虛擬目錄」，以便模擬資料夾結構。虛擬目錄會形成 Blob 名稱的一部分，並以分隔符號表示。

若要將 Blob 組織成虛擬目錄，請在 Blob 名稱中使用分隔符號。預設的分隔符號是正斜線 (/)，但可指定任何字元作為分隔符號。

如果使用分隔符號來命名 Blob，則可選擇以階層方式列出 Blob。對於階層式清單作業，Azure 儲存體會傳回父物件下方的任何虛擬目錄和 Blob。您可遞迴呼叫清單作業來周遊階層，類似於以程式設計方式周遊傳統檔案系統的方式。

使用簡單列表

根據預設，清單作業會以簡單清單傳回 Blob。在簡單清單中，Blob 不會依虛擬目錄加以組織。

以下範例使用扁平列表（flat listing）列出指定容器中的 blob，並指定可選的區段大小，並將 blob 名稱寫入主控台視窗。

private static async Task ListBlobsFlatListing(BlobContainerClient blobContainerClient, 
                                               int? segmentSize)
{
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = blobContainerClient.GetBlobsAsync()
            .AsPages(default, segmentSize);

        // Enumerate the blobs returned for each page.
        await foreach (Page<BlobItem> blobPage in resultSegment)
        {
            foreach (BlobItem blobItem in blobPage.Values)
            {
                Console.WriteLine("Blob name: {0}", blobItem.Name);
            }

            Console.WriteLine();
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

範例輸出類似於：

Blob name: FolderA/blob1.txt
Blob name: FolderA/blob2.txt
Blob name: FolderA/blob3.txt
Blob name: FolderA/FolderB/blob1.txt
Blob name: FolderA/FolderB/blob2.txt
Blob name: FolderA/FolderB/blob3.txt
Blob name: FolderA/FolderB/FolderC/blob1.txt
Blob name: FolderA/FolderB/FolderC/blob2.txt
Blob name: FolderA/FolderB/FolderC/blob3.txt

注意

所示的範例輸出是假設您有一個採用扁平命名空間的儲存體帳戶。如果你啟用了儲存帳號的階層命名空間功能，目錄就不是虛擬的。相反地，它們是具體且獨立的物件。因此，目錄會以零長度 Blob 的形式出現在清單中。

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

使用階層式清單

當以階層方式呼叫清單作業時，Azure 儲存體會傳回階層第一層級的虛擬目錄和 Blob。

若要階層式列出 blob，請呼叫 BlobContainerClient.GetBlobsByHierarchy 或 BlobContainerClient.GetBlobsByHierarchyAsync 方法。

以下範例透過階層式列舉（並指定可選區段大小）列出指定容器中的 blob，並將 blob 名稱寫入主控台視窗。

private static async Task ListBlobsHierarchicalListing(BlobContainerClient container, 
                                                       string prefix, 
                                                       int? segmentSize)
{
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = container.GetBlobsByHierarchyAsync(prefix:prefix, delimiter:"/")
            .AsPages(default, segmentSize);

        // Enumerate the blobs returned for each page.
        await foreach (Page<BlobHierarchyItem> blobPage in resultSegment)
        {
            // A hierarchical listing may return both virtual directories and blobs.
            foreach (BlobHierarchyItem blobhierarchyItem in blobPage.Values)
            {
                if (blobhierarchyItem.IsPrefix)
                {
                    // Write out the prefix of the virtual directory.
                    Console.WriteLine("Virtual directory prefix: {0}", blobhierarchyItem.Prefix);

                    // Call recursively with the prefix to traverse the virtual directory.
                    await ListBlobsHierarchicalListing(container, blobhierarchyItem.Prefix, null);
                }
                else
                {
                    // Write out the name of the blob.
                    Console.WriteLine("Blob name: {0}", blobhierarchyItem.Blob.Name);
                }
            }

            Console.WriteLine();
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

範例輸出類似於：

Virtual directory prefix: FolderA/
Blob name: FolderA/blob1.txt
Blob name: FolderA/blob2.txt
Blob name: FolderA/blob3.txt

Virtual directory prefix: FolderA/FolderB/
Blob name: FolderA/FolderB/blob1.txt
Blob name: FolderA/FolderB/blob2.txt
Blob name: FolderA/FolderB/blob3.txt

Virtual directory prefix: FolderA/FolderB/FolderC/
Blob name: FolderA/FolderB/FolderC/blob1.txt
Blob name: FolderA/FolderB/FolderC/blob2.txt
Blob name: FolderA/FolderB/FolderC/blob3.txt

注意

Blob 快照無法在階層式列出作業中列出。

列出 Blob 版本或快照

若要列出 Blob 版本或快照集，請指定 BlobStates 參數搭配 Version 或 Snapshot 欄位。該服務會回傳從最舊到最新的版本和快照。

下列程式碼範例示範如何列出 Blob 版本。

private static void ListBlobVersions(BlobContainerClient blobContainerClient, 
                                           string blobName)
{
    try
    {
        // Call the listing operation, specifying that blob versions are returned.
        // Use the blob name as the prefix. 
        var blobVersions = blobContainerClient.GetBlobs
            (BlobTraits.None, BlobStates.Version, prefix: blobName)
            .OrderByDescending(version => version.VersionId).Where(blob => blob.Name == blobName);

        // Construct the URI for each blob version.
        foreach (var version in blobVersions)
        {
            BlobUriBuilder blobUriBuilder = new BlobUriBuilder(blobContainerClient.Uri)
            {
                BlobName = version.Name,
                VersionId = version.VersionId
            };

            if ((bool)version.IsLatestVersion.GetValueOrDefault())
            {
                Console.WriteLine("Current version: {0}", blobUriBuilder);
            }
            else
            {
                Console.WriteLine("Previous version: {0}", blobUriBuilder);
            }
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

以 Apache Arrow 格式列出 Blob (預覽)

Important

Apache Arrow 格式的 blob 列表目前處於預覽階段。此情境需要 Azure Blob 儲存體用戶端函式庫的 .NET 測試版（預覽Azure.Storage.Blobs版，例如 12.30.0-beta.1 或更新版本）。預覽功能是在沒有服務等級合約的情況下提供的，不建議用於生產工作負載。有些功能可能不支援，或功能有限。欲了解更多資訊，請參閱 Microsoft Azure 預覽版補充使用條款。

此功能建立在現有 List Blobs API 之上。它不是使用預設的 XML，而是使用精簡的欄式 Apache Arrow 格式作為線上傳輸的回應格式。你可以在容器列表呼叫中設定一個選項來啟用它。 .NET SDK 在幕後解碼 Apache Arrow，仍然回傳相同的BlobItem物件。此方法提升列表吞吐量，並在列舉大型容器時減少客戶端 CPU。它保留了應用程式所依賴的回應合約。

Warning

在已啟用階層式命名空間（Azure Data Lake Storage）的儲存體帳戶上，不支援以 Apache Arrow 格式列出 Blob。

要請求 Apache 箭頭格式的結果，請將 GetBlobsOptions 的 ResponseFormat 屬性設為 StorageResponseFormat.Arrow，然後將選項傳給接受 GetBlobsOptions的 BlobContainerClient.GetBlobs 覆載。使用 Apache Arrow 輸出時，你也可以設定 StartFrom 和 EndBefore 屬性來控制回傳路徑的範圍。

以下範例列出容器中的 blob，並以 Apache Arrow 格式請求結果：

using Azure.Storage;
using Azure.Storage.Blobs.Models;

GetBlobsOptions options = new GetBlobsOptions
{
    Prefix = "FolderA/",
    ResponseFormat = StorageResponseFormat.Arrow
};

foreach (BlobItem blobItem in containerClient.GetBlobs(options))
{
    Console.WriteLine("Blob name: " + blobItem.Name);
}

資源

想了解如何使用 Azure Blob 儲存體用戶端函式庫（針對 .NET）列出 blob，請參閱以下資源。

REST API 操作

Azure SDK for .NET 包含建立在 Azure REST API 之上的函式庫。透過使用這些函式庫，你可以透過熟悉的 .NET 範式與 REST API 操作互動。用來列出 Blob 的用戶端程式庫方法會使用下列 REST API 作業：

列出 Blob 清單 (REST API)

用戶端程式庫資源

另請參閱

本文是適用於 .NET 的 Blob 儲存體開發人員指南的一部分。若要深入了解，請參閱位於建置 .NET 應用程式的開發人員指南文章完整清單。

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-09-02