List blob containers with TypeScript

  • Article

When you list the containers in an Azure Storage account from your code, you can specify a number of options to manage how results are returned from Azure Storage. This article shows how to list containers using the Azure 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, see Get started with Azure Blob Storage and TypeScript.
  • The authorization mechanism must have permissions to list blob containers. To learn more, see the authorization guidance for the following REST API operation:

About container listing options

To list containers in your storage account, create a BlobServiceClient object then call the following method:

List containers with optional prefix

By default, a listing operation returns up to 5000 results at a time.

The BlobServiceClient.listContainers returns a list of ContainerItem objects. Use the containerItem.name to create a ContainerClient in order to get a more complete ContainerProperties object.

// return up to 5000 containers
async function listContainers(
  blobServiceClient: BlobServiceClient,
  containerNamePrefix: string
): Promise<void> {
  const options: ServiceListContainersOptions = {
    includeDeleted: false,
    includeMetadata: true,
    includeSystem: true,
    prefix: containerNamePrefix
  };

  for await (const containerItem of blobServiceClient.listContainers(options)) {
    // ContainerItem
    console.log(`For-await list: ${containerItem.name}`);

    // ContainerClient
    const containerClient: ContainerClient =
      blobServiceClient.getContainerClient(containerItem.name);

    // ... do something with container
    // containerClient.listBlobsFlat({    includeMetadata: true,
    // includeSnapshots: false,
    // includeTags: true,
    // includeVersions: false,
    // prefix: ''});
  }
}

List containers with paging

To return a smaller set of results, provide a nonzero value for the size of the page of results to return.

If your storage account contains more than 5000 containers, or if you have specified a page size such that the listing operation returns a subset of containers in the storage account, then Azure Storage returns a continuation token with the list of containers. A continuation token is an opaque value that you can use to retrieve the next set of results from Azure Storage.

In your code, check the value of the continuation token to determine whether it is empty. When the continuation token is empty, then the set of results is complete. If the continuation token is not empty, then call the listing method again, passing in the continuation token to retrieve the next set of results, until the continuation token is empty.

async function listContainersWithPagingMarker(
  blobServiceClient: BlobServiceClient
) {
  // add prefix to filter list
  const containerNamePrefix = '';

  // page size
  const maxPageSize = 2;

  const options: ServiceListContainersOptions = {
    includeDeleted: false,
    includeMetadata: true,
    includeSystem: true,
    prefix: containerNamePrefix
  };

  let i = 1;

  let iterator = blobServiceClient
    .listContainers(options)
    .byPage({ maxPageSize });
  let response = (await iterator.next()).value;

  // Prints 2 container names
  if (response.containerItems) {
    for (const container of response.containerItems) {
      console.log(`IteratorPaged: Container ${i++}: ${container.name}`);
    }
  }

  // Gets next marker
  const marker = response.continuationToken;

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

  // Print next 4 container names
  if (response.containerItems) {
    for (const container of response.containerItems) {
      console.log(`Container ${i++}: ${container.name}`);
    }
  }
}

Use the options parameter to the listContainers method to filter results with a prefix.

Filter results with a prefix

To filter the list of containers, specify a string for the prefix property. The prefix string can include one or more characters. Azure Storage then returns only the containers whose names start with that prefix.

async function listContainers(
  blobServiceClient: BlobServiceClient,
  containerNamePrefix: string
) {

  const options: ServiceListContainersOptions = {
    includeDeleted: false,
    includeMetadata: true,
    includeSystem: true,

    // filter by prefix
    prefix: containerNamePrefix
  };

  for await (const containerItem of blobServiceClient.listContainers(options)) {


    // do something with containerItem

  }
}

Include metadata in results

To return container metadata with the results, specify the metadata value for the BlobContainerTraits enum. Azure Storage includes metadata with each container returned, so you do not need to fetch the container metadata as a separate operation.

async function listContainers(
  blobServiceClient: BlobServiceClient,
  containerNamePrefix: string
) {

  const options: ServiceListContainersOptions = {
    includeDeleted: false,
    includeSystem: true,
    prefix: containerNamePrefix,

    // include metadata
    includeMetadata: true,
  };

  for await (const containerItem of blobServiceClient.listContainers(options)) {

    // do something with containerItem

  }
}

Resources

To learn more about listing containers using the Azure Blob Storage client library for JavaScript, see the following resources.

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 containers use the following REST API operation:

Code samples

Client library resources

See also