Manage versioning (Harmony SDK)

Notes

• Enabling versioning for a bucket lets you recover previous versions of an object if it is accidentally overwritten or deleted. The versioning state of a bucket can be unversioned (the default state), enabled, or suspended. For more information, see Versioning.

• To set the versioning state of a bucket, you must have the oss:PutBucketVersioning permission. To retrieve the versioning state of a bucket, you must have the oss:GetBucketVersioning permission. For more information, see Grant a custom access policy to a RAM user.

Configure the versioning state of a bucket

The following code shows how to enable or suspend versioning for a bucket.

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

// Create an OSS client instance.
const client = new Client({
  // Replace with the AccessKey ID of the temporary identity credentials from Security Token Service (STS).
  accessKeyId: 'yourAccessKeyId',
  // Replace with the AccessKey Secret of the temporary identity credentials from STS.
  accessKeySecret: 'yourAccessKeySecret',
  // Replace with the security token of the temporary identity credentials from STS.
  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',
});

// Set the versioning state of the bucket.
const putBucketVersioning = async () => {
  try {
    // Call the putBucketVersioning method to set the versioning state of the bucket.
    const res = await client.putBucketVersioning({
      bucket: 'yourBucketName', // Replace with your bucket name.
      status: EVersionStatus.ENABLED // Set the versioning state to enabled (ENABLED).
    });

    // Print the returned result.
    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. For example, "InvalidArgument" indicates an invalid parameter.
      console.log('Error message: ', err.message); // The error description, which provides more details.
      console.log('Request ID: ', err.requestId); // The unique ID of the request, which is used for troubleshooting.
      console.log('HTTP status code: ', err.status); // The HTTP status code. For example, 400 indicates a client error.
      console.log('Error category: ', err.ec); // The error category, which further classifies the error type.
    } else {
      console.log('Unknown error: ', err); // An error that is not of the RequestError type, which may be another exception.
    }
  }
};

// Call the function to set the versioning state of the bucket.
putBucketVersioning();

Query the versioning state of a bucket

The following code shows how to retrieve the versioning state of a bucket.

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

// Create an OSS client instance.
const client = new Client({
  // Replace this with the AccessKey ID of the STS temporary credential.
  accessKeyId: 'yourAccessKeyId',
  // Replace this with the AccessKey secret of the STS temporary credential.
  accessKeySecret: 'yourAccessKeySecret',
  // Replace this with the security token of the STS temporary credential.
  securityToken: 'yourSecurityToken',
  // Specify the region where the bucket is located. For China (Hangzhou), set the region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

// Get the versioning status of the bucket.
const getBucketVersioning = async () => {
  try {
    // Call the getBucketVersioning method to get the versioning status of the specified bucket.
    const res = await client.getBucketVersioning({
      bucket: 'yourBucketName' // Replace this with your bucket name.
    });

    // Print the returned result, which contains the versioning status of the bucket.
    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. For example, "NoSuchBucket" indicates that the bucket does not exist.
      console.log('Error message: ', err.message); // The error description, which provides more detailed error information.
      console.log('Request ID: ', err.requestId); // The unique identifier of the request, which is used for troubleshooting.
      console.log('HTTP status code: ', err.status); // The HTTP response status code. For example, 404 indicates that the resource is not found.
      console.log('Error category: ', err.ec); // The error category, which is used to further classify the error type.
    } else {
      console.log('Unknown error: ', err); // An error that is not of the RequestError type, such as another exception.
    }
  }
};

// Call the function to get the versioning status of the bucket.
getBucketVersioning();

References

• For more information about the API operation to set the versioning state of a bucket, see PutBucketVersioning.

• For more information about the API operation to retrieve the versioning state of a bucket, see GetBucketVersioning.