Перечисление 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 организованы в плоской парадигме, вместо иерархического подхода (как в классической файловой системе). Однако объекты можно упорядочить по виртуальным каталогам, чтобы имитировать структуру папок. Виртуальный каталог образует часть имени блоба и обозначается символом-разделителем.

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

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

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

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

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

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 возвращает виртуальные каталоги и большие двоичные объекты на первом уровне иерархии.

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

• BlobContainerClient.listBlobsByHierarchy

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

// 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 с помощью клиентской библиотеки Azure Blob Storage для JavaScript, см. в следующих ресурсах.

Примеры кода

• Просмотр примеров кода JavaScript и TypeScript из этой статьи (GitHub)

Операции REST API

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

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

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

• Справочная документация по клиентской библиотеке
• Исходный код клиентской библиотеки
• Пакет (npm)

См. также

• Перечисление ресурсов BLOB
• Версионирование BLOB-объектов