Вывод списка BLOB-объектов с помощью Java

В этой статье показано, как перечислить BLOB-объекты с помощью клиентской библиотеки служба хранилища Azure client library for Java.

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

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

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

Чтобы работать с примерами кода в этой статье, выполните следующие действия, чтобы настроить проект.

Примечание.

В этой статье используется средство сборки Maven для создания и запуска примера кода. Для работы с пакетами SDK Azure для Java есть и другие средства сборки, например Gradle.

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

Откройте файл pom.xml в текстовом редакторе. Установите пакеты, включив файл BOM или включив прямую зависимость.

Добавление инструкций импорта

Добавьте следующие операторы import :

import com.azure.core.http.rest.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;

Авторизация

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

Создание клиентского объекта

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

В следующем примере используется BLOBServiceClientBuilder для создания BlobServiceClient объекта с помощью DefaultAzureCredentialи показано, как создать клиенты контейнеров и BLOB-объектов при необходимости:

// Azure SDK client builders accept the credential as a parameter
// TODO: Replace <storage-account-name> with your actual storage account name
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .endpoint("https://<storage-account-name>.blob.core.windows.net/")
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

// If needed, you can create a BlobContainerClient object from the BlobServiceClient
BlobContainerClient containerClient = blobServiceClient
        .getBlobContainerClient("<container-name>");

// If needed, you can create a BlobClient object from the BlobContainerClient
BlobClient blobClient = containerClient
        .getBlobClient("<blob-name>");

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

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

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

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

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

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

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

Чтобы отфильтровать список BLOB-объектов, передайте строку в качестве параметра prefix для ListBlobsOptions.setPrefix(String prefix). Строка префикса может содержать один или несколько символов. служба хранилища Azure возвращает только те объекты BLOB, имена которых начинаются с этого префикса.

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

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

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

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

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

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

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

public void listBlobsFlat(BlobContainerClient blobContainerClient) {
    System.out.println("List blobs flat:");

    blobContainerClient.listBlobs()
            .forEach(blob -> System.out.printf("Name: %s%n", blob.getName()));
}

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

List blobs flat:
Name: file4.txt
Name: folderA/file1.txt
Name: folderA/file2.txt
Name: folderA/folderB/file3.txt

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

public void listBlobsFlatWithOptions(BlobContainerClient blobContainerClient) {
    ListBlobsOptions options = new ListBlobsOptions()
            .setMaxResultsPerPage(2) // Low number for demonstration purposes
            .setDetails(new BlobListDetails()
                    .setRetrieveDeletedBlobs(true));

    System.out.println("List blobs flat:");

    int i = 0;
    Iterable<PagedResponse<BlobItem>> blobPages = blobContainerClient.listBlobs(options, null).iterableByPage();
    for (PagedResponse<BlobItem> page : blobPages) {
        System.out.printf("Page %d%n", ++i);
        page.getElements().forEach(blob -> {
            System.out.printf("Name: %s, Is deleted? %b%n",
                    blob.getName(),
                    blob.isDeleted());
        });
    }
}

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

List blobs flat:
Page 1
Name: file4.txt, Is deleted? false
Name: file5-deleted.txt, Is deleted? true
Page 2
Name: folderA/file1.txt, Is deleted? false
Name: folderA/file2.txt, Is deleted? false
Page 3
Name: folderA/folderB/file3.txt, Is deleted? false

Примечание.

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

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

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

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

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

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

public void listBlobsHierarchicalListing(BlobContainerClient blobContainerClient, String prefix/* ="" */) {
    String delimiter = "/";
    ListBlobsOptions options = new ListBlobsOptions()
            .setPrefix(prefix);

    blobContainerClient.listBlobsByHierarchy(delimiter, options, null)
            .forEach(blob -> {
                if (blob.isPrefix()) {
                    System.out.printf("Virtual directory prefix: %s%n", delimiter + blob.getName());
                    listBlobsHierarchicalListing(blobContainerClient, blob.getName());
                } else {
                    System.out.printf("Blob name: %s%n", blob.getName());
                }
            });
}

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

List blobs hierarchical:
Blob name: file4.txt
Virtual directory prefix: /folderA/
Blob name: folderA/file1.txt
Blob name: folderA/file2.txt
Virtual directory prefix: /folderA/folderB/
Blob name: folderA/folderB/file3.txt

Примечание.

Снимки blob нельзя перечислять в иерархической операции списка.

Список blobs в формате Apache Arrow (предварительный просмотр)

Important

Список блобов в формате Apache Arrow сейчас находится в PREVIEW. Для этого сценария требуется бета-версия (предпросмотр) клиентской библиотеки Хранилище BLOB-объектов Azure для Java (например, azure-storage-blobверсия 12.36.0-beta.1 или более поздний предпросмотрный релиз). Предварительные версии функций предоставляются без соглашения об уровне обслуживания и не рекомендуется для рабочих нагрузок. Некоторые функции могут не поддерживаться или иметь ограниченные возможности. Дополнительные сведения см. в статье Дополнительные условия использования предварительных версий Microsoft Azure.

Эта возможность основана на существующем List Blobs API. Вместо стандартного XML в качестве формата ответов при передаче по сети используется компактный колоночный формат Apache Arrow. Это включается установкой одного параметра в запросе на получение списка контейнеров. Java SDK расшифровывает Apache Arrow за кулисами и всё равно возвращает те же объектыBlobItem. Такой подход повышает производительность при получении списка и снижает нагрузку на ЦП на стороне клиента при перечислении содержимого больших контейнеров. Он сохраняет контракт на ответ, на который опираются заявки.

Предупреждение

Получение списка BLOB-объектов в формате Apache Arrow не поддерживается в учетных записях хранения с включенным иерархическим пространством имен (Azure Data Lake Storage).

Чтобы запросить результаты в формате Apache Arrow, установите формат сериализации ответов в ListBlobsOptions на StorageResponseSerializationFormat.ARROW , вызвав setStorageResponseSerializationFormat, затем передайте эти опции в BlobContainerClient.listBlobs. При использовании вывода Apache Arrow вы также можете вызвать setStartFrom и setEndBefore, чтобы управлять диапазоном возвращаемых путей.

В следующем примере перечислены blob-и в контейнере и запрашиваются результаты в формате Apache Arrow:

ListBlobsOptions options = new ListBlobsOptions()
    .setPrefix("folderA/")
    .setStorageResponseSerializationFormat(StorageResponseSerializationFormat.ARROW);

for (BlobItem blobItem : containerClient.listBlobs(options, null)) {
    System.out.println("Blob name: " + blobItem.getName());
}

Ресурсы

Чтобы узнать больше о том, как перечислять blob-и с помощью клиентской библиотеки Хранилище BLOB-объектов Azure для Java, смотрите следующие ресурсы.

Примеры кода

Операции REST API

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

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

См. также

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

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