How to list objects using the Harmony SDK - Object Storage Service

This topic describes how to list all objects in a bucket using the Object Storage Service (OSS) SDK for Harmony.

Usage notes

For information about the regions and endpoints that are supported by OSS, see Regions and endpoints.
To list objects, you must have the oss:ListObjects permission. For more information, see Attach a custom policy to a RAM user.

Sample code

The following sample code provides an example of how to call the ListObjectsV2 operation to list objects in a bucket:

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

// Create an OSSClient instance.
const client = new Client({
  // Specify the AccessKey ID obtained from Security Token Service (STS).
  accessKeyId: 'yourAccessKeyId',
  // Specify the AccessKey secret obtained from STS.
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the security token obtained from STS.
  securityToken: 'yourSecurityToken',
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

/**
 * List objects in a bucket. 
 * Use the listObjectsV2 method to list objects in the bucket and the metadata of the objects. 
 */
const listObjectsV2 = async () => {
  try {
    // Use the listObjectsV2 method to list objects in the bucket and the metadata of the objects.
    const res = await client.listObjectsV2({
      bucket: 'yourBucketName', // Specify the name of the bucket.
    });

    // Display the objects and their metadata.
    console.log(JSON.stringify(res));
  } catch (err) {
    // Capture the exceptions during the request.
    if (err instanceof RequestError) {
      // If known types of errors exist, display information, such as the error code, error message, request ID, HTTP status code, and EC.
      console.log('code: ', err.code); // The error code.
      console.log('message: ', err.message); // The error message.
      console.log('requestId: ', err.requestId); // The request ID.
      console.log('status: ', err.status); // The HTTP status code.
      console.log('ec: ', err.ec); // The EC.
    } else {
      // Display other unknown types of errors.
      console.log('unknown error: ', err);
    }
  }
};

// Call the listObjectsV2 function to list objects in the bucket.
listObjectsV2();

Common scenarios

List objects with a specific prefix

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

// Create an OSSClient instance.
const client = new Client({
  // Specify the AccessKey ID of the RAM user.
  accessKeyId: 'yourAccessKeyId',
  // Specify the AccessKey secret of the RAM user.
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});


/**
 * List objects whose names contain a specific prefix in the bucket. 
 * Use the listObjectsV2 method and specify the prefix parameter to filter objects. 
 */
const listObjectsV2WithPrefix = async () => {
  try {
    // Use the listObjectsV2 method to list objects whose names contain a specific prefix in the bucket.
    const res = await client.listObjectsV2({
      bucket: 'yourBucketName', // Specify the name of the bucket.
      prefix: 'objectNamePrefix', // Specify the prefix contained in the names of the objects.
    });

    // Display the objects and their metadata.
    console.log(JSON.stringify(res));
  } catch (err) {
    // Capture exceptions during the request.
    if (err instanceof RequestError) {
      console.log('code: ', err.code); // The error code.
      console.log('message: ', err.message); // The error message.
      console.log('requestId: ', err.requestId); // The request ID.
      console.log('status: ', err.status); // The HTTP status code.
      console.log('ec: ', err.ec); // The EC.
    } else {
      console.log('unknown error: ', err);
    }
  }
};

// Call the listObjectsV2WithPrefix function to list objects whose names contain the specified prefix in the bucket.
listObjectsV2WithPrefix();

List objects by specifying a delimiter

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

// Create an OSS client instance.
const client = new Client({
  // Replace this with the AccessKey ID of your RAM user.
  accessKeyId: 'yourAccessKeyId',
  // Replace this with the AccessKey secret of your RAM user.
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the region where the bucket is located. For example, the region for China (Hangzhou) is 'oss-cn-hangzhou'.
  region: 'oss-cn-hangzhou',
});


/**
 * List objects in a bucket and use a separator.
 * Use the listObjectsV2 method and specify the delimiter parameter to simulate a folder structure.
 */
const listObjectsV2WithDelimiter = async () => {
  try {
    // Call the listObjectsV2 method to list objects in the specified bucket and use a separator to simulate a folder structure.
    const res = await client.listObjectsV2({
      bucket: 'yourBucketName', // The bucket name. Replace this with the name of the bucket that you use.
      delimiter: '/', // The separator. This is typically used to simulate a folder structure.
    });

    // Print the listed objects and their metadata.
    console.log(JSON.stringify(res));
  } catch (err) {
    // Catch exceptions that occur during the request.
    if (err instanceof RequestError) {
      console.log('code: ', err.code); // Error code
      console.log('message: ', err.message); // Error message
      console.log('requestId: ', err.requestId); // Request ID
      console.log('status: ', err.status); // HTTP status code
      console.log('ec: ', err.ec); // Error code
    } else {
      console.log('unknown error: ', err);
    }
  }
};

// Call the listObjectsV2WithDelimiter function to list objects using a separator.
listObjectsV2WithDelimiter();

List all objects by page

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

// Create an OSS client instance.
const client = new Client({
  // Replace with the AccessKey ID of your RAM user.
  accessKeyId: 'yourAccessKeyId',
  // Replace with the AccessKey secret of your RAM user.
  accessKeySecret: 'yourAccessKeySecret',
  // Set the region where the bucket is located. For example, for a bucket in the China (Hangzhou) region, set the region to 'oss-cn-hangzhou'.
  region: 'oss-cn-hangzhou',
});


/**
 * List objects in a bucket page by page.
 * Use the listObjectsV2 method with the continuationToken parameter to list objects page by page.
 */
const listObjectsV2WithContinuationToken = async () => {
  try {
    let continuationToken: string | undefined; // The pagination token. It is initially empty.
    let isTruncated = true; // Indicates whether there are more objects to list.

    // Loop through and list objects until no more objects are left.
    while (isTruncated) {
      const res = await client.listObjectsV2({
        bucket: 'yourBucketName', // The bucket name. Replace with the name of your bucket.
        continuationToken, // The pagination token used to retrieve the next page of results.
      });

      // Print the objects on the current page and their metadata.
      console.log(JSON.stringify(res));

      // Update the pagination status.
      isTruncated = res.data.isTruncated; // Indicates whether there are more objects.
      continuationToken = res.data.nextContinuationToken; // The pagination token for the next page.
    }
  } catch (err) {
    // Catch exceptions that occur during the request.
    if (err instanceof RequestError) {
      console.log('code: ', err.code); // The error code.
      console.log('message: ', err.message); // The error message.
      console.log('requestId: ', err.requestId); // The request ID.
      console.log('status: ', err.status); // The HTTP status code.
      console.log('ec: ', err.ec); // The error code.
    } else {
      console.log('unknown error: ', err);
    }
  }
};

// Call the listObjectsV2WithContinuationToken function to list objects page by page.
listObjectsV2WithContinuationToken();

List objects and get owner information

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

// Create an OSS client instance.
const client = new Client({
  // Replace with the AccessKey ID of the RAM user.
  accessKeyId: 'yourAccessKeyId',
  // Replace with the AccessKey secret of the RAM user.
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the region where the bucket is located. For example, the region for China (Hangzhou) is 'oss-cn-hangzhou'.
  region: 'oss-cn-hangzhou',
});

/**
 * Lists objects in a bucket and gets their owner information.
 * Use the listObjectsV2 method and set the fetchOwner parameter to get the owner information.
 */
const listObjectsV2WithFetchOwner = async () => {
  try {
    // Call the listObjectsV2 method to list objects in the specified bucket and get their owner information.
    const res = await client.listObjectsV2({
      bucket: 'yourBucketName', // The bucket name. Replace with the name of your bucket.
      fetchOwner: true, // Specifies whether to get the owner information of the objects.
    });

    // Print the listed objects and their metadata.
    console.log(JSON.stringify(res));
  } catch (err) {
    // Catch exceptions that occur during the request.
    if (err instanceof RequestError) {
      console.log('code: ', err.code); // Error code.
      console.log('message: ', err.message); // Error message.
      console.log('requestId: ', err.requestId); // Request ID.
      console.log('status: ', err.status); // HTTP status code.
      console.log('ec: ', err.ec); // Error code.
    } else {
      console.log('unknown error: ', err);
    }
  }
};

// Call the listObjectsV2WithFetchOwner function to list objects and get their owner information.
listObjectsV2WithFetchOwner();