Elencare i BLOB con JavaScript

Questo articolo illustra come elencare i blob utilizzando la libreria client di Archiviazione di Azure per JavaScript.

Prerequisiti

• Gli esempi in questo articolo presuppongono che sia già stato configurato un progetto per l'uso con la libreria client di Archiviazione BLOB di Azure per JavaScript. Per informazioni sulla configurazione del progetto, incluse l'installazione del pacchetto, l'importazione di moduli e la creazione di un oggetto client autorizzato per l'uso con le risorse dati, consultare Introduzione ad Archiviazione BLOB di Azure e JavaScript.
• Il meccanismo di autorizzazione deve disporre delle autorizzazioni per elencare i BLOB. Per maggiori informazioni, consultare il materiale sussidiario per l'autorizzazione per l'operazione API REST seguente:
  • Elenca i blob

Informazioni sulle opzioni di elenco dei blob

Quando elenchi i blob nel codice, puoi specificare diverse opzioni per gestire il modo in cui Archiviazione di Azure restituisce i risultati. È possibile specificare il numero di risultati da restituire in ogni set di risultati e quindi recuperare i set successivi. È possibile specificare un prefisso per restituire i BLOB i cui nomi iniziano con tale carattere o stringa. Ed è possibile elencare i BLOB in una struttura elenco semplice o gerarchica. Un elenco gerarchico restituisce i BLOB come se fossero organizzati in cartelle.

Per elencare i blob in un contenitore usando un elenco semplice, chiamare il metodo seguente:

• ContainerClient.listBlobsFlat

Per elencare i BLOB in un contenitore usando un elenco gerarchico, chiamare il metodo seguente:

• ContainerClient.listBlobsByHierarchy

Gestire il numero di risultati restituiti

Per impostazione predefinita, un'operazione di elenco restituisce fino a 5000 risultati alla volta, ma è possibile specificare il numero di risultati che ogni operazione deve restituire. Gli esempi presentati in questo articolo illustrano come restituire i risultati nelle pagine. Per altre informazioni sui concetti relativi alla paginazione, vedere Paginazione con Azure SDK per JavaScript.

Filtrare i risultati con un prefisso

Per filtrare l'elenco di blob, specificare una stringa per la proprietà prefix in ContainerListBlobsOptions. La stringa di prefisso può includere uno o più caratteri. Archiviazione di Azure restituisce solo i blob i cui nomi iniziano con quel prefisso. Ad esempio, il passaggio della stringa sample- di prefisso restituisce solo i BLOB i cui nomi iniziano con sample-.

Includi i metadati blob o altre informazioni

Per includere i metadati dei BLOB nei risultati, impostare la proprietà includeMetadata su true nell'oggetto ContainerListBlobsOptions. È anche possibile includere snapshot, tag o versioni nei risultati impostando la proprietà appropriata su true.

Confronto tra elenco semplice e gerarchico

I BLOB in Archiviazione di Azure sono organizzati secondo un paradigma semplice, anziché gerarchico (come un file system classico). Tuttavia, puoi organizzare i blob in directory virtuali per imitare una struttura di cartelle. Una directory virtuale costituisce parte del nome del BLOB ed è indicata dal carattere di delimitazione.

Per organizzare i BLOB in directory virtuali, usare un carattere di delimitazione nel nome del BLOB. Il delimitatore predefinito è la barra (/), ma è possibile specificare qualsiasi carattere.

Se dai un nome ai tuoi blob usando un delimiter, puoi scegliere di elencarli in modo gerarchico. Per un'operazione di elencazione gerarchica, Archiviazione di Azure restituisce tutte le directory virtuali e i blob presenti sotto l'oggetto padre. È possibile chiamare l'operazione di elenco in modo ricorsivo per attraversare la gerarchia in modo analogo a come si attraverserebbe un file system classico a livello di codice.

Usare un elenco semplice

Per impostazione predefinita, un'operazione di elenco restituisce i BLOB in un elenco semplice. In un elenco semplice, i BLOB non sono organizzati in base alla directory virtuale.

Il seguente esempio elenca i blob nel contenitore specificato utilizzando un elenco piatto. Questo esempio comprende snapshot dei BLOB e metadati dei BLOB, se presenti:

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

L'output di esempio è simile al seguente:

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

Usare un elenco gerarchico

Quando si chiama un'operazione di elencazione in modo gerarchico, Archiviazione di Azure restituisce le directory virtuali e i blob al primo livello della gerarchia.

Per elencare i BLOB in modo gerarchico, usare il metodo seguente:

• BlobContainerClient.listBlobsByHierarchy

L'esempio seguente elenca i BLOB nel contenitore specificato usando un elenco gerarchico. In questo esempio, il parametro prefix viene inizialmente impostato su una stringa vuota per elencare tutti i BLOB nel contenitore. L'esempio richiama quindi ricorsivamente l'operazione di enumerazione per scorrere la gerarchia di directory virtuali ed elencare i 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}`);
    }
  }
}

L'output di esempio è simile al seguente:

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

Elenco dei blob in formato Apache Arrow (anteprima)

Questa funzionalità è costruita sull'API esistente List Blobs . Invece di usare l'XML predefinito, utilizza il formato compatto e columnare Apache Arrow come formato di risposta sul filo. Lo si abilita impostando una singola opzione nella chiamata di elenco dei contenitori. L'SDK JavaScript decodifica Apache Arrow dietro le quinte e restituisce comunque gli stessi oggetti blob. Questo approccio migliora la velocità di elencazione e riduce l'utilizzo della CPU lato client durante l'enumerazione di contenitori di grandi dimensioni. Preserva il contratto di risposta su cui si basano le domande.

Per richiedere risultati formattati con Apache Arrow, imposta la responseFormat proprietà delle opzioni di elenco su StorageResponseFormat.Arrow, poi passa le opzioni a ContainerClient.listBlobsFlat. Importare l'enum StorageResponseFormat da @azure/storage-blob.

Il seguente esempio elenca i blob in un contenitore e richiede i risultati in 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);
}

Risorse

Per saperne di più su come elencare i blob utilizzando la libreria client Archiviazione BLOB di Azure per JavaScript, consulta le seguenti risorse.

Esempi di codice

• Visualizza esempi di codice JavaScript e TypeScript da questo articolo su GitHub.

Operazioni dell'API REST

L'Azure SDK per JavaScript contiene librerie che si costruiscono sopra l'API Azure REST. Utilizzando queste librerie, puoi interagire con le operazioni REST API attraverso paradigmi JavaScript familiari. I metodi della libreria client per elencare i BLOB usano l'operazione API REST seguente:

• List Blobs (API REST)

Risorse della libreria client

• Documentazione di riferimento della libreria client
• Codice sorgente della libreria client
• Pacchetto (npm)

Vedi anche

• Elencare le risorse Blob
• Controllo delle versioni per i BLOB