Scarica un blob con .NET

Questo articolo illustra come scaricare un BLOB usando la libreria client di Archiviazione di Azure per .NET. È possibile scaricare dati BLOB in varie destinazioni, tra cui un percorso di file locale, un flusso o una stringa di testo. È anche possibile aprire un flusso BLOB e leggerlo.

Prerequisiti

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 i dettagli, vedi Introduzione a Archiviazione BLOB di Azure e .NET.

Installare i pacchetti

Dalla directory del progetto, installare i pacchetti per le librerie client di Archiviazione BLOB di Azure e Azure Identity utilizzando 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 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 dependency injection 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 eseguire un'operazione di download. Per l'autorizzazione con Microsoft Entra ID (opzione consigliata), è necessario disporre del ruolo predefinito di RBAC di Azure Lettore dati BLOB di Archiviazione o superiore. Per altre informazioni, vedere le indicazioni sulle autorizzazioni per Get Blob (API REST).

Scarica un blob

Per scaricare un BLOB, è possibile utilizzare uno o più dei metodi seguenti:

È anche possibile aprire un flusso per leggere da un BLOB. Il flusso scarica il blob solo man mano che viene letto. È possibile usare uno dei metodi seguenti:

Scaricare in un percorso file

L'esempio seguente scarica un BLOB in un percorso di file locale. Se la directory specificata non esiste, il codice genera un'eccezione DirectoryNotFoundException. Se il file esiste già in localFilePath, viene sovrascritto per impostazione predefinita durante i download successivi.

public static async Task DownloadBlobToFileAsync(
    BlobClient blobClient,
    string localFilePath)
{
    await blobClient.DownloadToAsync(localFilePath);
}

Scaricare in un flusso

L'esempio seguente scarica un blob creando un oggetto Stream e quindi lo scarica in tale flusso. Se la directory specificata non esiste, il codice genera un'eccezione DirectoryNotFoundException.

public static async Task DownloadBlobToStreamAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    await blobClient.DownloadToAsync(fileStream);

    fileStream.Close();
}

Scaricare in una stringa

L'esempio seguente presuppone che il BLOB sia un file di testo e scarica il BLOB in una stringa:

public static async Task DownloadBlobToStringAsync(BlobClient blobClient)
{
    BlobDownloadResult downloadResult = await blobClient.DownloadContentAsync();
    string blobContents = downloadResult.Content.ToString();
}

Scaricare da un flusso

L'esempio seguente scarica un blob leggendo da un flusso:

public static async Task DownloadBlobFromStreamAsync(
    BlobClient blobClient,
    string localFilePath)
{
    using (var stream = await blobClient.OpenReadAsync())
    {
        FileStream fileStream = File.OpenWrite(localFilePath);
        await stream.CopyToAsync(fileStream);
    }
}

Scaricare un BLOB in blocchi con le opzioni di configurazione

È possibile definire le opzioni di configurazione della libreria client durante il download di un BLOB. Queste opzioni possono essere ottimizzate per migliorare le prestazioni e l'affidabilità. Gli esempi di codice seguenti illustrano come usare BlobDownloadToOptions per definire le opzioni di configurazione quando si chiama un metodo di download. Si noti che le stesse opzioni sono disponibili per BlobDownloadOptions.

Specificare le opzioni di trasferimento dei dati al download

È possibile configurare i valori in StorageTransferOptions per migliorare le prestazioni per le operazioni di trasferimento dei dati. Nell'esempio di codice seguente viene illustrato come impostare i valori per StorageTransferOptions e includere le opzioni come parte di un'istanza di BlobDownloadToOptions. I valori forniti in questo esempio non sono necessariamente quelli consigliati. Per ottimizzare correttamente questi valori, è necessario considerare le esigenze specifiche dell'app.

public static async Task DownloadBlobWithTransferOptionsAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    var transferOptions = new StorageTransferOptions
    {
        // Set the maximum number of parallel transfer workers
        MaximumConcurrency = 2,

        // Set the initial transfer length to 8 MiB
        InitialTransferSize = 8 * 1024 * 1024,

        // Set the maximum length of a transfer to 4 MiB
        MaximumTransferSize = 4 * 1024 * 1024
    };

    BlobDownloadToOptions downloadOptions = new BlobDownloadToOptions()
    {
        TransferOptions = transferOptions
    };

    await blobClient.DownloadToAsync(fileStream, downloadOptions);

    fileStream.Close();
}

Per altre informazioni sull'ottimizzazione delle opzioni di trasferimento dei dati, vedere Ottimizzazione delle prestazioni per caricamenti e download.

Specificare le opzioni di convalida del trasferimento al download

La convalida del trasferimento con CRC64-NVME fornisce l'integrità dei dati a livello di client per Archiviazione BLOB di Azure, consentendo di verificare che i dati inviati dall'applicazione siano gli stessi dati archiviati e letti da Azure. Se abilitato, l'SDK BLOB calcola e convalida CRC64-NVME checksum durante le operazioni di caricamento e download, mentre il servizio calcola e convalida in modo indipendente CRC64-NVME checksum per i dati ricevuti e restituiti. La convalida viene eseguita su ogni richiesta e nel flusso di dati completo, assicurandosi che l'intero BLOB venga verificato anche quando i dati vengono trasferiti in partizioni, ad esempio caricamenti in blocchi o letture a intervalli. Per altri dettagli, vedere Structured Body Format (Formato corpo strutturato ).

La convalida del trasferimento con MD5 è disponibile per verificare che i dati inviati dall'applicazione corrispondano ai dati ricevuti e restituiti dal servizio in ogni richiesta. Se abilitato, l'SDK Blob calcola e convalida gli hash MD5 durante le operazioni di caricamento e download, mentre il servizio calcola e convalida in modo indipendente gli hash MD5 per i dati che elabora. La convalida viene eseguita a livello di richiesta e risposta HTTP, consentendo di rilevare il danneggiamento per ogni segmento di dati trasferito, ad esempio singoli blocchi durante i caricamenti o gli intervalli durante le letture.

Le opzioni di convalida del trasferimento possono essere definite a livello di client usando BlobClientOptions, che applica le opzioni di convalida a tutti i metodi chiamati da un'istanza BlobClient. In alternativa, è possibile eseguire l'override delle opzioni di convalida del trasferimento a livello di metodo usando BlobDownloadToOptions. Nell'esempio di codice seguente viene illustrato come creare un oggetto BlobDownloadToOptions e specificare un algoritmo per la generazione di un checksum.

public static async Task DownloadBlobWithChecksumAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    var validationOptions = new DownloadTransferValidationOptions
    {
        AutoValidateChecksum = true,
        ChecksumAlgorithm = StorageChecksumAlgorithm.Auto
    };

    BlobDownloadToOptions downloadOptions = new BlobDownloadToOptions()
    {
        TransferValidation = validationOptions
    };

    await blobClient.DownloadToAsync(fileStream, downloadOptions);

    fileStream.Close();
}

La tabella seguente illustra le opzioni disponibili per l'algoritmo checksum, come definito da StorageChecksumAlgorithm:

Nome valore Descrizione
Automatico 0 Consigliato. Consente alla libreria di scegliere un algoritmo. Diverse versioni della libreria possono scegliere algoritmi diversi. Sceglie automaticamente StorageCrc64 nelle versioni della libreria client 12.28.0+
None 1 Nessun algoritmo selezionato. Non calcolare o richiedere i checksum.
MD5 2 Algoritmo hash MD5 standard.
StorageCrc64 3 Archiviazione di Azure CRC64-NVME personalizzato.

Risorse

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

Esempi di codice

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 scaricare i BLOB usano l'operazione API REST seguente:

Risorse della libreria client

Vedi anche

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.
  • Last updated on