使用 .NET 列出 blobList blobs with .NET

通过代码列出 Blob 时,可以指定多个选项来管理如何从 Azure 存储返回结果。When you list blobs from your code, you can specify a number of options to manage how results are returned from Azure Storage. 可以指定要在每个结果集中返回的结果数,然后检索后续结果集。You can specify the number of results to return in each set of results, and then retrieve the subsequent sets. 可以指定前缀以返回名称以该字符或字符串开头的 blob。You can specify a prefix to return blobs whose names begin with that character or string. 而且,可以在平面列表结构中列出 blob,也可以分层列出 blob。And you can list blobs in a flat listing structure, or hierarchically. 分层列表返回 blob,就像它们被组织到文件夹中一样。A hierarchical listing returns blobs as though they were organized into folders.

本文介绍如何使用适用于 .NET 的 Azure 存储客户端库列出 blob。This article shows how to list blobs using the Azure Storage client library for .NET.

了解 Blob 列出选项Understand blob listing options

若要列出存储帐户中的 Blob,请调用以下方法之一:To list the blobs in a storage account, call one of these methods:

管理要返回的结果数Manage how many results are returned

默认情况下,列表操作一次最多返回 5000 个结果,但你可以指定你所希望的每个列表操作返回的结果数。By default, a listing operation returns up to 5000 results at a time, but you can specify the number of results that you want each listing operation to return. 本文演示的示例说明了如何执行此操作。The examples presented in this article show you how to do this.

如果列表操作返回的 blob 超过 5000 个,或者可用的 blob 数超过指定的数量,Azure 存储会返回继续标记,并显示 blob 列表。If a listing operation returns more than 5000 blobs, or if the number of blobs that are available exceed the number that you specified, then Azure Storage returns a continuation token with the list of blobs. 继续标记是一个不透明值,可用于从 Azure 存储中检索下一组结果。A continuation token is an opaque value that you can use to retrieve the next set of results from Azure Storage.

在代码中检查继续标记的值,以确定它是否为 null。In your code, check the value of the continuation token to determine whether it is null. 如果继续标记为 null,则表示结果集是完整的。When the continuation token is null, then the set of results is complete. 如果继续标记不为 null,则再次调用列出操作,并传入继续标记以检索下一组结果,直到继续标记为 null。If the continuation token is not null, then call listing operation again, passing in the continuation token to retrieve the next set of results, until the continuation token is null.

使用前缀筛选结果Filter results with a prefix

若要筛选容器列表,请为 prefix 参数指定一个字符串。To filter the list of containers, specify a string for the prefix parameter. 前缀字符串可以包含一个或多个字符。The prefix string can include one or more characters. 然后,Azure 存储只返回其名称以该前缀开头的 Blob。Azure Storage then returns only the blobs whose names start with that prefix.

返回元数据Return metadata

可以返回包含结果的 blob 元数据。You can return blob metadata with the results.

  • 如果使用的是 .NET v12 SDK,请为 BlobTraits 枚举指定 Metadata 值。If you're using the .NET v12 SDK, specify the Metadata value for the BlobTraits enumeration.

  • 如果使用的是 .NET v11 SDK,请为 BlobListingDetails 枚举指定 Metadata 值。If you're using the .NET v11 SDK, specify the Metadata value for the BlobListingDetails enumeration. Azure 存储包含每个返回的 Blob 的元数据,因此在此上下文中,无需同时调用 FetchAttributes 方法之一即可检索 Blob 元数据。Azure Storage includes metadata with each blob returned, so you do not need to call one of the FetchAttributes methods in this context to retrieve the blob metadata.

平面列表与分层列表Flat listing versus hierarchical listing

Azure 存储中的 Blob 以平面范式进行组织,而不是以分层范式(类似于经典文件系统)进行组织。Blobs in Azure Storage are organized in a flat paradigm, rather than a hierarchical paradigm (like a classic file system). 但是,可以将 Blob 组织到虚拟目录中,以便模拟文件夹结构。However, you can organize blobs into virtual directories in order to mimic a folder structure. 虚拟目录构成 blob 名称的一部分,并由分隔符表示。A virtual directory forms part of the name of the blob and is indicated by the delimiter character.

若要将 blob 组织为虚拟目录,请在 blob 名称中使用分隔符。To organize blobs into virtual directories, use a delimiter character in the blob name. 默认分隔符是正斜杠 (/),但你可以指定任何字符作为分隔符。The default delimiter character is a forward slash (/), but you can specify any character as the delimiter.

如果使用分隔符来命名 Blob,可以选择以分层方式列出 Blob。If you name your blobs using a delimiter, then you can choose to list blobs hierarchically. 对于分层列出操作,Azure 存储将返回父对象下的所有虚拟目录和 Blob。For a hierarchical listing operation, Azure Storage returns any virtual directories and blobs beneath the parent object. 可以递归方式调用列出操作来遍历层次结构,类似于以编程方式遍历经典文件系统。You can call the listing operation recursively to traverse the hierarchy, similar to how you would traverse a classic file system programmatically.

使用平面列出Use a flat listing

默认情况下,列出操作在平面列表中返回 Blob。By default, a listing operation returns blobs in a flat listing. 在平面列表中,Blob 不会按虚拟目录进行组织。In a flat listing, blobs are not organized by virtual directory.

以下示例使用平面列表列出指定容器中的 Blob(其中指定了可选的段大小),并将 Blob 名称写入控制台窗口。The following example lists the blobs in the specified container using a flat listing, with an optional segment size specified, and writes the blob name to a console window.

如果在帐户上启用了分层命名空间功能,则目录不是虚拟目录,If you've enabled the hierarchical namespace feature on your account, directories are not virtual. 而是具体的独立对象。Instead, they are concrete, independent objects. 因此,目录在列表中显示为长度为零的 blob。Therefore, directories appear in the list as zero-length blobs.

private static void ListBlobsFlatListing(BlobContainerClient container, int? segmentSize)
{
    string continuationToken = null;

    try
    {
        // Call the listing operation and enumerate the result segment.
        // When the continuation token is empty, the last segment has been returned
        // and execution can exit the loop.
        do
        {
            var resultSegment = container.GetBlobs(prefix:"TestFolder")
                .AsPages(continuationToken, segmentSize);

            foreach (Azure.Page<BlobItem> blobPage in resultSegment)
            {
                foreach (BlobItem blobItem in blobPage.Values)
                {
                    Console.WriteLine("Blob name: {0}", blobItem.Name);
                }

                // Get the continuation token and loop until it is empty.
                continuationToken = blobPage.ContinuationToken;

                Console.WriteLine();
            }

        } while (continuationToken != "");

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

示例输出类似于:The sample output is similar to:

Blob name: FolderA/blob1.txt
Blob name: FolderA/blob2.txt
Blob name: FolderA/blob3.txt
Blob name: FolderA/FolderB/blob1.txt
Blob name: FolderA/FolderB/blob2.txt
Blob name: FolderA/FolderB/blob3.txt
Blob name: FolderA/FolderB/FolderC/blob1.txt
Blob name: FolderA/FolderB/FolderC/blob2.txt
Blob name: FolderA/FolderB/FolderC/blob3.txt

使用分层列表Use a hierarchical listing

以分层方式调用列出操作时,Azure 存储将返回位于层次结构第一级别的虚拟目录和 Blob。When you call a listing operation hierarchically, Azure Storage returns the virtual directories and blobs at the first level of the hierarchy. 将设置每个虚拟目录的 Prefix 属性,以便可以在递归调用中传递前缀来检索下一个目录。The Prefix property of each virtual directory is set so that you can pass the prefix in a recursive call to retrieve the next directory.

若要以分层方式列出 blob,请调用 BlobContainerClient.GetBlobsByHierarchyBlobContainerClient.GetBlobsByHierarchyAsync 方法。To list blobs hierarchically, call the BlobContainerClient.GetBlobsByHierarchy, or the BlobContainerClient.GetBlobsByHierarchyAsync method.

以下示例使用分层列表列出指定容器中的 Blob(其中指定了可选的段大小),并将 Blob 名称写入控制台窗口。The following example lists the blobs in the specified container using a hierarchical listing, with an optional segment size specified, and writes the blob name to the console window.

private static void ListBlobsHierarchicalListing(BlobContainerClient container, 
           string? prefix, int? segmentSize)
       {
           string continuationToken = null;
           
           try
           {
               // Call the listing operation and enumerate the result segment.
               // When the continuation token is empty, the last segment has been returned and
               // execution can exit the loop.
               do
               {
                   var resultSegment = container.GetBlobsByHierarchy(prefix:prefix, delimiter:"/")
                       .AsPages(continuationToken, segmentSize);

                   foreach (Azure.Page<BlobHierarchyItem> blobPage in resultSegment)
                   {
                       // A hierarchical listing may return both virtual directories and blobs.
                       foreach (BlobHierarchyItem blobhierarchyItem in blobPage.Values)
                       {
                           if (blobhierarchyItem.IsPrefix)
                           {
                               // Write out the prefix of the virtual directory.
                               Console.WriteLine("Virtual directory prefix: {0}", blobhierarchyItem.Prefix);

                               // Call recursively with the prefix to traverse the virtual directory.
                               ListBlobsHierarchicalListing(container, blobhierarchyItem.Prefix, null);
                           }
                           else
                           {
                               // Write out the name of the blob.
                               Console.WriteLine("Blob name: {0}", blobhierarchyItem.Blob.Name);
                           }
                       }

                       Console.WriteLine();

                       // Get the continuation token and loop until it is empty.
                       continuationToken = blobPage.ContinuationToken;
                   }


               } while (continuationToken != "");
           }
           catch (RequestFailedException e)
           {
               Console.WriteLine(e.Message);
               Console.ReadLine();
               throw;
           }
       }

示例输出类似于:The sample output is similar to:

Virtual directory prefix: FolderA/
Blob name: FolderA/blob1.txt
Blob name: FolderA/blob2.txt
Blob name: FolderA/blob3.txt

Virtual directory prefix: FolderA/FolderB/
Blob name: FolderA/FolderB/blob1.txt
Blob name: FolderA/FolderB/blob2.txt
Blob name: FolderA/FolderB/blob3.txt

Virtual directory prefix: FolderA/FolderB/FolderC/
Blob name: FolderA/FolderB/FolderC/blob1.txt
Blob name: FolderA/FolderB/FolderC/blob2.txt
Blob name: FolderA/FolderB/FolderC/blob3.txt

备注

在分层列出操作中无法列出 Blob 快照。Blob snapshots cannot be listed in a hierarchical listing operation.

使用 .NET 进行开发的资源Resources for development with .NET

下面的链接为使用适用于 .NET 的 Azure 存储客户端库的开发人员提供了有用的资源。The links below provide useful resources for developers using the Azure Storage client library for .NET.

Azure 存储通用 APIAzure Storage common APIs

Blob 存储 APIBlob storage APIs

.NET 工具.NET tools

后续步骤Next steps