Lister les objets blob avec .NET

Cet article montre comment lister les blobs en utilisant la bibliothèque client stockage Azure pour .NET.

Prérequis

• Abonnement Azure : créez-en un gratuitement
• Compte de stockage Azure : créez un compte de stockage
• Dernière version du Kit de développement logiciel (SDK) .NET pour votre système d’exploitation. Veillez à disposer du Kit de développement logiciel (SDK), et non du runtime.

Configurer 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 en utilisant 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 les ressources de données.

Autorisation

Le mécanisme d’autorisation doit disposer des autorisations nécessaires pour répertorier un blob. Pour l’autorisation avec Microsoft Entra ID (recommandé), vous avez besoin du rôle intégré Azure RBAC Storage Blob Data Reader ou supérieur. Pour en savoir plus, veuillez consulter l’aide sur l’autorisation pour Répertorier des objets blob (API REST).

À propos des options de liste de blobs

Lorsque vous listez les objets blob de votre code, vous pouvez spécifier un certain nombre d’options pour gérer la façon dont les résultats sont retournés à partir du stockage Azure. Vous pouvez spécifier le nombre de résultats à retourner dans chaque ensemble de résultats, puis récupérer les ensembles suivants. Vous pouvez spécifier un préfixe pour retourner les blobs dont le nom commence par ce caractère ou cette chaîne. Vous pouvez lister les blobs dans une structure de listes plates ou hiérarchiquement. Une liste hiérarchique retourne les blobs comme s’ils étaient organisés en dossiers.

Pour lister les objets blob dans un compte de stockage, appelez l’une des méthodes suivantes :

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

Gérez le nombre de résultats retournés

Par défaut, une opération de liste renvoie jusqu’à 5 000 résultats à la fois, mais vous pouvez spécifier le nombre de résultats que chaque opération de liste doit renvoyer. Les exemples présentés dans cet article vous montrent comment restituer les résultats en pages. Pour en savoir plus sur les concepts de pagination, consultez Pagination avec le kit de développement logiciel (SDK) Azure pour .NET.

Filtrez les résultats avec un préfixe

Pour filtrer la liste de blobs, spécifiez une chaîne pour le paramètre prefix. La chaîne de préfixe peut inclure un ou plusieurs caractères. Le stockage Azure retourne alors uniquement les objets blob dont les noms commencent par ce préfixe.

Retourner les métadonnées

Vous pouvez retourner des métadonnées de blob avec les résultats en spécifiant la valeur des métadonnées pour l’énumération BlobTraits.

Création d’une liste plate ou d’une liste hiérarchique

Les objets blob dans le stockage Azure sont organisés en paradigme plat, plutôt qu’en paradigme hiérarchique (comme un système de fichiers standard). Toutefois, vous pouvez organiser les blobs en répertoires virtuels afin de simuler une structure de dossiers. Un répertoire virtuel fait partie du nom du blob et est indiqué par le caractère délimiteur.

Pour organiser les objets blob en répertoires virtuels, utilisez un caractère délimiteur dans les noms des objets blob. Le caractère délimiteur par défaut est une barre oblique (/), mais vous pouvez spécifier n’importe quel caractère comme délimiteur.

Si vous nommez vos objets blob en utilisant un délimiteur, vous pouvez choisir de lister les objets blob hiérarchiquement. Pour une opération de création de liste hiérarchique, le stockage Azure retourne tous les répertoires virtuels et les objets blob figurant sous l’objet parent. Vous pouvez appeler l’opération de création de liste de manière récursive pour parcourir la hiérarchie, de la même façon que vous parcourez un système de fichiers standard par programmation.

Utiliser une liste plate

Par défaut, une opération de création de liste retourne les objets blob dans une liste plate. Dans une liste plate, les blobs ne sont pas organisés par répertoire virtuel.

L’exemple suivant liste les blobs dans le conteneur spécifié en utilisant une liste plate, avec une taille de segment optionnelle spécifiée, et écrit le nom du blob dans une fenêtre de 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;
    }
}

Exemple de sortie :

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

Utiliser une liste hiérarchique

Lorsque vous appelez une opération de création de liste hiérarchique, le stockage Azure retourne les répertoires virtuels et les objets blob figurant au premier niveau de la hiérarchie.

Pour lister les blobs de façon hiérarchique, appelez la méthode BlobContainerClient.GetBlobsByHierarchy ou la méthode BlobContainerClient.GetBlobsByHierarchyAsync .

L’exemple suivant liste les blobs dans le conteneur spécifié en utilisant une liste hiérarchique, avec une taille de segment optionnelle spécifiée, et écrit le nom du blob sur la fenêtre de la 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;
    }
}

Exemple de sortie :

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

Répertorier les versions ou les instantanés de blobs

Pour lister les versions ou les instantanés de blob, spécifiez le paramètre BlobStates avec le champ Version ou Instantané. Le service retourne des versions et des instantanés du plus ancien au plus récent.

L’exemple de code suivant montre comment lister les versions de 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;
    }
}

Liste des blobs au format Apache Arrow (aperçu)

Cette capacité est construite sur l’API existante List Blobs . Au lieu d’utiliser le XML par défaut, il utilise le format compact et colonnaire Apache Arrow comme format de réponse sur le fil. Vous l’activez en définissant une seule option lors de l’appel de listage des conteneurs. Le SDK .NET décode Apache Arrow en coulisses et renvoie toujours les mêmes BlobItem objets. Cette approche améliore le débit des listes et réduit le CPU côté client lors de l’énumération de grands conteneurs. Cela préserve le contrat de réponse sur lequel reposent les demandes.

Pour demander des résultats formatés en flèche Apache, mettez la propriété ResponseFormat de GetBlobsOptions sur StorageResponseFormat.Arrow, puis passez les options à la surcharge BlobContainerClient.GetBlobs qui accepte GetBlobsOptions. Lorsque vous utilisez la sortie Apache Arrow, vous pouvez aussi définir les StartFrom propriétés et EndBefore pour contrôler la plage de chemins retournés.

L’exemple suivant liste les blobs dans un conteneur et demande les résultats au format 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);
}

Ressources

Pour en savoir plus sur la façon de lister les blobs en utilisant la bibliothèque client Stockage Blob Azure pour .NET, consultez les ressources suivantes.

Opérations de l'API REST

Le Kit de développement logiciel (SDK) Azure pour .NET contient des bibliothèques qui s’appuient à l’API Azure REST. En utilisant ces bibliothèques, vous pouvez interagir avec les opérations de l’API REST via des paradigmes .NET familiers. Les méthodes de bibliothèque de client pour lister les objets blob utilisent l’opération d’API REST suivante :

• Lister les blobs (API REST)

Ressources de bibliothèque cliente

• Documentation de référence sur la bibliothèque cliente
• Code source de la bibliothèque de client
• Package (NuGet)

Voir aussi

• Énumération des ressources d’objets blob
• Contrôle de version des blobs

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.