How to use Python SDK V2 to create, query, and lock retention policies - Object Storage Service

Use the OSS Python SDK v2 to manage write-once-read-many (WORM) compliance retention policies on a bucket. A retention policy enforces immutability for objects during the retention period, which can range from 1 day to 70 years.

This topic covers five operations: create, query, lock, extend, and cancel a retention policy.

Usage notes

All examples use the cn-hangzhou region. By default, the client connects using a public endpoint. To access OSS from another Alibaba Cloud service in the same region, set cfg.endpoint to the internal endpoint. For a full list of endpoints, see Regions and endpoints.

Prerequisites

Before you begin, make sure you have:

An OSS bucket
Python SDK v2 (alibabacloud_oss_v2) installed
Access credentials configured as environment variables

Create a retention policy

Call initiate_bucket_worm() to create a time-based retention policy. The response includes a worm_id that you need for subsequent lock and extend operations.

import argparse
import alibabacloud_oss_v2 as oss

parser = argparse.ArgumentParser(description="Create a WORM retention policy for a bucket")
parser.add_argument('--region', required=True, help='Region ID, e.g. cn-hangzhou')
parser.add_argument('--bucket', required=True, help='Bucket name')
parser.add_argument('--endpoint', help='Custom endpoint (optional)')
parser.add_argument('--retention_period_in_days', required=True, help='Retention period in days')

def main():
    args = parser.parse_args()

    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    client = oss.Client(cfg)

    result = client.initiate_bucket_worm(oss.InitiateBucketWormRequest(
        bucket=args.bucket,
        initiate_worm_configuration=oss.InitiateWormConfiguration(
            retention_period_in_days=int(args.retention_period_in_days),
        ),
    ))

    # Save the worm_id — you need it to lock or extend the policy.
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' worm id: {result.worm_id}'
    )

if __name__ == "__main__":
    main()

Query a retention policy

Call get_bucket_worm() to retrieve the current configuration and status of the retention policy.

import argparse
import alibabacloud_oss_v2 as oss

parser = argparse.ArgumentParser(description="Query the WORM retention policy of a bucket")
parser.add_argument('--region', required=True, help='Region ID, e.g. cn-hangzhou')
parser.add_argument('--bucket', required=True, help='Bucket name')
parser.add_argument('--endpoint', help='Custom endpoint (optional)')

def main():
    args = parser.parse_args()

    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    client = oss.Client(cfg)

    result = client.get_bucket_worm(oss.GetBucketWormRequest(
        bucket=args.bucket,
    ))

    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' worm id: {result.worm_configuration.worm_id},'
          f' state: {result.worm_configuration.state},'
          f' retention period in days: {result.worm_configuration.retention_period_in_days},'
          f' creation date: {result.worm_configuration.creation_date},'
          f' expiration date: {result.worm_configuration.expiration_date},'
    )

if __name__ == "__main__":
    main()

The worm_configuration object returns the following fields:

Field	Description
`worm_id`	Unique ID of the retention policy
`state`	Current state of the WORM feature
`retention_period_in_days`	Retention period in days
`creation_date`	Date the policy was created
`expiration_date`	Date the policy expires

Lock a retention policy

Call complete_bucket_worm() to lock the policy. After locking, the policy cannot be deleted and the retention period cannot be shortened.

import argparse
import alibabacloud_oss_v2 as oss

parser = argparse.ArgumentParser(description="Lock a WORM retention policy for a bucket")
parser.add_argument('--region', required=True, help='Region ID, e.g. cn-hangzhou')
parser.add_argument('--bucket', required=True, help='Bucket name')
parser.add_argument('--endpoint', help='Custom endpoint (optional)')
parser.add_argument('--worm_id', required=True, help='Worm ID returned when the policy was created')

def main():
    args = parser.parse_args()

    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    client = oss.Client(cfg)

    result = client.complete_bucket_worm(oss.CompleteBucketWormRequest(
        bucket=args.bucket,
        worm_id=args.worm_id,
    ))

    print(f'status code: {result.status_code},'
          f' request id: {result.request_id}'
    )

if __name__ == "__main__":
    main()

Extend the retention period

Call extend_bucket_worm() to increase the retention period of a retention policy.

import argparse
import alibabacloud_oss_v2 as oss

parser = argparse.ArgumentParser(description="Extend the retention period of a locked WORM policy")
parser.add_argument('--region', required=True, help='Region ID, e.g. cn-hangzhou')
parser.add_argument('--bucket', required=True, help='Bucket name')
parser.add_argument('--endpoint', help='Custom endpoint (optional)')
parser.add_argument('--worm_id', required=True, help='Worm ID of the locked policy')
parser.add_argument('--retention_period_in_days', required=True, help='New retention period in days')

def main():
    args = parser.parse_args()

    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    client = oss.Client(cfg)

    result = client.extend_bucket_worm(oss.ExtendBucketWormRequest(
        bucket=args.bucket,
        worm_id=args.worm_id,
        extend_worm_configuration=oss.ExtendWormConfiguration(
            retention_period_in_days=int(args.retention_period_in_days),
        ),
    ))

    print(f'status code: {result.status_code},'
          f' request id: {result.request_id}'
    )

if __name__ == "__main__":
    main()

Cancel an unlocked retention policy

Call abort_bucket_worm() to delete a policy that has not been locked.

import argparse
import alibabacloud_oss_v2 as oss

parser = argparse.ArgumentParser(description="Cancel an unlocked WORM retention policy")
parser.add_argument('--region', required=True, help='Region ID, e.g. cn-hangzhou')
parser.add_argument('--bucket', required=True, help='Bucket name')
parser.add_argument('--endpoint', help='Custom endpoint (optional)')

def main():
    args = parser.parse_args()

    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    client = oss.Client(cfg)

    result = client.abort_bucket_worm(oss.AbortBucketWormRequest(
        bucket=args.bucket,
    ))

    print(f'status code: {result.status_code},'
          f' request id: {result.request_id}'
    )

if __name__ == "__main__":
    main()

What's next

For common errors related to retention policies, see 27-WORM.