This article shows how to list blobs using theAzure Storage client library for JavaScript.

Prerequisites

• The examples in this article assume you already have a project set up to work with the Azure Blob Storage client library for JavaScript. To learn about setting up your project, including package installation, importing modules, and creating an authorized client object to work with data resources, seeGet started with Azure Blob Storage and JavaScript.
• Theauthorization mechanism must have permissions to list blobs. To learn more, see the authorization guidance for the following REST API operation:
  • List Blobs

About blob listing options

When you list blobs from your code, you can specify several options to manage how results are returned from Azure Storage. You can specify the number of results to return in each set of results, and then retrieve the subsequent sets. You can specify a prefix to return blobs whose names begin with that character or string. And you can list blobs in a flat listing structure, or hierarchically. A hierarchical listing returns blobs as though they were organized into folders.

To list the blobs in a container using a flat listing, call the following method:

• ContainerClient.listBlobsFlat

To list the blobs in a container using a hierarchical listing, call the following method:

• ContainerClient.listBlobsByHierarchy

Manage how many results are returned

By default, a listing operation returns up to 5000 results at a time, but you can specify the number of results that you want each listing operation to return. The examples presented in this article show you how to return results in pages. To learn more about pagination concepts, seePagination with the Azure SDK for JavaScript.

Filter results with a prefix

To filter the list of blobs, specify a string for theprefix property inContainerListBlobsOptions. The prefix string can include one or more characters. Azure Storage then returns only the blobs whose names start with that prefix. For example, passing the prefix stringsample- returns only blobs whose names start withsample-.

Include blob metadata or other information

To include blob metadata with the results, set theincludeMetadata property totrue as part ofContainerListBlobsOptions. You can also include snapshots, tags, or versions in the results by setting the appropriate property totrue.

Flat listing versus hierarchical listing

Blobs in Azure Storage are organized in a flat paradigm, rather than a hierarchical paradigm (like a classic file system). However, you can organize blobs intovirtual directories in order to mimic a folder structure. A virtual directory forms part of the name of the blob and is indicated by the delimiter character.

To organize blobs into virtual directories, use a delimiter character in the blob name. The default delimiter character is a forward slash (/), but you can specify any character as the delimiter.

If you name your blobs using a delimiter, then you can choose to list blobs hierarchically. For a hierarchical listing operation, Azure Storage returns any virtual directories and blobs beneath the parent object. You can call the listing operation recursively to traverse the hierarchy, similar to how you would traverse a classic file system programmatically.

Use a flat listing

By default, a listing operation returns blobs in a flat listing. In a flat listing, blobs aren't organized by virtual directory.

The following example lists the blobs in the specified container using a flat listing. This example includes blob snapshots and blob metadata, if they exist:

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

The sample output is similar to:

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

Use a hierarchical listing

When you call a listing operation hierarchically, Azure Storage returns the virtual directories and blobs at the first level of the hierarchy.

To list blobs hierarchically, use the following method:

• BlobContainerClient.listBlobsByHierarchy

The following example lists the blobs in the specified container using a hierarchical listing. In this example, the prefix parameter is initially set to an empty string to list all blobs in the container. The example then calls the listing operation recursively to traverse the virtual directory hierarchy and list blobs.

// Recursively list virtual folders and blobsasync 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 blobsasync 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}`);    }  }}

The sample output is similar to:

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

Resources

To learn more about how to list blobs using the Azure Blob Storage client library for JavaScript, see the following resources.

Code samples

• ViewJavaScript andTypeScript code samples from this article (GitHub)

REST API operations

The Azure SDK for JavaScript contains libraries that build on top of the Azure REST API, allowing you to interact with REST API operations through familiar JavaScript paradigms. The client library methods for listing blobs use the following REST API operation:

• List Blobs (REST API)

Client library resources

• Client library reference documentation
• Client library source code
• Package (npm)

See also

• Enumerating Blob Resources
• Blob versioning