Use OSS SDK for Go 2.0 to manage retention policies - Object Storage Service

Use the OSS SDK for Go 2.0 to create, lock, query, and manage time-based retention policies (WORM) on a bucket. Retention periods range from 1 day to 70 years.

Usage notes

The sample code uses the region ID cn-hangzhou for the China (Hangzhou) region. By default, a public endpoint is used to access resources in a bucket. To access resources from other Alibaba Cloud services in the same region, use an internal endpoint. For more information, see OSS regions and endpoints.
Access credentials in the sample code are loaded from environment variables. For configuration instructions, see Configure access credentials.

API summary

Operation	Method	State required
Create a retention policy	`InitiateBucketWorm`	—
Cancel a retention policy	`AbortBucketWorm`	InProgress
Lock a retention policy	`CompleteBucketWorm`	InProgress
Query a retention policy	`GetBucketWorm`	Any
Extend the retention period	`ExtendBucketWorm`	Locked

Create a retention policy

Call InitiateBucketWorm to create a time-based retention policy on a bucket. The response includes a WormId that is required for subsequent lock and extend operations.

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

var (
	region     string
	bucketName string
)

func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
}

func main() {
	flag.Parse()

	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	client := oss.NewClient(cfg)

	request := &oss.InitiateBucketWormRequest{
		Bucket: oss.Ptr(bucketName),
		InitiateWormConfiguration: &oss.InitiateWormConfiguration{
			RetentionPeriodInDays: oss.Ptr(int32(30)), // Set the retention period to 30 days.
		},
	}

	result, err := client.InitiateBucketWorm(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to initiate bucket worm %v", err)
	}

	// result.WormId is required to lock or extend this policy.
	log.Printf("initiate bucket worm result:%#v\n", result)
}

Cancel a retention policy

Only a policy in the InProgress (unlocked) state can be cancelled. Call AbortBucketWorm to delete it.

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

var (
	region     string
	bucketName string
)

func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
}

func main() {
	flag.Parse()

	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	client := oss.NewClient(cfg)

	request := &oss.AbortBucketWormRequest{
		Bucket: oss.Ptr(bucketName),
	}

	result, err := client.AbortBucketWorm(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to abort bucket worm %v", err)
	}

	log.Printf("abort bucket worm result:%#v\n", result)
}

Lock a retention policy

Locking a policy makes it permanently immutable — it cannot be cancelled or shortened afterwards. Only a policy in the InProgress state can be locked. Obtain wormId from the InitiateBucketWorm response (result.WormId).

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

var (
	region     string
	bucketName string
)

func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
}

func main() {
	var (
		wormId = "worm id" // Replace with the WormId returned by InitiateBucketWorm.
	)
	flag.Parse()

	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	client := oss.NewClient(cfg)

	// The policy must be in the InProgress state before it can be locked.
	request := &oss.CompleteBucketWormRequest{
		Bucket: oss.Ptr(bucketName),
		WormId: oss.Ptr(wormId),
	}

	result, err := client.CompleteBucketWorm(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to complete bucket worm %v", err)
	}

	log.Printf("complete bucket worm result:%#v\n", result)
}

Query a retention policy

Call GetBucketWorm to retrieve the current retention policy configuration and status for a bucket.

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

var (
	region     string
	bucketName string
)

func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
}

func main() {
	flag.Parse()

	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	client := oss.NewClient(cfg)

	request := &oss.GetBucketWormRequest{
		Bucket: oss.Ptr(bucketName),
	}

	result, err := client.GetBucketWorm(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to get bucket worm %v", err)
	}

	log.Printf("get bucket worm result:%#v\n", result)
}

Extend the retention period

After a policy is locked, the retention period can only be extended, not shortened. Call ExtendBucketWorm with a new RetentionPeriodInDays value greater than the current period. Obtain wormId from the InitiateBucketWorm response (result.WormId).

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

var (
	region     string
	bucketName string
)

func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
}

func main() {
	var (
		wormId = "worm id" // Replace with the WormId returned by InitiateBucketWorm.
	)
	flag.Parse()

	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	client := oss.NewClient(cfg)

	// The policy must be in the Locked state. The new period must be longer than the current period.
	request := &oss.ExtendBucketWormRequest{
		Bucket: oss.Ptr(bucketName),
		WormId: oss.Ptr(wormId),
		ExtendWormConfiguration: &oss.ExtendWormConfiguration{
			RetentionPeriodInDays: oss.Ptr(int32(30)), // Extend the retention period to 30 days.
		},
	}

	result, err := client.ExtendBucketWorm(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to extend bucket worm %v", err)
	}

	log.Printf("extend bucket worm result:%#v\n", result)
}

Object Storage Service:Retention policies with OSS SDK for Go 2.0