使用 Go 列出 blob

项目
08/27/2024

先决条件

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 元数据或其他信息

要在结果中包含 Blob 元数据，请将 Metadata 字段设置为 true 作为 ListBlobsInclude 的一部分。 Microsoft 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)

通过