使用 .NET 列出 Blob 容器

项目
10/15/2024

通过代码列出 Azure 存储帐户中的容器时，可以指定多个选项来管理如何从 Azure 存储返回结果。本文介绍如何使用适用于 .NET 的 Azure 存储客户端库列出容器。

先决条件

Azure 订阅 - 创建试用订阅。
Azure 存储帐户 - 创建存储帐户
适用于你的操作系统的最新 .NET SDK。确保获取 SDK，而不是运行时。

设置你的环境

如果没有现有项目，请查看本部分，其中介绍如何设置项目来使用适用于 .NET 的 Azure Blob 存储客户端库。步骤包括安装包、添加 using 指令，以及创建已授权的客户端对象。有关详细信息，请参阅 Azure Blob 存储和 .NET 入门。

安装包

从项目目录中，使用 dotnet add package 命令安装 Azure Blob 存储和 Azure 标识客户端库的包。与 Azure 服务的无密码连接需要 Azure.Identity 包。

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.chinacloudapi.cn"),
        new DefaultAzureCredential());

    return client;
}

可以在 .NET 应用中为依赖项注入注册服务客户端。

还可以为特定容器或 Blob 创建客户端对象。要详细了解如何创建和管理客户端对象，请参阅创建和管理与数据资源交互的客户端对象。

授权

授权机制必须具有列出 Blob 容器所需的权限。若要使用 Microsoft Entra ID 进行授权（建议），需有 Azure RBAC 内置角色“存储 Blob 数据参与者”或更高级别的角色。有关详细信息，请参阅列出容器 (REST API) 的授权指南。

关于容器列出选项

通过代码列出容器时，可以指定选项来管理如何从 Azure 存储返回结果。可以指定要在每个结果集中返回的结果数，然后检索后续结果集。还可以按前缀筛选结果，并将容器元数据与结果一起返回。后续部分将介绍这些选项。

若要列出存储帐户中的容器，请调用以下方法之一：

这些方法返回 BlobContainerItem 对象的列表。容器按名称的字典顺序排序。

管理要返回的结果数

默认情况下，列表操作一次最多返回 5000 个结果，但你可以指定你所希望的每个列表操作返回的结果数。本文演示的示例说明了如何在页面中返回结果。要详细了解分页概念，请参阅使用适用于 .NET 的 Azure SDK 进行分页。

使用前缀筛选结果

若要筛选容器列表，请为 prefix 参数指定一个字符串。前缀字符串可以包含一个或多个字符。然后，Azure 存储只返回其名称以该前缀开头的容器。

包含容器元数据

若要在结果中包含容器元数据，请为 BlobContainerTraits 枚举指定 Metadata 值。 Azure 存储包含返回的每个容器的元数据，因此你不需要单独提取容器元数据。

包含已删除的容器

若要在结果中包含软删除的容器，请为 BlobContainerStates 枚举指定 Deleted 值。

代码示例：列出容器

以下示例以异步方式列出存储帐户中以指定的前缀开头的容器。该示例列出了以指定前缀开头的容器，并且每次对列表操作的调用均返回指定数量的结果。然后，它使用延续令牌获取下一段结果。该示例还会连同结果一起返回容器元数据。

async static Task ListContainers(BlobServiceClient blobServiceClient, 
                                string prefix, 
                                int? segmentSize)
{
    try
    {
        // Call the listing operation and enumerate the result segment.
        var resultSegment = 
            blobServiceClient.GetBlobContainersAsync(BlobContainerTraits.Metadata, prefix, default)
            .AsPages(default, segmentSize);

        await foreach (Azure.Page<BlobContainerItem> containerPage in resultSegment)
        {
            foreach (BlobContainerItem containerItem in containerPage.Values)
            {
                Console.WriteLine("Container name: {0}", containerItem.Name);
            }

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

资源

若要详细了解如何使用适用于 .NET 的 Azure Blob 存储客户端库来列出容器，请参阅以下资源。

REST API 操作

Azure SDK for .NET 包含基于 Azure REST API 而生成的库，允许你通过熟悉的 .NET 范例与 REST API 操作进行交互。用于列出容器的客户端库方法使用以下 REST API 操作：

列出容器 (REST API)

客户端库资源

另请参阅

枚举 Blob 资源

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

通过