Elencare BLOB con .NET

Articolo
09/22/2023

Questo articolo illustra come elencare i BLOB usando la libreria client di Archiviazione di Azure per .NET.

Prerequisiti

Questo articolo presuppone che sia già stato configurato un progetto per lavorare con la libreria client Archiviazione BLOB di Azure per .NET. Per informazioni sulla configurazione del progetto, tra cui l'installazione del pacchetto, l'aggiunta using di direttive e la creazione di un oggetto client autorizzato, vedere Introduzione a Archiviazione BLOB di Azure e .NET.
Il meccanismo di autorizzazione deve disporre delle autorizzazioni per elencare i BLOB. Per altre informazioni, vedere le linee guida 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 tramite il codice, è possibile specificare diverse opzioni per gestire il modo in cui i risultati vengono restituiti dall'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:

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 da restituire per ogni operazione di elenco. 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 .NET.

Filtrare i risultati con un prefisso

Per filtrare l'elenco di BLOB, specificare una stringa per il prefix parametro . La stringa di prefisso può includere uno o più caratteri. Archiviazione di Azure restituisce solo i BLOB i cui nomi iniziano con tale prefisso.

Restituire i metadati

È possibile restituire metadati BLOB con i risultati specificando il valore Metadata per l'enumerazione BlobTraits .

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.

Nell'esempio seguente vengono elencati i BLOB nel contenitore specificato utilizzando un elenco semplice, con una dimensione di segmento facoltativa specificata. Il nome del BLOB viene scritto in una finestra della console.

private static async Task ListBlobsFlatListing(BlobContainerClient blobContainerClient, 
                                               int? segmentSize)
{
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = blobContainerClient.GetBlobsAsync()
            .AsPages(default, segmentSize);

        // Enumerate the blobs returned for each page.
        await foreach (Page<BlobItem> blobPage in resultSegment)
        {
            foreach (BlobItem blobItem in blobPage.Values)
            {
                Console.WriteLine("Blob name: {0}", blobItem.Name);
            }

            Console.WriteLine();
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

L'output è simile al seguente:

Blob name: FolderA/blob1.txt
Blob name: FolderA/blob2.txt
Blob name: FolderA/blob3.txt
Blob name: FolderA/FolderB/blob1.txt
Blob name: FolderA/FolderB/blob2.txt
Blob name: FolderA/FolderB/blob3.txt
Blob name: FolderA/FolderB/FolderC/blob1.txt
Blob name: FolderA/FolderB/FolderC/blob2.txt
Blob name: FolderA/FolderB/FolderC/blob3.txt

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 alternativo quando si usa uno spazio dei nomi gerarchico, vedere Elencare il contenuto della directory (Azure Data Lake Storage Gen2).

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, chiamare il metodo BlobContainerClient.GetBlobsByHierarchy o BlobContainerClient.GetBlobsByHierarchyAsync .

L'esempio seguente elenca i BLOB nel contenitore specificato usando un elenco gerarchico, con una dimensione del segmento facoltativa specificata e scrive il nome del BLOB nella finestra della console.

private static async Task ListBlobsHierarchicalListing(BlobContainerClient container, 
                                                       string prefix, 
                                                       int? segmentSize)
{
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = container.GetBlobsByHierarchyAsync(prefix:prefix, delimiter:"/")
            .AsPages(default, segmentSize);

        // Enumerate the blobs returned for each page.
        await foreach (Page<BlobHierarchyItem> blobPage in resultSegment)
        {
            // A hierarchical listing may return both virtual directories and blobs.
            foreach (BlobHierarchyItem blobhierarchyItem in blobPage.Values)
            {
                if (blobhierarchyItem.IsPrefix)
                {
                    // Write out the prefix of the virtual directory.
                    Console.WriteLine("Virtual directory prefix: {0}", blobhierarchyItem.Prefix);

                    // Call recursively with the prefix to traverse the virtual directory.
                    await ListBlobsHierarchicalListing(container, blobhierarchyItem.Prefix, null);
                }
                else
                {
                    // Write out the name of the blob.
                    Console.WriteLine("Blob name: {0}", blobhierarchyItem.Blob.Name);
                }
            }

            Console.WriteLine();
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

L'output è simile al seguente:

Virtual directory prefix: FolderA/
Blob name: FolderA/blob1.txt
Blob name: FolderA/blob2.txt
Blob name: FolderA/blob3.txt

Virtual directory prefix: FolderA/FolderB/
Blob name: FolderA/FolderB/blob1.txt
Blob name: FolderA/FolderB/blob2.txt
Blob name: FolderA/FolderB/blob3.txt

Virtual directory prefix: FolderA/FolderB/FolderC/
Blob name: FolderA/FolderB/FolderC/blob1.txt
Blob name: FolderA/FolderB/FolderC/blob2.txt
Blob name: FolderA/FolderB/FolderC/blob3.txt

Nota

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

Elencare le versioni o gli snapshot dei BLOB

Per elencare le versioni o gli snapshot del BLOB, specificare il parametro BlobStates con il campo Version o Snapshot . Le versioni e gli snapshot sono elencati dal meno recente al più recente.

Nell'esempio di codice seguente viene illustrato come elencare le versioni dei BLOB.

private static void ListBlobVersions(BlobContainerClient blobContainerClient, 
                                           string blobName)
{
    try
    {
        // Call the listing operation, specifying that blob versions are returned.
        // Use the blob name as the prefix. 
        var blobVersions = blobContainerClient.GetBlobs
            (BlobTraits.None, BlobStates.Version, prefix: blobName)
            .OrderByDescending(version => version.VersionId).Where(blob => blob.Name == blobName);

        // Construct the URI for each blob version.
        foreach (var version in blobVersions)
        {
            BlobUriBuilder blobUriBuilder = new BlobUriBuilder(blobContainerClient.Uri)
            {
                BlobName = version.Name,
                VersionId = version.VersionId
            };

            if ((bool)version.IsLatestVersion.GetValueOrDefault())
            {
                Console.WriteLine("Current version: {0}", blobUriBuilder);
            }
            else
            {
                Console.WriteLine("Previous version: {0}", blobUriBuilder);
            }
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

Risorse

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

Operazioni dell'API REST

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

Elencare i BLOB (API REST)