Elencare BLOB con Java

Questo articolo illustra come elencare i BLOB con la libreria client di Archiviazione di Azure per Java.

Prerequisiti

• Sottoscrizione di Azure: creare un account gratuito
• Account di archiviazione di Azure: creare un account di archiviazione
• Kit di sviluppo Java (JDK) versione 8 o successiva (è consigliabile usare la versione 17 per l’esperienza migliore)
• Per la gestione dei progetti in questo esempio viene usato Apache Maven

Configurazione dell'ambiente

Se non si ha un progetto esistente, questa sezione illustra come configurare un progetto per l’uso con la libreria client di Archiviazione BLOB di Azure per Java. Per altre informazioni, vedere Introduzione all’Archiviazione BLOB di Azure e Java.

Per usare gli esempi di codice in questo articolo, seguire questa procedura per configurare il progetto.

Installare i pacchetti

Aprire il file pom.xml nell'editor di testo. Installare i pacchetti includendo il file BOM o includendo una dipendenza diretta.

Aggiungere le istruzioni di importazione

Aggiungere le istruzioni import seguenti:

import com.azure.core.http.rest.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;

Autorizzazione

Il meccanismo di autorizzazione deve disporre delle autorizzazioni necessarie per elencare un blob. Per l'autorizzazione tramite Microsoft Entra ID (consigliato), è necessario il ruolo predefinito di Azure RBAC Storage Blob Data Reader o un ruolo superiore. Per altre informazioni, vedere le indicazioni sulle autorizzazioni per List Blobs (API REST).

Creare un oggetto client

Per connettere un'app all'archiviazione di BLOB, creare un'istanza di BlobServiceClient.

L’esempio seguente usa BlobServiceClientBuilder per compilare un oggetto BlobServiceClient usando DefaultAzureCredential e illustra come creare client blob e contenitori, se necessario:

// Azure SDK client builders accept the credential as a parameter
// TODO: Replace <storage-account-name> with your actual storage account name
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .endpoint("https://<storage-account-name>.blob.core.windows.net/")
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

// If needed, you can create a BlobContainerClient object from the BlobServiceClient
BlobContainerClient containerClient = blobServiceClient
        .getBlobContainerClient("<container-name>");

// If needed, you can create a BlobClient object from the BlobContainerClient
BlobClient blobClient = containerClient
        .getBlobClient("<blob-name>");

Per altre informazioni sulla creazione e la gestione di oggetti client, vedere Creare e gestire oggetti client che interagiscono con le risorse dati.

Informazioni sulle opzioni di elenco dei blob

Quando si elencano i blob dal codice, è possibile specificare opzioni per gestire il modo in cui i risultati vengono restituiti 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 account di archiviazione, chiamare uno dei metodi seguenti:

• listBlobs
• 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 in Azure SDK per Java.

Filtrare i risultati con un prefisso

Per filtrare l'elenco di BLOB, passare una stringa come parametro prefix a ListBlobsOptions.setPrefix(String prefix). La stringa di prefisso può includere uno o più caratteri. Archiviazione di Azure restituisce quindi solo i blob i cui nomi iniziano con quel prefisso.

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. 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.

L'esempio seguente elenca i blob nel contenitore specificato usando un elenco semplice:

public void listBlobsFlat(BlobContainerClient blobContainerClient) {
    System.out.println("List blobs flat:");

    blobContainerClient.listBlobs()
            .forEach(blob -> System.out.printf("Name: %s%n", blob.getName()));
}

L'esempio di output è simile al seguente:

List blobs flat:
Name: file4.txt
Name: folderA/file1.txt
Name: folderA/file2.txt
Name: folderA/folderB/file3.txt

Puoi anche specificare opzioni per filtrare i risultati delle liste o mostrare maggiori informazioni. L'esempio seguente elenca i BLOB con un prefisso specifico e i BLOB eliminati:

public void listBlobsFlatWithOptions(BlobContainerClient blobContainerClient) {
    ListBlobsOptions options = new ListBlobsOptions()
            .setMaxResultsPerPage(2) // Low number for demonstration purposes
            .setDetails(new BlobListDetails()
                    .setRetrieveDeletedBlobs(true));

    System.out.println("List blobs flat:");

    int i = 0;
    Iterable<PagedResponse<BlobItem>> blobPages = blobContainerClient.listBlobs(options, null).iterableByPage();
    for (PagedResponse<BlobItem> page : blobPages) {
        System.out.printf("Page %d%n", ++i);
        page.getElements().forEach(blob -> {
            System.out.printf("Name: %s, Is deleted? %b%n",
                    blob.getName(),
                    blob.isDeleted());
        });
    }
}

L'esempio di output è simile al seguente:

List blobs flat:
Page 1
Name: file4.txt, Is deleted? false
Name: file5-deleted.txt, Is deleted? true
Page 2
Name: folderA/file1.txt, Is deleted? false
Name: folderA/file2.txt, Is deleted? false
Page 3
Name: folderA/folderB/file3.txt, Is deleted? false

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:

• listBlobsByHierarchy

L'esempio seguente elenca i BLOB nel contenitore specificato usando un elenco gerarchico:

public void listBlobsHierarchicalListing(BlobContainerClient blobContainerClient, String prefix/* ="" */) {
    String delimiter = "/";
    ListBlobsOptions options = new ListBlobsOptions()
            .setPrefix(prefix);

    blobContainerClient.listBlobsByHierarchy(delimiter, options, null)
            .forEach(blob -> {
                if (blob.isPrefix()) {
                    System.out.printf("Virtual directory prefix: %s%n", delimiter + blob.getName());
                    listBlobsHierarchicalListing(blobContainerClient, blob.getName());
                } else {
                    System.out.printf("Blob name: %s%n", blob.getName());
                }
            });
}

L'esempio di output è simile al seguente:

List blobs hierarchical:
Blob name: file4.txt
Virtual directory prefix: /folderA/
Blob name: folderA/file1.txt
Blob name: folderA/file2.txt
Virtual directory prefix: /folderA/folderB/
Blob name: folderA/folderB/file3.txt

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 Java decodifica Apache Arrow dietro le quinte e restituisce comunque gli stessi BlobItem oggetti. 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 il formato di serializzazione della risposta su ListBlobsOptions su StorageResponseSerializationFormat.ARROW chiamando setStorageResponseSerializationFormat, poi passa le opzioni a BlobContainerClient.listBlobs. Quando si usa l'output di Apache Arrow, puoi anche chiamare setStartFrom e setEndBefore controllare l'intervallo di percorsi restituiti.

Il seguente esempio elenca i blob in un contenitore e richiede i risultati in formato Apache Arrow:

ListBlobsOptions options = new ListBlobsOptions()
    .setPrefix("folderA/")
    .setStorageResponseSerializationFormat(StorageResponseSerializationFormat.ARROW);

for (BlobItem blobItem : containerClient.listBlobs(options, null)) {
    System.out.println("Blob name: " + blobItem.getName());
}

Risorse

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

Esempi di codice

• Vedere gli esempi di codice di questo articolo (GitHub)

Operazioni dell'API REST

L'Azure SDK per Java contiene librerie che si costruiscono sopra l'API REST di Azure. Utilizzando queste librerie, puoi interagire con le operazioni API REST attraverso paradigmi Java 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 (Maven)

Vedi anche

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

Contenuto correlato

• Questo articolo fa parte della guida per sviluppatori di Archiviazione BLOB per Java. Per altre informazioni, vedere l'elenco completo degli articoli della Guida per sviluppatori in Creare la propria app Java.