Harmony list buckets - Object Storage Service - Alibaba Cloud Documentation Center

A bucket is a container that stores objects. All objects are stored in a bucket. You can list buckets that meet specific conditions across all regions in your Alibaba Cloud account. The listed buckets are sorted alphabetically.

Precautions

For more information about OSS-supported regions and their Endpoints, see Regions and Endpoints.
To list buckets, you must have the oss:ListBuckets permission. For more information, see Grant custom access policies to RAM users.
The following code lists buckets across all regions in your Alibaba Cloud account. This operation does not support listing buckets in a specific region. The result is not affected by the region of the specified endpoint.

Sample code

The following code shows how to list all buckets across all regions in your Alibaba Cloud account.

import Client, { RequestError } from '@aliyun/oss';

// Create an OSS client instance.
const client = new Client({
  // Replace with the Access Key ID of the Security Token Service (STS) temporary access credential.
  accessKeyId: 'yourAccessKeyId',
  // Replace with the Access Key Secret of the STS temporary access credential.
  accessKeySecret: 'yourAccessKeySecret',
  // Replace with the Security Token of the STS temporary access credential.
  securityToken: 'yourSecurityToken',
});

// List all buckets.
const listBuckets = async () => {
  try {
    // Call the listBuckets method to list all buckets.
    const res = await client.listBuckets({});

    // Print the result.
    console.log(JSON.stringify(res));
  } catch (err) {
    // Catch and handle request errors.
    if (err instanceof RequestError) {
      console.log('Error code: ', err.code); // Error code
      console.log('Error message: ', err.message); // Error description
      console.log('Request ID: ', err.requestId); // Unique identifier of the request
      console.log('HTTP status code: ', err.status); // HTTP response status code
      console.log('Error category: ', err.ec); // Error category
    } else {
      console.log('Unknown error: ', err); // Error that is not of the RequestError type
    }
  }
};

// Call the function to list all buckets.
listBuckets();

Other scenarios

List buckets with a specified prefix

The following code shows how to list buckets that have the prefix `bucketNamePrefix` across all regions in your Alibaba Cloud account.

import Client, { RequestError } from '@aliyun/oss';

// Create an OSS client instance.
const client = new Client({
  // Replace with the Access Key ID of the STS temporary access credential.
  accessKeyId: 'yourAccessKeyId',
  // Replace with the Access Key Secret of the STS temporary access credential.
  accessKeySecret: 'yourAccessKeySecret',
  // Replace with the Security Token of the STS temporary access credential.
  securityToken: 'yourSecurityToken',
});

// List buckets that start with a specific prefix.
const listBucketsWithPrefix = async () => {
  try {
    // Call the listBuckets method and specify the prefix parameter to filter bucket names.
    const res = await client.listBuckets({
      prefix: 'bucketNamePrefix' // Specify the prefix for bucket names.
    });

    // Print the result.
    console.log(JSON.stringify(res));
  } catch (err) {
    if (err instanceof RequestError) {
      console.log('Error code: ', err.code);
      console.log('Error message: ', err.message);
      console.log('Request ID: ', err.requestId);
      console.log('HTTP status code: ', err.status);
      console.log('Error category: ', err.ec);
    } else {
      console.log('Unknown error: ', err);
    }
  }
};

// Call the function to list buckets that start with a specific prefix.
listBucketsWithPrefix();

List all buckets using a pagination token (marker)

The following code shows how to list all buckets using a pagination token (marker).

import Client, { RequestError } from '@aliyun/oss';

// Create an OSS client instance.
const client = new Client({
  // Replace with the Access Key ID of the STS temporary access credential.
  accessKeyId: 'yourAccessKeyId',
  // Replace with the Access Key Secret of the STS temporary access credential.
  accessKeySecret: 'yourAccessKeySecret',
  // Replace with the Security Token of the STS temporary access credential.
  securityToken: 'yourSecurityToken',
});

// List all buckets using a pagination token (marker).
const listBucketsWithMarker = async () => {
  try {
    let marker: string | undefined; // The pagination token. It is initially empty.
    let isTruncated = true; // Indicates whether there is more data to retrieve.

    // Loop to retrieve all buckets until there is no more data.
    while (isTruncated) {
      const res = await client.listBuckets({
        marker // The current pagination token.
      });

      // Print the result.
      console.log(JSON.stringify(res));

      // Update the pagination status.
      isTruncated = res.data.isTruncated; // Indicates whether there is more data.
      marker = res.data.nextMarker; // The next pagination token.
    }
  } catch (err) {
    if (err instanceof RequestError) {
      console.log('Error code: ', err.code);
      console.log('Error message: ', err.message);
      console.log('Request ID: ', err.requestId);
      console.log('HTTP status code: ', err.status);
      console.log('Error category: ', err.ec);
    } else {
      console.log('Unknown error: ', err);
    }
  }
};

// Call the function to list all buckets using a pagination token.
listBucketsWithMarker();

References

For more information about the API operation for listing buckets, see ListBuckets (GetService).