Télécharger un blob avec .NET

  • Article

Cet article montre comment télécharger un objet blob en utilisant la Bibliothèque de client Stockage Azure pour .NET. Vous pouvez télécharger des données blob vers différentes destinations, notamment un chemin d’accès de fichier local, un flux ou une chaîne de texte. Vous pouvez également ouvrir un flux d’objets blob et lire à partir de celui-ci.

Prérequis

Paramétrer votre environnement

Si vous n’avez pas de projet existant, cette section vous montre comment configurer un projet pour travailler avec la bibliothèque de client Stockage Blob Azure pour .NET. Les étapes comprennent l’installation du package, l’ajout de directives using et la création d’un objet client autorisé. Pour plus d’informations, consultez Prise en main du Stockage Blob Azure et de .NET.

Installer des packages

À partir du répertoire du projet, installez les packages des bibliothèques de client Stockage Blob Azure et Azure Identity à l’aide de la commande dotnet add package. Le package Azure.Identity est nécessaire pour les connexions sans mot de passe aux services Azure.

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

Ajoutez des directives using.

Ajoutez ces directives using au début de votre fichier de code :

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

Certains exemples de code de cet article peuvent nécessiter des directives using supplémentaires.

Créer un objet client

Pour connecter une application au Stockage Blob, créez une instance de BlobServiceClient. L’exemple suivant montre comment créer un objet client à l’aide de DefaultAzureCredential pour l’autorisation :

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

    return client;
}

Vous pouvez inscrire un client de service pour l’injection de dépendances dans une application .NET.

Vous pouvez également créer des objets clients pour des conteneurs ou des objets blob spécifiques. Pour en savoir plus sur la création et la gestion d’objets clients, consultez Créer et gérer des objets clients qui interagissent avec des ressources de données.

Autorisation

Le mécanisme d’autorisation doit disposer des autorisations nécessaires pour effectuer une opération de téléchargement. Pour l’autorisation avec Microsoft Entra ID (recommandé), vous devez disposer au minimum du rôle RBAC Azure intégré Lecteur de données Blob du stockage. Pour en savoir plus, consultez l’aide sur l’autorisation pour l’opération Get Blob (API REST).

Télécharger un objet blob

Vous pouvez utiliser l’une des méthodes suivantes pour télécharger un objet blob :

Vous pouvez également ouvrir un flux pour lire un blob. Le flux télécharge uniquement le blob pendant la lecture du flux. Vous pouvez utiliser l’une des méthodes suivantes :

Télécharger dans un chemin de fichier

L’exemple suivant télécharge un blob dans un chemin d’accès de fichier local. Si le répertoire spécifié n’existe pas, le code lève une exception DirectoryNotFoundException. Si le fichier existe déjà dans localFilePath, il est remplacé par défaut lors des téléchargements suivants.

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

Télécharger dans un flux

L’exemple suivant télécharge un blob en créant un objet Stream, puis en charge ce flux. Si le répertoire spécifié n’existe pas, le code lève une exception DirectoryNotFoundException.

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

    await blobClient.DownloadToAsync(fileStream);

    fileStream.Close();
}

Télécharger dans une chaîne

L’exemple suivant suppose que l’objet blob est un fichier texte et télécharge l’objet blob vers une chaîne :

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

Télécharger à partir d’un flux

L’exemple suivant télécharge un blob en lisant un flux :

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

Télécharger un objet blob de blocs avec des options de configuration

Vous pouvez définir des options de configuration de bibliothèque de client lors du téléchargement d’un objet blob. Ces options peuvent être paramétrées pour améliorer les performances et améliorer la fiabilité. Les exemples de code suivants montrent comment utiliser BlobDownloadToOptions pour définir des options de configuration lors de l’appel d’une méthode de téléchargement. Notez que les mêmes options sont disponibles pour BlobDownloadOptions.

Spécifier les options de transfert de données lors du téléchargement

Vous pouvez configurer les valeurs dans StorageTransferOptions pour améliorer les performances des opérations de transfert de données. L’exemple de code suivant montre comment définir des valeurs pour StorageTransferOptions et inclure les options dans le cadre d’un BlobDownloadToOptions instance. Les valeurs fournies dans cet exemple ne sont pas destinées à être une recommandation. Pour régler correctement ces valeurs, vous devez tenir compte des besoins spécifiques de votre application.

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

Pour en savoir plus sur le réglage des options de transfert de données, consultez Optimisation des performances pour les chargements et les téléchargements.

Spécifier les options de validation de transfert lors du téléchargement

Vous pouvez spécifier des options de validation de transfert pour vous assurer que les données sont téléchargées correctement et qu’elles n’ont pas été falsifiées pendant le transit. Les options de validation de transfert peuvent être définies au niveau du client à l’aide de BlobClientOptions, qui applique des options de validation à toutes les méthodes appelées à partir d’un instance BlobClient.

Vous pouvez également remplacer les options de validation de transfert au niveau de la méthode à l’aide de BlobDownloadToOptions. L’exemple de code suivant montre comment créer un BlobDownloadToOptions objet et spécifier un algorithme pour générer une somme de contrôle. La somme de contrôle est ensuite utilisée par le service pour vérifier l’intégrité des données du contenu téléchargé.

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

Le tableau suivant présente les options disponibles pour l’algorithme de somme de contrôle, telles que définies par StorageChecksumAlgorithm :

Nom Valeur Description
Auto 0 Recommandé. Permet à la bibliothèque de choisir un algorithme. Différentes versions de bibliothèque peuvent choisir différents algorithmes.
Aucune 1 Aucun algorithme sélectionné. Ne calculez pas ou ne demandez pas de sommes de contrôle.
MD5 2 Algorithme de hachage MD5 standard.
StorageCrc64 3 Crc 64 bits personnalisé de Stockage Azure.

Ressources

Pour en savoir plus sur le téléchargement d’objets blob à l’aide de la bibliothèque de client Stockage Blob Azure pour .NET, consultez les ressources suivantes.

Exemples de code

Opérations de l'API REST

Le Kit de développement logiciel (SDK) Azure pour .NET contient des bibliothèques qui s'appuient sur l'API REST Azure, vous permettant d’interagir avec les opérations de l’API REST par le biais de paradigmes .NET familiers. Les méthodes de bibliothèque de client pour télécharger des objets blob utilisent l’opération d’API REST suivante :

Ressources de bibliothèque cliente

Voir aussi

Contenu connexe

  • Cet article fait partie du guide du développeur Stockage Blob pour .NET. Pour en savoir plus, consultez la liste complète des articles du guide du développeur dans Générer votre application .NET.