List buckets using the OSS SDK for Harmony - Object Storage Service

Use the Harmony SDK to list all buckets in your Alibaba Cloud account across all regions. Results are sorted alphabetically.

Note: listBuckets returns buckets across all regions regardless of the endpoint you specify. Filtering by region is not supported.

Prerequisites

Before you begin, ensure that you have:

The oss:ListBuckets permission. For details, see Grant custom access policies to RAM users
Security Token Service (STS) temporary access credentials (Access Key ID, Access Key Secret, and security token). For supported regions and endpoints, see Regions and endpoints

List all buckets

The following example lists all buckets 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',
});

const listBuckets = async () => {
  try {
    const res = await client.listBuckets({});

    console.log(JSON.stringify(res));
  } catch (err) {
    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);
    }
  }
};

listBuckets();

Filter and paginate results

listBuckets accepts the following optional parameters:

Parameter	Type	Description
`prefix`	`string`	Returns only buckets whose names start with this string.
`marker`	`string \| undefined`	Pagination token from the previous response (`nextMarker`). Pass this to retrieve the next page of results.

List buckets with a prefix

The following example returns only buckets whose names start with bucketNamePrefix.

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

const client = new Client({
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  securityToken: 'yourSecurityToken',
});

const listBucketsWithPrefix = async () => {
  try {
    const res = await client.listBuckets({
      prefix: 'bucketNamePrefix', // Returns only buckets whose names start with this prefix.
    });

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

listBucketsWithPrefix();

Paginate through all buckets

When isTruncated is true in the response, more buckets are available. Pass nextMarker as the marker parameter in the next call to retrieve the next page. Repeat until isTruncated is false.

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

const client = new Client({
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  securityToken: 'yourSecurityToken',
});

const listAllBucketsWithPagination = async () => {
  try {
    let marker: string | undefined; // Initially empty; set to nextMarker after each page.
    let isTruncated = true;

    while (isTruncated) {
      const res = await client.listBuckets({ marker });

      console.log(JSON.stringify(res));

      // Advance to the next page.
      isTruncated = res.data.isTruncated;
      marker = res.data.nextMarker;
    }
  } 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);
    }
  }
};

listAllBucketsWithPagination();

References

ListBuckets (GetService) — API reference for the list buckets operation.