How to list files using the Harmony SDK-Object Storage Service(OSS)-阿里云帮助中心

This topic describes how to list all objects in a bucket when versioning is enabled.

Notes

For more information about the regions and endpoints that OSS supports, see Regions and endpoints.
To list objects, you must have the oss:ListObjectVersions permission. For more information, see Grant custom access policies to RAM users.

Sample code

The following code shows how to list the versions of all objects, including delete markers, in a specified bucket.

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

// Create an OSS client instance.
const client = new Client({
  // Replace with the Access Key ID of your STS temporary credentials.
  accessKeyId: 'yourAccessKeyId',
  // Replace with the Access Key Secret of your STS temporary credentials.
  accessKeySecret: 'yourAccessKeySecret',
  // Replace with the Security Token of your STS temporary credentials.
  securityToken: 'yourSecurityToken',
  // Specify the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set Region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

// The bucket name.
const bucket = 'yourBucketName';
// The object name.
const key = 'yourObjectName';

// List the versions of objects in the bucket.
const listObjectVersions = async () => {
  try {
    // Call the listObjectVersions method to list the versions of objects in the bucket.
    const res = await client.listObjectVersions({
      bucket // Replace with your bucket name.
    });

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

// Call the function to list the versions of all objects.
listObjectVersions();

Scenarios

List and group object versions

The following sample code shows how to list and group object versions by setting the `delimiter` parameter.

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

// Create an OSS client instance.
const client = new Client({
  // Replace with the Access Key ID of your STS temporary credentials.
  accessKeyId: 'yourAccessKeyId',
  // Replace with the Access Key Secret of your STS temporary credentials.
  accessKeySecret: 'yourAccessKeySecret',
  // Replace with the Security Token of your STS temporary credentials.
  securityToken: 'yourSecurityToken',
  // Specify the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set Region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

// List the versions of objects in the bucket and group the results using a separator.
const listObjectVersionsWithDelimiter = async () => {
  try {
    // Call the listObjectVersions method and specify the delimiter parameter to group the results.
    const res = await client.listObjectVersions({
      bucket, // Replace with your bucket name.
      delimiter: '/' // Use '/' as the separator to group objects by folder structure.
    });

    // 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 and group object versions.
listObjectVersionsWithDelimiter();

List object versions in a bucket using pagination markers

The following sample code shows how to list the versions of objects in a bucket using the `keyMarker` and `versionIdMarker` pagination markers.

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

// Create an OSS client instance.
const client = new Client({
  // Replace with the Access Key ID of your STS temporary credentials.
  accessKeyId: 'yourAccessKeyId',
  // Replace with the Access Key Secret of your STS temporary credentials.
  accessKeySecret: 'yourAccessKeySecret',
  // Replace with the Security Token of your STS temporary credentials.
  securityToken: 'yourSecurityToken',
  // Specify the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set Region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

// Use pagination markers (keyMarker and versionIdMarker) to list the versions of objects in the bucket.
const listObjectVersionsWithMarker = async () => {
  try {
    let keyMarker: string | undefined; // The pagination marker. Initially empty.
    let versionIdMarker: string | undefined; // The version pagination marker. Initially empty.
    let isTruncated = true; // Specifies whether there is more data to retrieve.

    // Loop to retrieve object versions until there is no more data.
    while (isTruncated) {
      const res = await client.listObjectVersions({
        bucket, // Replace with your bucket name.
        keyMarker, // The current pagination marker.
        versionIdMarker // The current version pagination marker.
      });

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

      // Update the pagination status.
      isTruncated = res.data.isTruncated; // Specifies whether there is more data.
      keyMarker = res.data.nextKeyMarker; // The next pagination marker.
      versionIdMarker = res.data.nextVersionIdMarker; // The next version pagination marker.
    }
  } 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 the versions of all objects using pagination markers.
listObjectVersionsWithMarker();

References

For more information about the API operation to list object versions, including delete markers, see ListObjectVersions (GetBucketVersions).