使用 Go 列出 Blob

• .NET
• Java
• JavaScript
• Python
• Go

本文說明如何使用適用於 Go 的 Azure 儲存體用戶端模組來列出 Blob。

必要條件

• Azure 訂用帳戶 - 建立免費帳戶
• Azure 儲存體帳戶 - 建立儲存體帳戶
• Go 1.18+

設定您的環境

如果沒有現有的專案，本節說明如何設定專案以使用適用於 Go 的 Azure Blob 儲存體用戶端模組。 這些步驟包括模組安裝、新增 import 路徑，以及建立已授權的用戶端物件。 如需詳細資訊，請參閱開始使用 Azure Blob 儲存體和 Go。

安裝模組

使用下列命令安裝 azblob 模組：

go get github.com/Azure/azure-sdk-for-go/sdk/storage/azblob

若要使用 Microsoft Entra ID 進行驗證 (建議使用)，請使用下列命令安裝 azidentity 模組：

go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

新增匯入路徑

在您的程式碼檔案中，新增下列匯入路徑：

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
)

這些匯入路徑代表開始使用所需的最小值。 本文中的某些程式碼範例可能需要其他匯入路徑。 如需特定詳細資料和範例使用方式，請參閱程式碼範例。

建立用戶端物件

若要將應用程式連線至 Blob 記憶體，請使用 azblob.NewClient 建立用戶端物件。 下列範例示範如何使用 DefaultAzureCredential 來建立用戶端物件以進行授權：

func getServiceClientTokenCredential(accountURL string) *azblob.Client {
    // Create a new service client with token credential
    credential, err := azidentity.NewDefaultAzureCredential(nil)
    handleError(err)

    client, err := azblob.NewClient(accountURL, credential, nil)
    handleError(err)

    return client
}

授權

授權機制必須具有上傳 Blob 的必要權限。 如需使用 Microsoft Entra ID 授權 (建議使用)，您需要 Azure RBAC 內建角色儲存體 Blob 資料讀者或更高的權限。 若要深入了解，請參閱列出 Blob (REST API) 的授權指導。

關於 Blob 清單選項

從程式碼列出 Blob 時，您可以指定許多選項來管理從 Azure 儲存體傳回結果的方式。 您可指定要在每一組結果中傳回的結果數目，然後擷取後續集合。 您可指定前置詞，以傳回名稱開頭為該字元或字串的 Blob。 也可以使用簡單列表結構或以階層方列出 Blob。 階層式清單會傳回 Blob，就好像這些 Blob 已組織成資料夾一樣。

若要使用簡單列表列出容器中的 Blob，請呼叫下列方法：

• NewListBlobsFlatPager

若要使用階層式清單列出容器中的 Blob，請從容器用戶端物件呼叫下列方法：

• NewListBlobsHierarchyPager

管理傳回的結果數目

根據預設，清單作業一次最多會傳回 5000 個結果。 若要傳回較小的結果集，請為 ListBlobsFlatOptions 或 ListBlobsHierarchyOptions 中的 MaxResults 欄位提供非零值。

使用前置詞篩選結果

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

包含 Blob 中繼資料或其他資訊

若要包含具有結果的容器中繼資料，請將 Metadata 欄位設定為 true，以作為 ListBlobsInclude 的一部分。 Azure 儲存體包含中繼資料與每個傳回的 Blob，因此您無須個別擷取 Blob 中繼資料。

如需在結果中包含快照集、版本、Blob 索引標籤和其他資訊的其他選項，請參閱 ListBlobsInclude。

簡單列表與階層式清單

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

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

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

注意

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

使用簡單列表

根據預設，清單作業會以簡單列表傳回 Blob。 在簡單列表中，Blob 不會透過虛擬目錄進行編排。

下列範例使用一般清單列出指定容器中的 blob。 如果 Blob 快照集和 Blob 版本存在，則此範例包括：

func listBlobsFlat(client *azblob.Client, containerName string) {
    // List the blobs in the container
    pager := client.NewListBlobsFlatPager(containerName, &azblob.ListBlobsFlatOptions{
        Include: azblob.ListBlobsInclude{Snapshots: true, Versions: true},
    })

    fmt.Println("List blobs flat:")
    for pager.More() {
        resp, err := pager.NextPage(context.TODO())
        handleError(err)

        for _, blob := range resp.Segment.BlobItems {
            fmt.Println(*blob.Name)
        }
    }
}

範例輸出類似於：

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

下列範例會列出容器中以特定前置詞開頭的 Blob：

func listBlobsFlatOptions(client *azblob.Client, containerName string, prefix string) {
    // List the blobs in the container with a prefix
    pager := client.NewListBlobsFlatPager(containerName, &azblob.ListBlobsFlatOptions{
        Prefix: to.Ptr(prefix),
    })

    fmt.Println("List blobs with prefix:")
    for pager.More() {
        resp, err := pager.NextPage(context.TODO())
        handleError(err)

        for _, blob := range resp.Segment.BlobItems {
            fmt.Println(*blob.Name)
        }
    }
}

傳遞「sample」前置詞字串時，輸出類似於：

List blobs with prefix:
sample-blob1.txt
sample-blob2.txt
sample-blob3.txt

注意

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

如需使用階層命名空間時的替代清單選項，請參閱 NewListPathsPager。

使用階層式清單

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

若要以階層方式列出 Blob，請使用下列方法：

• NewListBlobsHierarchyPager

下列範例使用階層式清單列出所指定容器中的 Blob。 在此範例中，前置詞參數一開始會設定為空字串，以列出容器中的所有 Blob。 然後，此範例會以遞歸方式呼叫清單作業，以周遊虛擬目錄階層和列表 Blob。

func listBlobsHierarchy(client *azblob.Client, containerName string, prefix string) {
    // Reference the container as a client object
    containerClient := client.ServiceClient().NewContainerClient(containerName)

    pager := containerClient.NewListBlobsHierarchyPager("/", &container.ListBlobsHierarchyOptions{
        Prefix:     to.Ptr(prefix),
        MaxResults: to.Ptr(int32(1)), // MaxResults set to 1 for demonstration purposes
    })

    for pager.More() {
        resp, err := pager.NextPage(context.TODO())
        handleError(err)

        if resp.Segment.BlobPrefixes != nil {
            for _, prefix := range resp.Segment.BlobPrefixes {
                fmt.Println("Virtual directory prefix:", *prefix.Name)

                // Recursively list blobs in the prefix
                listBlobsHierarchy(client, containerName, *prefix.Name)
            }
        }

        for _, blob := range resp.Segment.BlobItems {
            fmt.Println("Blob:", *blob.Name)
        }
    }
}

範例輸出類似於：

Virtual directory prefix: folderA/
Blob: folderA/file1.txt
Blob: folderA/file2.txt
Blob: folderA/file3.txt
Virtual directory prefix: folderA/folderB/
Blob: folderA/folderB/file1.txt
Blob: folderA/folderB/file2.txt
Blob: folderA/folderB/file3.txt

注意

本指南中的程式碼範例旨在協助您開始使用 Azure Blob 儲存體和 Go。 您應該修改錯誤處理和 Context 值，以符合您應用程式的需求。

資源

若要深入了解如何使用適用於 Go 的 Azure Blob 儲存體用戶端模組來列出 Blob，請參閱下列資源。

程式碼範例

• 檢視本文中的程式碼範例 (GitHub)

REST API 操作

適用於 Go 的 Azure SDK 包含建置在 Azure REST API 之上的程式庫，可讓您透過熟悉的 Go 典範與 REST API 作業進行互動。 用來列出 Blob 的用戶端程式庫方法會使用下列 REST API 作業：

• 列出 Blob (REST API)

用戶端模組資源

• 用戶端模組參考文件
• 用戶端模組原始程式碼
• 套件 (pkg.go.dev)

另請參閱

• 列舉 Blob 資源
• Blob 版本設定

相關內容

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