Elencare i BLOB con JavaScript

Articolo
10/31/2024

Questo articolo illustra come elencare i BLOB usando la libreria client 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:
- Elencare i BLOB

Informazioni sulle opzioni per l'elenco di BLOB

Quando si elencano i BLOB dal codice, è possibile specificare diverse opzioni per gestire la modalità di restituzione dei risultati da Archiviazione di Azure. È 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 flat, 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 prefix proprietà in ContainerListBlobsOptions. La stringa di prefisso può includere uno o più caratteri. Archiviazione di Azure restituisce solo i BLOB i cui nomi iniziano con tale prefisso. Ad esempio, il passaggio della stringa sample- di prefisso restituisce solo i BLOB i cui nomi iniziano con sample-.

Includere metadati BLOB o altre informazioni

Per includere i metadati blob con i risultati, impostare la includeMetadata proprietà su true come parte di 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, è possibile organizzare i BLOB in directory virtuali per simulare 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 i BLOB vengono denominati usando un delimitatore, è possibile scegliere un elenco gerarchico. In un'operazione di elenco gerarchico, Archiviazione di Azure restituisce le directory virtuali e i BLOB 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.

L'esempio seguente elenca i BLOB nel contenitore specificato usando un elenco flat. Questo esempio include snapshot BLOB e metadati BLOB, se esistenti:

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

L'output è simile al seguente:

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

Nota

L'output di esempio illustrato presuppone che si disponga di un account di archiviazione con uno spazio dei nomi flat. Se è stata abilitata la funzionalità dello spazio dei nomi gerarchico per l'account di archiviazione, le directory non sono virtuali. Sono invece oggetti concreti e indipendenti. Di conseguenza, le directory vengono visualizzate nell’elenco come BLOB di lunghezza zero.

Per un’opzione di elenco alternativa quando si usa uno spazio dei nomi gerarchico, vedere Elencare il contenuto delle directory (Azure Data Lake Storage).

Usare un elenco gerarchico

Quando si chiama un'operazione di elenco gerarchico, Archiviazione di Azure restituisce le directory virtuali e i BLOB del 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 chiama quindi l'operazione di elenco in modo ricorsivo per attraversare la gerarchia di directory virtuali ed elencare i 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}`);
    }
  }
}

L'output è 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

Nota

In un'operazione di elenco gerarchico non è possibile elencare gli snapshot BLOB.

Risorse

Per altre informazioni su come elencare i BLOB usando la libreria client Archiviazione BLOB di Azure per JavaScript, vedere le risorse seguenti.

Esempi di codice

Visualizzare esempi di codice JavaScript e TypeScript di questo articolo (GitHub)

Operazioni dell'API REST

Azure SDK per JavaScript contiene librerie basate sull'API REST di Azure che consentono di interagire con le operazioni dell'API REST tramite paradigmi noti di JavaScript. I metodi della libreria client per elencare i BLOB usano l'operazione API REST seguente:

List Blobs (API REST)

Condividi tramite