使用 Go 列出 Blob

發行項
05/30/2024

本文說明如何使用適用於 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 個結果。若要傳回較小的結果集，請為 MaxResults ListBlobsFlatOptions 或 ListBlobsHierarchyOptions 中的字段提供非零值。

使用前置詞篩選結果

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

包含 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 操作

Azure SDK for Go 包含以 Azure REST API 為基礎的連結庫，可讓您透過熟悉的 Go 架構與 REST API 作業互動。用來列出 Blob 的用戶端程式庫方法會使用下列 REST API 作業：

列出 Blob (REST API)

共用方式為