Répertorier les objets blob avec JavaScript

Article
11/05/2024

Cet article montre comment répertorier des objets blob à l’aide de la Bibliothèque de client Stockage Azure pour JavaScript.

Prérequis

Les exemples de cet article supposent que vous disposez déjà d'un projet configuré pour fonctionner avec la bibliothèque client Azure Blob Storage pour JavaScript. Pour en savoir plus sur la configuration de votre projet, y compris l'installation de packages, l'importation de modules et la création d'un objet client autorisé pour travailler avec des ressources de données, consultez Démarrer avec Stockage Blob Azure et JavaScript.
Le mécanisme d’autorisation doit disposer des autorisations nécessaires pour répertorier les objets blob. Pour en savoir plus, consultez les conseils d’autorisation pour l’opération d’API REST suivante :
- Lister les objets blob

À propos des options de liste d’objets blob

Quand vous listez les blobs dans votre code, vous pouvez spécifier plusieurs 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 également répertorier les blobs dans une structure de liste plate, ou hiérarchiquement. Une liste hiérarchique retourne les blobs comme s’ils étaient organisés en dossiers.

Pour répertorier les objets blob dans un conteneur en utilisant une liste plate, appelez la méthode suivante :

ContainerClient.listBlobsFlat

Pour répertorier les objets blob dans un conteneur à l’aide d’une liste hiérarchique, appelez la méthode suivante :

ContainerClient.listBlobsByHierarchy

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 JavaScript.

Filtrez les résultats avec un préfixe

Pour filtrer la liste des objets blob, spécifiez une chaîne pour la propriété prefix dans les ContainerListBlobsOptions. 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. Par exemple, le passage de la chaîne de préfixe sample- retourne uniquement les blobs dont le nom commence par sample-.

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

Pour inclure les métadonnées de blobs avec les résultats, définissez la propriété includeMetadata sur true dans le cadre de ContainerListBlobsOptions. Vous pouvez également inclure des instantanés, des balises ou des versions dans les résultats en définissant la propriété appropriée sur true.

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 objets blob dans le conteneur spécifié à l’aide d’une liste plate. Cet exemple inclut des instantanés de blobs et des métadonnées de blobs, s’ils existent :

JavaScript
TypeScript

async function listBlobsFlat(containerClient) {

  const maxPageSize = 2;

  // Some options for filtering results
  const listOptions = {
    includeMetadata: true,
    includeSnapshots: true,
    prefix: '' // Filter results by blob name prefix
  };

  console.log("Blobs flat list (by page):");
  for await (const response of containerClient
    .listBlobsFlat(listOptions)
    .byPage({ maxPageSize })) {
    console.log("- Page:");
    if (response.segment.blobItems) {
      for (const blob of response.segment.blobItems) {
        console.log(`  - ${blob.name}`);
      }
    }
  }
}

async function listBlobsFlat(
  containerClient: ContainerClient
): Promise<void> {
  
  const maxPageSize = 2;

  // Some options for filtering results
  const listOptions: ContainerListBlobsOptions = {
    includeMetadata: true,
    includeSnapshots: true,
    prefix: '' // Filter results by blob name prefix
  };

  console.log("Blobs flat list(by page):");
  for await (const response of containerClient
    .listBlobsFlat(listOptions)
    .byPage({ maxPageSize })) {
    console.log("- Page:");
    if (response.segment.blobItems) {
      for (const blob of response.segment.blobItems) {
        console.log(`  - ${blob.name}`);
      }
    }
  }
}

Exemple de sortie :

Blobs flat list (by page):
- Page:
  - a1
  - a2
- Page:
  - folder1/b1
  - folder1/b2
- Page:
  - folder2/sub1/c
  - folder2/sub1/d

Remarque

L’exemple de sortie affiché suppose que vous disposez d’un compte de stockage avec un espace de noms plat. Si vous avez activé la fonctionnalité d’espace de noms hiérarchique pour votre compte de stockage, les répertoires ne sont pas virtuels. Au lieu de cela, ce sont des objets concrets et indépendants. Par conséquent, les répertoires apparaissent dans la liste sous forme d’objets blob de longueur nulle.

Pour obtenir une autre option de référencement lors de l’utilisation d’un espace de noms hiérarchique, consultez la section Afficher le contenu du répertoire (Azure Data Lake Storage).

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 :

BlobContainerClient.listBlobsByHierarchy

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.

JavaScript
TypeScript

// Recursively list virtual folders and blobs
async function listBlobHierarchical(containerClient, delimiter='/') {
  
  const maxPageSize = 20;

  // Some options for filtering list
  const listOptions = {
    prefix: '' // Filter results by blob name prefix   
  };

  let i = 1;
  console.log(`Folder ${delimiter}`);

  for await (const response of containerClient
    .listBlobsByHierarchy(delimiter, listOptions)
    .byPage({ maxPageSize })) {

    console.log(`   Page ${i++}`);
    const segment = response.segment;

    if (segment.blobPrefixes) {

      // Do something with each virtual folder
      for await (const prefix of segment.blobPrefixes) {

        // Build new delimiter from current and next
        await listBlobHierarchical(containerClient, `${delimiter}${prefix.name}`);
      }
    }

    for (const blob of response.segment.blobItems) {

      // Do something with each blob
      console.log(`\tBlobItem: name - ${blob.name}`);
    }
  }
}

// Recursively list virtual folders and blobs
async function listBlobHierarchical(
  containerClient: ContainerClient,
  delimiter = '/'
): Promise<void> {

  const maxPageSize = 20;

  // Some options for filtering results
  const listOptions: ContainerListBlobsOptions = {
    prefix: '' // Filter results by blob name prefix
  };

  let i = 1;
  console.log(`Folder ${delimiter}`);

  for await (const response of containerClient
    .listBlobsByHierarchy(delimiter, listOptions)
    .byPage({ maxPageSize })) {
    console.log(`   Page ${i++}`);
    const segment = response.segment;

    if (segment.blobPrefixes) {
      // Do something with each virtual folder
      for await (const prefix of segment.blobPrefixes) {
        // Build new delimiter from current and next
        await listBlobHierarchical(
          containerClient,
          `${delimiter}${prefix.name}`
        );
      }
    }

    for (const blob of response.segment.blobItems) {
      // Do something with each blob
      console.log(`\tBlobItem: name - ${blob.name}`);
    }
  }
}

Exemple de sortie :

Folder /
   Page 1
        BlobItem: name - a1
        BlobItem: name - a2
   Page 2
Folder /folder1/
   Page 1
        BlobItem: name - folder1/b1
        BlobItem: name - folder1/b2
Folder /folder2/
   Page 1
Folder /folder2/sub1/
   Page 1
        BlobItem: name - folder2/sub1/c
        BlobItem: name - folder2/sub1/d
   Page 2
        BlobItem: name - folder2/sub1/e

Notes

Les instantanés d’objets blob ne peuvent pas être listés dans une opération de création de liste hiérarchique.

Ressources

Pour en savoir comment lister les objets blob à l’aide de la bibliothèque de client Stockage Blob Azure pour JavaScript, consultez les ressources suivantes.

Exemples de code

Voir les exemples de code JavaScript et TypeScript de cet article (GitHub)

Opérations de l'API REST

Le Kit de développement logiciel (SDK) Azure pour JavaScript 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 JavaScript familiers. Les méthodes de bibliothèque de client pour lister les objets blob utilisent l’opération d’API REST suivante :

List Blobs (REST API)

Partage via