Répertorier les objets blob avec JavaScript

Article
08/21/2023

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 Stockage Blob Azure 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 plus d’informations, 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

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 é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 lister les objets blob d’un compte de stockage, créez un ContainerClient puis appelez l’une des méthodes suivantes :

ContainerClient.listBlobsByHierarcy
ContainerClient.listBlobsFlat

Vous trouverez les fonctionnalités associées dans les méthodes suivantes :

BlobServiceClient.findBlobsByTag
ContainerClient.findBlobsByTag

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.

const listOptions = {
    includeCopy: false,                 // include metadata from previous copies
    includeDeleted: false,              // include deleted blobs 
    includeDeletedWithVersions: false,  // include deleted blobs with versions
    includeLegalHold: false,            // include legal hold
    includeMetadata: true,              // include custom metadata
    includeSnapshots: true,             // include snapshots
    includeTags: true,                  // include indexable tags
    includeUncommitedBlobs: false,      // include uncommitted blobs
    includeVersions: false,             // include all blob version
    prefix: ''                          // filter by blob name prefix
};

Retourner les métadonnées

Vous pouvez retourner des métadonnées d’objet blob avec les résultats en spécifiant la propriété includeMetadata dans les options de liste.

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 objets blob 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.

async function listBlobsFlatWithPageMarker(containerClient) {

  // page size - artificially low as example
  const maxPageSize = 2;

  let i = 1;
  let marker;

  // some options for filtering list
  const listOptions = {
    includeMetadata: false,
    includeSnapshots: false,
    includeTags: false,
    includeVersions: false,
    prefix: ''
  };

  let iterator = containerClient.listBlobsFlat(listOptions).byPage({ maxPageSize });
  let response = (await iterator.next()).value;

  // Prints blob names
  for (const blob of response.segment.blobItems) {
    console.log(`Flat listing: ${i++}: ${blob.name}`);
  }

  // Gets next marker
  marker = response.continuationToken;

  // Passing next marker as continuationToken    
  iterator = containerClient.listBlobsFlat().byPage({ 
      continuationToken: marker, 
      maxPageSize: maxPageSize * 2 
  });
  response = (await iterator.next()).value;

  // Prints next blob names
  for (const blob of response.segment.blobItems) {
    console.log(`Flat listing: ${i++}: ${blob.name}`);
  }
}

Exemple de sortie :

Flat listing: 1: a1
Flat listing: 2: a2
Flat listing: 3: folder1/b1
Flat listing: 4: folder1/b2
Flat listing: 5: folder2/sub1/c
Flat listing: 6: folder2/sub1/d

Notes

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 Gen2).

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 répertorier les objets blob de façon hiérarchique, appelez la méthode BlobContainerClient.listBlobsByHierarchy.

L’exemple suivant liste les objets blob dans le conteneur spécifié à l’aide d’une liste hiérarchique, avec une taille de segment facultative spécifiée, et écrit le nom de l’objet blob dans la fenêtre de console.

// Recursively list virtual folders and blobs
// Pass an empty string for prefixStr to list everything in the container
async function listBlobHierarchical(containerClient, prefixStr) {

  // page size - artificially low as example
  const maxPageSize = 2;

  // some options for filtering list
  const listOptions = {
    includeMetadata: false,
    includeSnapshots: false,
    includeTags: false,
    includeVersions: false,
    prefix: prefixStr
  };

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

  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 prefix from current virtual folder
        await listBlobHierarchical(containerClient, 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.

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 :