Поделиться через

Получение списка больших двоичных объектов с помощью .NET

В этой статье показано, как получить список больших двоичных объектов с помощью клиентской библиотеки службы хранилища Azure для .NET.

Предварительные условия

Настройка среды

Если у вас нет существующего проекта, в этом разделе показано, как настроить проект для работы с клиентской библиотекой Хранилище BLOB-объектов Azure для .NET. Ниже приведены шаги по установке пакета, добавлению using директив и созданию авторизованного клиентского объекта. См. Начало работы с хранилищем BLOB-объектов Azure и .NET для получения дополнительных сведений.

Установка пакетов

В каталоге вашего проекта установите пакеты для клиентских библиотек Azure Blob Storage и Azure Identity с помощью команды dotnet add package. Пакет Azure.Identity необходим для подключений без пароля к службам Azure.

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

    return client;
}

Вы можете зарегистрировать клиент службы для внедрения зависимостей в приложении .NET.

Вы также можете создавать клиентские объекты для определенных контейнеров или блобов. Дополнительные сведения о создании клиентских объектов и управлении ими см. в статье "Создание клиентских объектов и управление ими", взаимодействующих с ресурсами данных.

Авторизация

Механизм авторизации должен иметь необходимые разрешения для получения списка объектов Blob. Для авторизации с помощью Microsoft Entra ID (рекомендуется) требуется встроенная роль Azure RBAC Storage Blob Data Reader или выше. Дополнительные сведения см. в руководстве по авторизации для List Blobs (REST API).

Сведения о параметрах перечисления BLOB-объектов

При перечислении объектов из кода, можно указать ряд параметров для управления способом возврата результатов из Azure Storage. Можно указать число возвращаемых результатов в каждом наборе результатов, а затем извлечь последующие наборы. Можно указать префикс для возврата больших двоичных объектов, имена которых начинаются с указанного символа или строки. Кроме того, можно создать неструктурированный или структурированный список больших двоичных объектов. В структурированном списке большие двоичные объекты представлены так, будто они организованы по папкам.

Чтобы получить список больших двоичных объектов в учетной записи хранения, вызовите один из следующих методов:

Управление количеством возвращаемых результатов

По умолчанию операция получения списка возвращает не более 5000 результатов за раз, но вы можете определить количество возвращаемых результатов для каждой операции получения списка. Примеры, представленные в этой статье, показывают, как возвращать результаты по страницам. Дополнительные сведения о принципах разбиения на страницы см. в статье Разбиение на страницы с помощью пакета SDK Azure для .NET.

Фильтрация результатов с помощью префикса

Чтобы отфильтровать список объектов, укажите строку для параметра prefix. Строка префикса может содержать один или несколько символов. Azure Storage возвращает только те блобы, имена которых начинаются с этого префикса.

Возврат метаданных

Метаданные BLOB можно вернуть с результатами, указав значение Метаданные для перечисления BlobTraits.

Плоский список и иерархический список

Объекты blob в службе хранилища Azure организованы по плоской структуре, а не по иерархической (как в классической файловой системе). Однако двоичные объекты можно организовать в виртуальные каталоги, чтобы имитировать структуру папок. Виртуальный каталог формирует часть имени объекта Blob и обозначается символом-разделителем.

Чтобы упорядочить большие двоичные объекты по виртуальным каталогам, используйте символ-разделитель в имени большого двоичного объекта. Символом-разделителем по умолчанию является косая черта (/), однако в качестве разделителя можно указать любой символ.

Если присвоить большим двоичным объектам имена с использованием разделителя, можно выбрать получение структурированного списка больших двоичных объектов. Для операции иерархического перечисления служба хранилища Azure возвращает все виртуальные директории и объекты BLOB, находящиеся под родительским объектом. Операцию перечисления можно вызвать рекурсивно для прохода по иерархии, подобно тому, как осуществляется программный обход классической файловой системы.

Использование неструктурированного списка

По умолчанию операция перечисления возвращает большие двоичные объекты в виде неструктурированного списка. В плоском списке BLOB не упорядочиваются по виртуальным каталогам.

В следующем примере перечисляются BLOB-объекты в указанном контейнере, используя плоский список с заданным необязательным размером сегмента, и выводятся имена этих объектов в окно консоли.

private static async Task ListBlobsFlatListing(BlobContainerClient blobContainerClient, 
                                               int? segmentSize)
{
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = blobContainerClient.GetBlobsAsync()
            .AsPages(default, segmentSize);

        // Enumerate the blobs returned for each page.
        await foreach (Page<BlobItem> blobPage in resultSegment)
        {
            foreach (BlobItem blobItem in blobPage.Values)
            {
                Console.WriteLine("Blob name: {0}", blobItem.Name);
            }

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

Выходные данные аналогичны следующим:

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

Примечание.

В приведенном примере выходных данных предполагается, что у вас есть учетная запись хранения с плоским пространством имен. Если вы включили функцию иерархического пространства имен для учетной записи хранения, каталоги не являются виртуальными. Это реальные независимые объекты. В результате каталоги отображаются в списке как большие двоичные объекты нулевой длины.

Альтернативный вариант перечисления при работе с иерархическим пространством имен см. в разделе "Список содержимого каталога" (Azure Data Lake Storage).

Использование иерархического списка

При вызове операции иерархического перечисления служба хранилища Azure возвращает виртуальные каталоги и большие двоичные объекты на первом уровне иерархии.

Чтобы перечислить объекты blob иерархически, вызовите метод BlobContainerClient.GetBlobsByHierarchy или BlobContainerClient.GetBlobsByHierarchyAsync.

В следующем примере выводится иерархический список больших двоичных объектов в указанном контейнере с необязательным размером сегмента, а имя большого двоичного объекта отображается в окне консоли.

private static async Task ListBlobsHierarchicalListing(BlobContainerClient container, 
                                                       string prefix, 
                                                       int? segmentSize)
{
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = container.GetBlobsByHierarchyAsync(prefix:prefix, delimiter:"/")
            .AsPages(default, segmentSize);

        // Enumerate the blobs returned for each page.
        await foreach (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.
                    await ListBlobsHierarchicalListing(container, blobhierarchyItem.Prefix, null);
                }
                else
                {
                    // Write out the name of the blob.
                    Console.WriteLine("Blob name: {0}", blobhierarchyItem.Blob.Name);
                }
            }

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

Выходные данные аналогичны следующим:

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 не могут быть перечислены при выполнении операции иерархического перечисления.

Список версий или снимков блоков

Чтобы перечислить версии блобов или их моментальные снимки, укажите параметр BlobStates с полем Version или Snapshot. Версии и моментальные снимки перечислены в порядке от самых старых к самым новым.

В следующем примере кода показано, как получить список версий BLOB-объектов.

private static void ListBlobVersions(BlobContainerClient blobContainerClient, 
                                           string blobName)
{
    try
    {
        // Call the listing operation, specifying that blob versions are returned.
        // Use the blob name as the prefix. 
        var blobVersions = blobContainerClient.GetBlobs
            (BlobTraits.None, BlobStates.Version, prefix: blobName)
            .OrderByDescending(version => version.VersionId).Where(blob => blob.Name == blobName);

        // Construct the URI for each blob version.
        foreach (var version in blobVersions)
        {
            BlobUriBuilder blobUriBuilder = new BlobUriBuilder(blobContainerClient.Uri)
            {
                BlobName = version.Name,
                VersionId = version.VersionId
            };

            if ((bool)version.IsLatestVersion.GetValueOrDefault())
            {
                Console.WriteLine("Current version: {0}", blobUriBuilder);
            }
            else
            {
                Console.WriteLine("Previous version: {0}", blobUriBuilder);
            }
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

Ресурсы

Дополнительные сведения о том, как перечислять BLOB-объекты с использованием клиентской библиотеки Azure Blob Storage для .NET, см. в следующих ресурсах.

Операции REST API

Пакет SDK Azure для .NET содержит библиотеки, которые создаются на основе REST API Azure, что позволяет взаимодействовать с операциями REST API через знакомые парадигмы .NET. Методы клиентской библиотеки для перечисления объектов BLOB используют следующую операцию REST API:

Ресурсы клиентской библиотеки

См. также

Связанный контент

  • Эта статья является частью руководства разработчика хранилища BLOB-объектов для .NET. Дополнительные сведения см. в полном списке статей руководства разработчика по созданию приложения .NET.