Elencare BLOB con .NET

Questo articolo mostra come elencare i blob utilizzando la libreria client Archiviazione di Azure per .NET.

Prerequisiti

• Sottoscrizione di Azure: creare un account gratuito
• Account di archiviazione di Azure: creare un account di archiviazione
• Ultima versione di .NET SDK per il sistema operativo in uso. Assicurarsi di ottenere l'SDK e non il runtime.

Configurazione dell'ambiente

Se non si ha un progetto esistente, questa sezione spiega come configurare un progetto per l'uso con la libreria client di Archiviazione BLOB di Azure per .NET. I passaggi includono l'installazione del pacchetto, l'aggiunta di direttive using e la creazione di un oggetto client autorizzato. Per altre informazioni, vedi Introduzione a Archiviazione BLOB di Azure e .NET.

Installare i pacchetti

Nella directory del progetto installare i pacchetti per le librerie client di Archiviazione BLOB di Azure e Azure Identity usando il comando dotnet add package. Il pacchetto Azure.Identity è necessario per le connessioni senza password ai servizi di Azure.

dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity

Aggiungere direttive using

Aggiungere queste direttive using all'inizio del file del codice:

using Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;

Alcuni esempi di codice in questo articolo potrebbero richiedere direttive using aggiuntive.

Creare un oggetto client

Per connettere un'app all'archiviazione di BLOB, creare un'istanza di BlobServiceClient. Nell'esempio seguente viene illustrato come creare un oggetto client usando DefaultAzureCredential per l'autorizzazione:

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

È possibile registrare un client di servizio per l'iniezione di dipendenze in un'app .NET.

È anche possibile creare oggetti client per contenitori o BLOB specifici. Per altre informazioni sulla creazione e la gestione di oggetti client, vedere Creare e gestire oggetti client che interagiscono con le risorse dati.

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

Informazioni sulle opzioni di elenco dei 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. Puoi elencare i blob in una struttura di elenco piatto 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:

• BlobContainerClient.GetBlobs
• BlobContainerClient.GetBlobsAsync
• BlobContainerClient.GetBlobsByHierarchy
• BlobContainerClient.GetBlobsByHierarchyAsync

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

Filtrare i risultati con un prefisso

Per filtrare l’elenco dei BLOB, specificare una stringa per il parametro 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.

Restituisci metadati

È possibile restituire i metadati del BLOB con i risultati specificando il valore metadati 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. 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 usando un elenco piatto, con una dimensione di segmento opzionale specificata, e scrive il nome del blob su 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 di esempio è 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

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

Il seguente esempio elenca i blob nel contenitore specificato usando un elenco gerarchico, con una dimensione di segmento opzionale 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 di esempio è 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

Elencare le versioni o gli snapshot dei BLOB

Per elencare le versioni o gli snapshot dei BLOB, specificare il parametro BlobStates con il campo Versione o Snapshot. Il servizio restituisce versioni e istantanee dal più vecchio 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;
    }
}

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 .NET 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 la proprietà ResponseFormat di GetBlobsOptions su StorageResponseFormat.Arrow, poi passa le opzioni al sovraccarico BlobContainerClient.GetBlobs che accetta GetBlobsOptions. Quando si usa l'output di Apache Arrow, puoi anche impostare le StartFrom proprietà e EndBefore per controllare l'intervallo di percorsi restituiti.

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

using Azure.Storage;
using Azure.Storage.Blobs.Models;

GetBlobsOptions options = new GetBlobsOptions
{
    Prefix = "FolderA/",
    ResponseFormat = StorageResponseFormat.Arrow
};

foreach (BlobItem blobItem in containerClient.GetBlobs(options))
{
    Console.WriteLine("Blob name: " + blobItem.Name);
}

Risorse

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

Operazioni dell'API REST

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

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 .NET. Per altre informazioni, vedere l’elenco completo degli articoli della Guida per sviluppatori inCreare la propria app .NET.