Lister les blobs avec Go

Cet article montre comment lister les blobs en utilisant le module client stockage Azure pour Go.

Prérequis

• Abonnement Azure : créez-en un gratuitement
• Compte de stockage Azure : créez un compte de stockage
• Accédez à 1,18+

Paramétrer votre environnement

Si vous n’avez aucun projet existant, cette section montre comment configurer un projet pour qu’il fonctionne avec le module client du Stockage Blob Azure pour Go. Les étapes incluent l’installation du module, l’ajout de chemins d’accès import et la création d’un objet client autorisé. Pour plus d’informations, consultez Bien démarrer avec Stockage Blob Azure et Go.

Installer des modules

Installez le module azblob à l’aide de la commande suivante :

go get github.com/Azure/azure-sdk-for-go/sdk/storage/azblob

Pour vous authentifier auprès de Microsoft Entra ID (recommandé), installez le module azidentity à l’aide de la commande suivante :

go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

Ajouter des chemins d’importation

Dans votre fichier de code, ajoutez les chemins d’importation suivants :

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
)

Ces chemins d’importation représentent le minimum nécessaire pour démarrer. Certains exemples de code de cet article peuvent nécessiter des chemins d’importation supplémentaires. Pour plus d’informations et des exemples d’utilisation spécifiques, consultez Exemples de code.

Créer un objet client

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

func getServiceClientTokenCredential(accountURL string) *azblob.Client {
    // Create a new service client with token credential
    credential, err := azidentity.NewDefaultAzureCredential(nil)
    handleError(err)

    client, err := azblob.NewClient(accountURL, credential, nil)
    handleError(err)

    return client
}

Autorisation

Le mécanisme d’autorisation doit disposer des autorisations nécessaires pour téléverser 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, consultez le guide d’autorisation pour Lister les blobs (API REST).

À propos des options de listage des blobs

Quand vous listez les blobs dans votre code, vous pouvez spécifier de nombreuses options pour gérer la façon dont les résultats sont retournés par le 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 blobs dans un conteneur en utilisant une liste plate, appelez la méthode suivante :

• NewListBlobsFlatPager

Pour lister les blobs dans un conteneur en utilisant une liste hiérarchique, appelez la méthode suivante depuis un objet client conteneur :

• NewListBlobsHierarchyPager

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

Par défaut, une opération de dressage de liste renvoie jusqu’à 5 000 résultats à la fois. Pour retourner un ensemble plus petit de résultats, fournissez une valeur autre que zéro pour le champ MaxResults dans ListBlobsFlatOptions ou ListBlobsHierarchyOptions.

Filtrez les résultats avec un préfixe

Pour filtrer la liste des objets blob retournée, spécifiez une chaîne ou un caractère pour le champ Prefix dans ListBlobsFlatOptions ou ListBlobsHierarchyOptions. 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.

Inclure des métadonnées de blob ou d’autres informations

Pour inclure les métadonnées des blobs dans les résultats, définissez le champ Metadata sur true dans ListBlobsInclude. stockage Azure inclut des métadonnées avec chaque blob retourné, vous n’avez donc pas besoin de récupérer séparément les métadonnées du blob.

Consultez ListBlobsInclude pour obtenir des options supplémentaires permettant d’inclure des instantanés, des versions, des étiquettes d’index de blob et d’autres informations dans les résultats.

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 d’énumération renvoie les blobs sous forme de liste plate. Dans une liste plate, les blobs ne sont pas organisés par répertoire virtuel.

L’exemple suivant répertorie les objets blob dans le conteneur spécifié avec un listage plat. Cet exemple comprend des instantanés de blob et des versions de blob, le cas échéant :

func listBlobsFlat(client *azblob.Client, containerName string) {
    // List the blobs in the container
    pager := client.NewListBlobsFlatPager(containerName, &azblob.ListBlobsFlatOptions{
        Include: azblob.ListBlobsInclude{Snapshots: true, Versions: true},
    })

    fmt.Println("List blobs flat:")
    for pager.More() {
        resp, err := pager.NextPage(context.TODO())
        handleError(err)

        for _, blob := range resp.Segment.BlobItems {
            fmt.Println(*blob.Name)
        }
    }
}

La sortie obtenue ressemble à ceci :

List blobs flat:
file4.txt
folderA/file1.txt
folderA/file2.txt
folderA/folderB/file3.txt

L’exemple suivant répertorie les blobs d’un conteneur commençant par un préfixe spécifique :

func listBlobsFlatOptions(client *azblob.Client, containerName string, prefix string) {
    // List the blobs in the container with a prefix
    pager := client.NewListBlobsFlatPager(containerName, &azblob.ListBlobsFlatOptions{
        Prefix: to.Ptr(prefix),
    })

    fmt.Println("List blobs with prefix:")
    for pager.More() {
        resp, err := pager.NextPage(context.TODO())
        handleError(err)

        for _, blob := range resp.Segment.BlobItems {
            fmt.Println(*blob.Name)
        }
    }
}

Lorsque vous passez une chaîne de préfixes « sample », la sortie est similaire à :

List blobs with prefix:
sample-blob1.txt
sample-blob2.txt
sample-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 manière hiérarchique, utilisez la méthode suivante :

• NewListBlobsHierarchyPager

L’exemple suivant répertorie les objets blob dans le conteneur spécifié en utilisant une liste hiérarchique. Dans cet exemple, le paramètre de préfixe est initialement défini sur une chaîne vide pour répertorier tous les objets blob d’un conteneur. Cet exemple appelle ensuite l’opération de liste de manière récurrente pour parcourir la hiérarchie de répertoire virtuel et répertorier les objets blob.

func listBlobsHierarchy(client *azblob.Client, containerName string, prefix string) {
    // Reference the container as a client object
    containerClient := client.ServiceClient().NewContainerClient(containerName)

    pager := containerClient.NewListBlobsHierarchyPager("/", &container.ListBlobsHierarchyOptions{
        Prefix:     to.Ptr(prefix),
        MaxResults: to.Ptr(int32(1)), // MaxResults set to 1 for demonstration purposes
    })

    for pager.More() {
        resp, err := pager.NextPage(context.TODO())
        handleError(err)

        if resp.Segment.BlobPrefixes != nil {
            for _, prefix := range resp.Segment.BlobPrefixes {
                fmt.Println("Virtual directory prefix:", *prefix.Name)

                // Recursively list blobs in the prefix
                listBlobsHierarchy(client, containerName, *prefix.Name)
            }
        }

        for _, blob := range resp.Segment.BlobItems {
            fmt.Println("Blob:", *blob.Name)
        }
    }
}

La sortie obtenue ressemble à :

Virtual directory prefix: folderA/
Blob: folderA/file1.txt
Blob: folderA/file2.txt
Blob: folderA/file3.txt
Virtual directory prefix: folderA/folderB/
Blob: folderA/folderB/file1.txt
Blob: folderA/folderB/file2.txt
Blob: folderA/folderB/file3.txt

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 Go décode Apache Arrow en coulisses et renvoie toujours les mêmes BlobItem valeurs. 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 par Apache Arrow, définissez le ResponseFormat champ ListBlobsFlatOptions sur StorageResponseFormatArrow, puis passez les options à NewListBlobsFlatPager. Lorsque vous utilisez le format de sortie Apache Arrow, vous pouvez également définir les champs StartFrom et EndBefore pour contrôler la plage des chemins renvoyés.

L’exemple suivant liste les blobs dans un conteneur et demande les résultats au format Apache Arrow :

import (
    "context"

    "github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/container"
)

pager := client.NewListBlobsFlatPager("sample-container", &azblob.ListBlobsFlatOptions{
    Prefix:         to.Ptr("folderA/"),
    ResponseFormat: container.StorageResponseFormatArrow,
})

for pager.More() {
    resp, err := pager.NextPage(context.TODO())
    handleError(err)

    for _, blob := range resp.Segment.BlobItems {
        fmt.Println(*blob.Name)
    }
}

Ressources

Pour découvrir plus d’informations sur l’établissement d’une liste d’objets blob en utilisant le module client Stockage Blob Azure pour Go, consultez les ressources suivantes.

Exemples de code

• Afficher des exemples de code de cet article (GitHub)

Opérations de l'API REST

Le Kit de développement logiciel (SDK) Azure for Go 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 Go 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 du module client

• Documentation de référence sur les modules clients
• Code source du module client
• Package (pkg.go.dev)

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 sur Stockage Blob pour Go. Pour en savoir plus, consultez la liste complète des articles du guide du développeur dans Générer votre application Go.