You can configure a time-based retention policy for a bucket. The retention policy has a retention period that ranges from 1 day to 70 years. This topic describes how to create, query, and lock a retention policy.

Background information

Object Storage Service (OSS) supports the Write Once Read Many (WORM) feature, which prevents an object from being deleted or overwritten for a specified period of time.

If a retention policy is not locked within 24 hours after it is created, the retention policy becomes invalid. If the retention policy configured for a bucket is locked, you can upload objects to or read objects from the bucket. However, objects in the bucket or the retention policy cannot be deleted within the retention period specified by the policy. The retention period specified by the policy can be extended but not shortened. For more information about retention policies, see Retention policy.

Create a retention policy for a bucket

The following code provides an example on how to create a retention policy for a bucket:

const OSS = require('ali-oss');

const client = new OSS({
  // 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: 'yourregion',
  // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeyId'
});
// Create a retention policy for the bucket. 
async function initiateBucketWorm() {
 // Set yourbucketname to the name of your bucket. 
  const bucket = 'yourbucketname'
  // Specify the retention period of objects. 
  const days = '<Retention Days>'
    const res = await client.initiateBucketWorm(bucket, days)
  console.log(res.wormId)
}

initiateBucketWorm()

Delete an unlocked retention policy of a bucket

The following code provides an example on how to delete an unlocked retention policy of a bucket:

const OSS = require('ali-oss');

const client = new OSS({
  // 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: 'yourregion',
  // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeyId'
});
// Delete the unlocked retention policy that is configured for the bucket. 
async function abortBucketWorm() {
  // Set yourbucketname to the name of your bucket. 
  const bucket = 'yourbucketname'
    try {
    await client.abortBucketWorm(bucket)
    console.log('abort success')
  } catch(err) {
        console.log('err: ', err)
    }
}

abortBucketWorm()

Lock a retention policy of a bucket

The following code provides an example on how to lock a retention policy of a bucket:

const OSS = require('ali-oss');

const client = new OSS({
  // 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: 'yourregion',
  // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeyId'
});
// Lock the retention policy that is configured for the bucket. 
async function completeBucketWorm() {
  // Set yourbucketname to the name of your bucket. 
  const bucket = 'yourbucketname'
  const wormId = 'Your Worm Id'
    try {
        await client.completeBucketWorm(bucket, wormId)
  } catch(err) {
      console.log(err)
  }
}

completeBucketWorm()

Query a retention policy of a bucket

The following code provides an example on how to query a retention policy of a bucket:

const OSS = require('ali-oss');

const client = new OSS({
  // 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: 'yourregion',
  // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeyId'
});
// Query the retention policy that is configured for the bucket. 
async function getBucketWorm() {
  // Set yourbucketname to the name of your bucket. 
  const bucket = 'yourbucketname'
    try {
        const res = await client.getBucketWorm(bucket)
    // Query the ID of the retention policy. 
    console.log(res.wormId)
    // Query the status of the retention policy. InProgress indicates that the retention policy is not locked. Locked indicates that the retention policy is locked. 
    console.log(res.state)
    // Query the retention period of objects. 
    console.log(res.days)
  } catch(err) {
      console.log(err)
  }
}

getBucketWorm()

Extend the retention period of objects

The following code provides an example on how to extend the retention period of objects in a bucket for which a retention policy is locked:

const OSS = require('ali-oss');

const client = new OSS({
  // 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: 'yourregion',
  // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeyId'
});
// Extend the retention period of objects specified by the locked retention policy. 
async function extendBucketWorm() {
  // Set yourbucketname to the name of your bucket. 
  const bucket = 'yourbucketname'
  const wormId = 'Your Worm Id'
  const days = 'Retention Days'
    try {
        const res = await client.extendBucketWorm(bucket, wormId, days)
    console.log(res)
  } catch(err) {
      console.log(err)
  }
}

extendBucketWorm()

References

  • For the complete sample code that is used to configure a retention policy for a bucket, visit GitHub.
  • For more information about the API operation that you can call to create a retention policy for a bucket, see InitiateBucketWorm.
  • For more information about the API operation that you can call to delete an unlocked retention policy of a bucket, see AbortBucketWorm.
  • For more information about the API operation that you can call to lock a retention policy of a bucket, see CompleteBucketWorm.
  • For more information about the API operation that you can call to query a retention policy of a bucket, see GetBucketWorm.
  • For more information about the API operation that you can call to extend the retention period of objects in a bucket for which a retention policy is locked, see ExtendBucketWorm.