Listar blobs con JavaScript

En este artículo se muestra cómo enumerar blobs con la biblioteca cliente de Azure Storage para JavaScript.

Requisitos previos

• Los ejemplos de este artículo asumen que ya tiene un proyecto configurado para trabajar con la librería cliente Azure Blob Storage para JavaScript. Para obtener más información sobre la configuración del proyecto, incluida la instalación de paquetes, la importación de módulos y la creación de un objeto cliente autorizado para trabajar con recursos de datos, consulte Introducción a Azure Blob Storage y JavaScript.
• El mecanismo de autorización debe tener permisos para enumerar blobs. Para obtener más información, consulte la guía de autorización para la siguiente operación de la API de REST:
  • Enumeración de blobs

Información sobre las opciones de enumeración de blobs

Al enumerar blobs desde el código, puede especificar varias opciones para administrar cómo se devuelven los resultados de Azure Storage. Puede especificar el número de resultados que se van a devolver en cada conjunto de resultados y luego recuperar los conjuntos subsiguientes. Puede especificar un prefijo para devolver los blobs cuyos nombres comienzan por ese carácter o cadena. También puede enumerar los blobs en una estructura de lista plana o de forma jerárquica. Una lista jerárquica devuelve los blobs como si estuvieran organizados en carpetas.

Para enumerar los blobs de un contenedor usando una lista plana, llame al siguiente método:

• ContainerClient.listBlobsFlat

Para enumerar los blobs de un contenedor usando una lista jerárquica, llame al siguiente método:

• ContainerClient.listBlobsByHierarchy

Gestiona cuántos resultados se devuelven

De forma predeterminada, una operación de enumeración devuelve hasta 5000 resultados a la vez, pero puede especificar el número de resultados que quiere que devuelva. En los ejemplos que se presentan en este artículo muestran cómo devolver resultados por páginas. Para más información sobre los conceptos de paginación, consulte Paginación con el SDK de Azure para JavaScript.

Filtrado de los resultados con un prefijo

Para filtrar la lista de blobs, especifique una cadena para la propiedad prefix en ContainerListBlobsOptions. La cadena de prefijo puede incluir uno o varios caracteres. Azure Storage solo devuelve los blobs cuyos nombres comienzan con ese prefijo. Por ejemplo, pasar la cadena sample- de prefijo solo devuelve blobs cuyos nombres comienzan por sample-.

Incluir metadatos del blob u otra información

Para incluir los metadatos del blob con los resultados, establezca la propiedad includeMetadata en true como parte de ContainerListBlobsOptions. También puede incluir instantáneas, etiquetas o versiones en los resultados estableciendo la propiedad adecuada a true.

Lista plana frente a lista jerárquica

Los blobs de Azure Storage están organizados en un paradigma plano, en lugar de un paradigma jerárquico (como un sistema de archivos clásico). Sin embargo, puedes organizar los blobs en directorios virtuales para imitar una estructura de carpetas. Un directorio virtual forma parte del nombre del blob y se indica mediante el carácter delimitador.

Para organizar los blobs en directorios virtuales, use un carácter delimitador en el nombre del blob. El carácter delimitador predeterminado es una barra diagonal (/), pero puede especificar cualquier carácter como delimitador.

Si nombras tus blobs usando un delimitador, puedes elegir listar los blobs jerárquicamente. En el caso de una operación de enumeración jerárquica, Azure Storage devuelve los directorios virtuales y los blobs que hay debajo del objeto primario. Puede llamar a la operación de enumeración de forma recursiva para recorrer la jerarquía, de manera similar a como se haría con un sistema de archivos clásico mediante programación.

Uso de una lista plana

De forma predeterminada, una operación de enumeración devuelve los blobs en una lista plana. En una lista plana, los blobs no se organizan por directorio virtual.

El siguiente ejemplo lista las bolas en el contenedor especificado usando una lista plana. Este ejemplo incluye instantáneas de blobs y metadatos de blobs, si existen:

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}`);
      }
    }
  }
}

La salida es parecida a esta:

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

Uso de una lista jerárquica

Cuando se realiza una operación de enumeración de forma jerárquica, Azure Storage devuelve los directorios virtuales y los blobs en el primer nivel de la jerarquía.

Para enumerar los blobs jerárquicamente, use el método siguiente:

• BlobContainerClient.listBlobsByHierarchy

En el ejemplo siguiente se enumeran los blobs del contenedor especificado mediante una lista jerárquica. En este ejemplo, el parámetro de prefijo se establece inicialmente en una cadena vacía para enumerar todos los blobs del contenedor. A continuación, el ejemplo llama recursivamente a la operación de enumeración para recorrer la jerarquía de directorios virtuales y enumerar los blobs.

// 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}`);
    }
  }
}

La salida es parecida a esta:

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

Lista de blobs en formato Apache Arrow (vista previa)

Esta capacidad se basa en la API existente List Blobs . En lugar de usar el XML por defecto, utiliza el formato compacto y columnar Apache Arrow como formato de respuesta en el cable. Lo activas configurando una única opción en la llamada para listar contenedores. El SDK de JavaScript decodifica Apache Arrow detrás de escena y sigue devolviendo los mismos objetos de blob. Este enfoque mejora el rendimiento de listados y reduce la CPU del lado del cliente al enumerar contenedores grandes. Preserva el contrato de respuesta en el que dependen las solicitudes.

Para solicitar resultados con formato Apache Arrow, establece la responseFormat propiedad de las opciones de listado en StorageResponseFormat.Arrow, y luego pasa las opciones a ContainerClient.listBlobsFlat. Importa el StorageResponseFormat enum desde @azure/storage-blob.

El siguiente ejemplo lista los blobs en un contenedor y solicita los resultados en formato 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);
}

Recursos

Para saber más sobre cómo listar blobs utilizando la biblioteca cliente Azure Blob Storage para JavaScript, consulta los siguientes recursos.

Ejemplos de código

• Consulta ejemplos de código JavaScript y TypeScript de este artículo en GitHub.

Operaciones de API REST

El SDK de Azure para JavaScript contiene bibliotecas que se construyen sobre la API REST de Azure. Al utilizar estas librerías, puedes interactuar con las operaciones de la API REST mediante paradigmas JavaScript familiares. Los métodos de la biblioteca cliente para crear listas de blobs usan esta operación de API de REST:

• Enumeración de blobs (API de REST)

Recursos de la biblioteca cliente

• Documentación de referencia de la biblioteca cliente
• Código fuente de la biblioteca del cliente
• Paquete (npm)

Consulte también

• Enumeración de recursos de blob
• Control de versiones de blobs