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. This feature 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 of the policy. The retention period specified by the policy can be extended but cannot be shortened. For more information about retention policies, see Retention policy.

Create a retention policy

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

# -*- coding: utf-8 -*-
import oss2
# 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. 
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Set yourBucketName to the name of your bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'yourBucketName')

# Create a retention policy and set the retention period to 1 day. 
result = bucket.init_bucket_worm(1)
# Display the ID of the retention policy. 
print(result.worm_id)

Delete an unlocked retention policy

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

# -*- coding: utf-8 -*-
import oss2
# 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. 
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Set yourBucketName to the name of your bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'yourBucketName')

# Delete the unlocked retention policy. 
bucket.abort_bucket_worm()

Lock a retention policy

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

# -*- coding: utf-8 -*-
import oss2
# 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. 
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Set yourBucketName to the name of your bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'yourBucketName')

# Lock the retention policy. 
bucket.complete_bucket_worm('<yourWromId>')

Query a retention policy

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

# -*- coding: utf-8 -*-
import oss2
# 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. 
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Set yourBucketName to the name of your bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'yourBucketName')

# Query the retention policy. 
result = self.bucket.get_bucket_worm()

# Display the ID of the retention policy. 
print(result.worm_id)
# Display the status of the retention policy. InProgress indicates that the retention policy is not locked. Locked indicates that the retention policy is locked. 
print(result.state)
# Display the retention period of objects. 
print(result.retention_period_days)
# Display the time when the retention policy is created. 
print(result.creation_date)

Extend the retention period of objects

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

# -*- coding: utf-8 -*-
import oss2
# 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. 
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Set yourBucketName to the name of your bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'yourBucketName')

# Extend the retention period of objects in the bucket. 
bucket.extend_bucket_worm('<yourWormId>', 2)

References

  • For more information about the API operation that you can call to create a retention policy, see InitiateBucketWorm.
  • For more information about the API operation that you can call to delete an unlocked retention policy, see AbortBucketWorm.
  • For more information about the API operation that you can call to lock a retention policy, see CompleteBucketWorm.
  • For more information about the API operation that you can call to query a retention policy, see GetBucketWorm.
  • For more information about the API operation that you can call to extend the retention period of objects in a bucket whose retention policy is locked, see ExtendBucketWorm.