Partage via

Télécharger un objet blob avec .NET

  • Article

Cet article montre comment charger un objet blob à l’aide de la bibliothèque de client Stockage Azure pour .NET. Vous pouvez charger des données dans un objet blob de blocs à partir d’un chemin d’accès de fichier, d’un flux, d’un objet binaire ou d’une chaîne de texte. Vous pouvez également ouvrir un flux de blobs et écrire dans ce flux, ou charger des grands blobs dans des blocs.

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 charger un objet blob. Pour l’autorisation avec Microsoft Entra ID (recommandé), vous devez disposer au minimum du rôle RBAC Azure intégré Contributeur aux données Blob du stockage. Si vous souhaitez en savoir plus, consulter l’aide sur l’autorisation pour les opérations Put Blob (API REST) et Put Block (API REST).

Charger des données dans un blob de blocs

Vous pouvez utiliser l’une des méthodes suivantes pour charger des données dans un objet blob de blocs :

Lorsque vous utilisez ces méthodes de chargement, la bibliothèque de client peut appeler Put Blob ou une série d’appels Put Block, suivis de Put Block List. Ce comportement dépend de la taille globale de l’objet et de la façon dont les options de transfert de données sont définies.

Pour ouvrir un flux dans le Stockage Blob et écrire dans ce flux, utilisez l’une des méthodes suivantes :

Charger un blob de blocs à partir d’un chemin de fichier local

L’exemple suivant charge un objet blob de blocs à partir du chemin d'accès d’un fichier local :

public static async Task UploadFromFileAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    await blobClient.UploadAsync(localFilePath, true);
}

Charger un blob de blocs à partir d’un flux

L’exemple suivant charge un objet blob de blocs en créant un objet Stream et en chargeant ce flux.

public static async Task UploadFromStreamAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, true);
    fileStream.Close();
}

Charger un objet blob de blocs depuis un objet BinaryData

L’exemple suivant charge un objet blob de blocs à partir du chemin d'accès d’un objet BinaryData.

public static async Task UploadFromBinaryDataAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    BinaryReader reader = new BinaryReader(fileStream);

    byte[] buffer = new byte[fileStream.Length];
    reader.Read(buffer, 0, buffer.Length);
    BinaryData binaryData = new BinaryData(buffer);

    await blobClient.UploadAsync(binaryData, true);

    fileStream.Close();
}

Charger un objet blob de blocs à partir d’une chaîne

L’exemple suivant charge un objet blob de blocs à partir d’une chaîne :

public static async Task UploadFromStringAsync(
    BlobContainerClient containerClient,
    string blobName)
{
    BlobClient blobClient = containerClient.GetBlobClient(blobName);
    string blobContents = "Sample blob data";

    await blobClient.UploadAsync(BinaryData.FromString(blobContents), overwrite: true);
}

Charger dans un flux du Stockage Blob

Vous pouvez ouvrir un flux dans le Stockage Blob et écrire dedans. L’exemple suivant crée un fichier zip dans le Stockage Blob et écrit des fichiers dedans. Au lieu de créer un fichier zip dans la mémoire locale, seul un fichier à la fois est en mémoire.

public static async Task UploadToStreamAsync(
    BlobContainerClient containerClient,
    string localDirectoryPath)
{
    string zipFileName = Path.GetFileName(
        Path.GetDirectoryName(localDirectoryPath)) + ".zip";

    BlockBlobClient blockBlobClient = containerClient.GetBlockBlobClient(zipFileName);

    using (Stream stream = await blockBlobClient.OpenWriteAsync(true))
    {
        using (ZipArchive zip = new ZipArchive(stream, ZipArchiveMode.Create, leaveOpen: false))
        {
            foreach (var fileName in Directory.EnumerateFiles(localDirectoryPath))
            {
                using (var fileStream = File.OpenRead(fileName))
                {
                    var entry = zip.CreateEntry(
                        Path.GetFileName(fileName), CompressionLevel.Optimal);
                    using (var innerFile = entry.Open())
                    {
                        await fileStream.CopyToAsync(innerFile);
                    }
                }
            }
        }
    }
}

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 chargement d’un objet blob. Ces options peuvent être paramétrées pour améliorer les performances, améliorer la fiabilité et optimiser les coûts. Les exemples de code suivants montrent comment utiliser BlobUploadOptions pour définir des options de configuration lors de l’appel d’une méthode de chargement.

Spécifier les options de transfert de données lors du 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 BlobUploadOptions 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 UploadWithTransferOptionsAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

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

    var uploadOptions = new BlobUploadOptions()
    {
        TransferOptions = transferOptions
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

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

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

Vous pouvez spécifier des options de validation de transfert pour vous assurer que les données sont 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 BlobUploadOptions. L’exemple de code suivant montre comment créer un BlobUploadOptions 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 chargé.

public static async Task UploadWithChecksumAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    var validationOptions = new UploadTransferValidationOptions
    {
        ChecksumAlgorithm = StorageChecksumAlgorithm.Auto
    };

    var uploadOptions = new BlobUploadOptions()
    {
        TransferValidation = validationOptions
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, uploadOptions);
    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.

Remarque

Si la somme de contrôle spécifiée dans la requête ne correspond pas à la somme de contrôle calculée par le service, l’opération de chargement échoue. L’opération n’est pas retentée à l’utilisation d’une stratégie de nouvelles tentatives par défaut. Dans .NET, un RequestFailedException est levé avec le code d’état 400 et le code d’erreur Md5Mismatch ou Crc64Mismatch (selon l’algorithme utilisé).

Charger avec des balises d’index

Les balises d’index de blob catégorisent les données de votre compte de stockage à l’aide d’attributs de balise clé-valeur. Ces balises sont automatiquement indexées et exposées en tant qu’index multidimensionnel pouvant faire l’objet d’une recherche pour trouver facilement des données. Vous pouvez ajouter des balises à une instance BlobUploadOptions et basculer cette instance vers la méthode UploadAsync.

L’exemple suivant charge un objet blob de blocs avec des étiquettes d’index :

public static async Task UploadBlobWithTagsAsync(
    BlobContainerClient containerClient,
    string blobName)
{
    BlobClient blobClient = containerClient.GetBlobClient(blobName);
    string blobContents = "Sample blob data";

    BlobUploadOptions options = new BlobUploadOptions();
    options.Tags = new Dictionary<string, string>
    {
        { "Sealed", "false" },
        { "Content", "image" },
        { "Date", "2020-04-20" }
    };

    await blobClient.UploadAsync(BinaryData.FromString(blobContents), options);
}

Définir le niveau d’accès d’un objet blob pendant le chargement

Vous pouvez définir le niveau d’accès d’un objet blob lors du chargement à l’aide de la classe BlobUploadOptions . L’exemple de code suivant montre comment définir le niveau d’accès lors du chargement d’un objet blob :

public static async Task UploadWithAccessTierAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlockBlobClient blockBlobClient = containerClient.GetBlockBlobClient(fileName);

    var uploadOptions = new BlobUploadOptions()
    {
        AccessTier = AccessTier.Cool
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blockBlobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

La définition du niveau d’accès est autorisée seulement sur les objets blob de blocs. Vous pouvez définir le niveau d’accès d’un objet blob de blocs sur Hot, Cool, Coldou Archive. Pour définir le niveau d’accès sur Cold, vous devez utiliser une version minimale de la bibliothèque cliente de la version 12.15.0.

Pour en savoir plus sur les niveaux d’accès, consultez Vue générale des niveaux d’accès .

Charger un objet blob de blocs en mettant en lots des blocs et en validant

Vous pouvez avoir un meilleur contrôle sur la répartition des chargements dans des blocs en indexant manuellement des blocs de données individuels. Quand tous les blocs qui composent un blob sont indexés, vous pouvez les valider dans le Stockage Blob. Vous pouvez utiliser cette approche pour améliorer les performances en chargeant des blocs en parallèle.

public static async Task UploadBlocksAsync(
    BlobContainerClient blobContainerClient,
    string localFilePath,
    int blockSize)
{
    string fileName = Path.GetFileName(localFilePath);
    BlockBlobClient blobClient = blobContainerClient.GetBlockBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    ArrayList blockIDArrayList = new ArrayList();
    byte[] buffer;

    var bytesLeft = (fileStream.Length - fileStream.Position);

    while (bytesLeft > 0)
    {
        if (bytesLeft >= blockSize)
        {
            buffer = new byte[blockSize];
            await fileStream.ReadAsync(buffer, 0, blockSize);
        }
        else
        {
            buffer = new byte[bytesLeft];
            await fileStream.ReadAsync(buffer, 0, Convert.ToInt32(bytesLeft));
            bytesLeft = (fileStream.Length - fileStream.Position);
        }

        using (var stream = new MemoryStream(buffer))
        {
            string blockID = Convert.ToBase64String(
                Encoding.UTF8.GetBytes(Guid.NewGuid().ToString()));

            blockIDArrayList.Add(blockID);
            await blobClient.StageBlockAsync(blockID, stream);
        }
        bytesLeft = (fileStream.Length - fileStream.Position);
    }

    string[] blockIDArray = (string[])blockIDArrayList.ToArray(typeof(string));

    await blobClient.CommitBlockListAsync(blockIDArray);
}

Ressources

Pour en savoir plus sur le 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 le chargement d’objets blob utilisent les opérations d’API REST suivantes :

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.