Перечисление BLOB-объектов с помощью JavaScript

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

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

В примерах этой статьи предполагается, что у вас уже есть проект, настроенный для работы с клиентской библиотекой Хранилище BLOB-объектов Azure для JavaScript. Сведения о настройке проекта, включая установку пакетов, импорт модулей и создание авторизованного клиентского объекта для работы с ресурсами данных, см. в статье "Начало работы с Хранилище BLOB-объектов Azure и JavaScript".
Механизм авторизации должен иметь разрешения для перечисления блобов. Дополнительные сведения см. в руководстве по авторизации для следующей операции REST API:
- Список BLOB

Сведения об опциях перечисления Blob-объектов

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

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

ContainerClient.listBlobsFlat

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

ContainerClient.listBlobsByHierarchy

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

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

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

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

Включите метаданные BLOB или другие сведения

Чтобы включить метаданные BLOB-объектов в результаты, установите свойство includeMetadata в true как часть ContainerListBlobsOptions. Кроме того, можно включить моментальные снимки, теги или версии в результаты, задав соответствующее свойство true.

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

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

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

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

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

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

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

JavaScript
TypeScript

async function listBlobsFlat(containerClient) {

  const maxPageSize = 2;

  // Some options for filtering results
  const listOptions = {
    includeMetadata: true,
    includeSnapshots: true,
    prefix: '' // Filter results by blob name prefix
  };

  console.log("Blobs flat list (by page):");
  for await (const response of containerClient
    .listBlobsFlat(listOptions)
    .byPage({ maxPageSize })) {
    console.log("- Page:");
    if (response.segment.blobItems) {
      for (const blob of response.segment.blobItems) {
        console.log(`  - ${blob.name}`);
      }
    }
  }
}

async function listBlobsFlat(
  containerClient: ContainerClient
): Promise<void> {
  
  const maxPageSize = 2;

  // Some options for filtering results
  const listOptions: ContainerListBlobsOptions = {
    includeMetadata: true,
    includeSnapshots: true,
    prefix: '' // Filter results by blob name prefix
  };

  console.log("Blobs flat list(by page):");
  for await (const response of containerClient
    .listBlobsFlat(listOptions)
    .byPage({ maxPageSize })) {
    console.log("- Page:");
    if (response.segment.blobItems) {
      for (const blob of response.segment.blobItems) {
        console.log(`  - ${blob.name}`);
      }
    }
  }
}

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

Blobs flat list (by page):
- Page:
  - a1
  - a2
- Page:
  - folder1/b1
  - folder1/b2
- Page:
  - folder2/sub1/c
  - folder2/sub1/d

Примечание.

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

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

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

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

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

BlobContainerClient.listBlobsByHierarchy

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

JavaScript
TypeScript

// Recursively list virtual folders and blobs
async function listBlobHierarchical(containerClient, delimiter='/') {
  
  const maxPageSize = 20;

  // Some options for filtering list
  const listOptions = {
    prefix: '' // Filter results by blob name prefix   
  };

  let i = 1;
  console.log(`Folder ${delimiter}`);

  for await (const response of containerClient
    .listBlobsByHierarchy(delimiter, listOptions)
    .byPage({ maxPageSize })) {

    console.log(`   Page ${i++}`);
    const segment = response.segment;

    if (segment.blobPrefixes) {

      // Do something with each virtual folder
      for await (const prefix of segment.blobPrefixes) {

        // Build new delimiter from current and next
        await listBlobHierarchical(containerClient, `${delimiter}${prefix.name}`);
      }
    }

    for (const blob of response.segment.blobItems) {

      // Do something with each blob
      console.log(`\tBlobItem: name - ${blob.name}`);
    }
  }
}

// Recursively list virtual folders and blobs
async function listBlobHierarchical(
  containerClient: ContainerClient,
  delimiter = '/'
): Promise<void> {

  const maxPageSize = 20;

  // Some options for filtering results
  const listOptions: ContainerListBlobsOptions = {
    prefix: '' // Filter results by blob name prefix
  };

  let i = 1;
  console.log(`Folder ${delimiter}`);

  for await (const response of containerClient
    .listBlobsByHierarchy(delimiter, listOptions)
    .byPage({ maxPageSize })) {
    console.log(`   Page ${i++}`);
    const segment = response.segment;

    if (segment.blobPrefixes) {
      // Do something with each virtual folder
      for await (const prefix of segment.blobPrefixes) {
        // Build new delimiter from current and next
        await listBlobHierarchical(
          containerClient,
          `${delimiter}${prefix.name}`
        );
      }
    }

    for (const blob of response.segment.blobItems) {
      // Do something with each blob
      console.log(`\tBlobItem: name - ${blob.name}`);
    }
  }
}

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

Folder /
   Page 1
        BlobItem: name - a1
        BlobItem: name - a2
   Page 2
Folder /folder1/
   Page 1
        BlobItem: name - folder1/b1
        BlobItem: name - folder1/b2
Folder /folder2/
   Page 1
Folder /folder2/sub1/
   Page 1
        BlobItem: name - folder2/sub1/c
        BlobItem: name - folder2/sub1/d
   Page 2
        BlobItem: name - folder2/sub1/e

Примечание.

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

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

Important

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

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

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

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

Чтобы запросить результаты в формате Apache Arrow, установите свойство responseFormat параметров перечисления в значение StorageResponseFormat.Arrow, затем передайте параметры в ContainerClient.listBlobsFlat. Импортируйте StorageResponseFormat enum из @azure/storage-blob.

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

const { StorageResponseFormat } = require("@azure/storage-blob");

const options = {
  prefix: "FolderA/",
  responseFormat: StorageResponseFormat.Arrow,
};

for await (const blob of containerClient.listBlobsFlat(options)) {
  console.log("Blob name: " + blob.name);
}

Ресурсы

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

Примеры кода

Просмотрите примеры кода JavaScript и TypeScript из этой статьи на GitHub.

Операции REST API

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

Список блобов (REST API)

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

См. также

Обратная связь

Были ли сведения на этой странице полезными?

Последнее обновление: 2026-08-27