使用 Go 列出 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 内置角色 Storage Blob Data Reader 或更高级别的角色。若要了解详细信息，请参阅有关列出 Blob 对象（REST API）的授权指南。

关于 Blob 列表选项

在代码中列出 Blob 时，可以指定多个选项来控制 Azure 存储返回结果的方式。可以指定要在每个结果集中返回的结果数，然后检索后续结果集。可以指定一个前缀，以返回名称以该字符或字符串开头的 Blob。你可以按平面列表结构或分层结构列出 Blob。分层列表返回 Blob 对象，仿佛它们是按文件夹方式组织的一样。

要使用平面列表列出容器中的blob，请调用以下方法：

NewListBlobsFlatPager

要通过层级列表列出容器中的blob，请从容器客户端对象调用以下方法：

NewListBlobsHierarchyPager

设置返回结果的数量

默认情况下，列出操作每次最多返回 5000 个结果。要返回较小的结果集，请为 MaxResults 或 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 值以满足应用程序的需求。

以 Apache Arrow 格式列出 Blob（预览）

Important

Apache Arrow格式的blob列表目前处于预览阶段。此场景需要 Azure 存储客户端模块的测试版（预览版）用于 Go 运行（例如 github.com/Azure/azure-sdk-for-go/sdk/storage/azblobv1.8.1-beta.1 或更高版本的预览版）。预览版功能在没有服务级别协议的情况下提供，不建议用于生产工作负荷。有些功能可能不被支持，或者功能受限。有关详细信息，请参阅适用于 Azure 预览版的补充使用条款。

该功能基于现有 List Blobs API。它没有使用默认的 XML，而是使用紧凑的列状 Apache Arrow 格式作为线路上的响应格式。你可以通过在容器列表调用中设置一个选项来启用它。 Go SDK 在幕后解码了 Apache Arrow，但返回的数值依然相同 BlobItem 。这种方法在枚举大型容器时提高了列表吞吐量并减少客户端 CPU。它保留了应用程序所依赖的响应合同。

Warning

在启用层级命名空间（Azure Data Lake Storage）的存储账户上，不支持Apache Arrow格式的blob列表。

要请求Apache Arrow格式的结果，请将ListBlobsFlatOptions字段设置为ResponseFormatStorageResponseFormatArrow，然后将选项传递给NewListBlobsFlatPager。使用 Apache Arrow 输出时，你还可以设置 StartFrom 和 EndBefore 字段来控制返回路径的范围。

以下示例列出容器中的blobs，并请求以Apache Arrow格式获取结果：

import (
    "context"

    "github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/container"
)

pager := client.NewListBlobsFlatPager("sample-container", &azblob.ListBlobsFlatOptions{
    Prefix:         to.Ptr("folderA/"),
    ResponseFormat: container.StorageResponseFormatArrow,
})

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

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

资源

若要详细了解如何使用适用于 Go 的 Azure Blob 存储客户端模块列出 Blob，请参阅以下资源。

代码示例

查看本文中的代码示例 (GitHub)

REST API 操作

Azure SDK for Go 包含基于 Azure REST API 构建的库。通过使用这些库，你可以通过熟悉的 Go 范式与 REST API 操作交互。用于列出 blob 的客户端库方法使用以下 REST API 操作：

列出 Blob (REST API)

客户端模块资源

另请参阅

本文是适用于 Go 的 Blob 存储开发人员指南的一部分。若要了解详细信息，请参阅构建 Go 应用中的完整开发人员指南文章列表。

Last updated on 2026-09-04