Prevent users from modifying or deleting data in a bucket within a specific period of time by configuring retention policies for the bucket by using OSS SDK for Go-Object Storage Service(OSS)-阿里云帮助中心

The Write Once Read Many (WORM) feature of retention policies in Object Storage Service (OSS) allows you to prevent users from modifying or deleting data. If you do not want anyone, including resource owners, to modify or delete objects in a bucket within a specific period of time, you can configure a retention policy for the bucket. After you configure a retention policy, users can only read the objects in or upload objects to the bucket until the retention period ends. Users can modify or delete objects in the bucket only after the retention period ends.

Notes

In this topic, the public endpoint of the China (Hangzhou) region is used. If you want to access OSS from other Alibaba Cloud services in the same region as OSS, use an internal endpoint. For more information about OSS regions and endpoints, see Regions and endpoints.
In this topic, access credentials are obtained from environment variables. For more information about how to configure access credentials, see Configure access credentials.
This topic demonstrates creating an OSSClient instance with an OSS endpoint. For alternative configurations, such as using a custom domain or authenticating with credentials from Security Token Service (STS), see Configure a client (Go SDK V1).

Sample code

Create a retention policy

Important

A bucket cannot have versioning and retention policies configured at the same time. Therefore, before you create a retention policy for a bucket, please make sure that versioning is not enabled for the bucket.

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

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		log.Fatalf("Error creating credentials provider: %v", err)
	}

	// Create an OSSClient instance.
	// 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. Specify your actual endpoint. 
	// 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 cn-hangzhou. Specify the actual region.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Specify the version of the signature algorithm.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		log.Fatalf("Error creating OSS client: %v", err)
	}

	// Specify the name of the bucket for which you want to configure a retention policy. 
	bucketName := "<yourBucketName>"

	// Set the retention period of the retention policy to 60 days.
	result, err := client.InitiateBucketWorm(bucketName, 60)
	if err != nil {
		log.Fatalf("Error initiating bucket WORM: %v", err)
	}

	log.Println("WORM policy initiated successfully:", result)
}

Cancel an unlocked retention policy

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

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		log.Fatalf("Error creating credentials provider: %v", err)
	}

	// Create an OSSClient instance. 
	// 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. Specify your actual endpoint. 
	// 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 cn-hangzhou. Specify the actual region.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Specify the version of the signature algorithm.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		log.Fatalf("Error creating OSS client: %v", err)
	}

	// Specify the name of the bucket from which you want to delete the retention policy.
	bucketName := "<yourBucketName>"

	// Delete the unlocked retention policy.
	err = client.AbortBucketWorm(bucketName)
	if err != nil {
		log.Fatalf("Error aborting bucket WORM: %v", err)
	}

	log.Println("Bucket WORM policy aborted successfully")
}

Lock a retention policy

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

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		log.Fatalf("Error creating credentials provider: %v", err)
	}

	// Create an OSSClient instance. 
	// 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. Specify your actual endpoint. 
	// 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 cn-hangzhou. Specify the actual region.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Specify the version of the signature algorithm.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		log.Fatalf("Error creating OSS client: %v", err)
	}

	// Specify the name of the bucket for which you want to lock the retention policy.
	bucketName := "<yourBucketName>"

	// Query the current WORM configuration.
	wormConfig, err := client.GetBucketWorm(bucketName)
	if err != nil {
		log.Fatalf("Error getting bucket WORM configuration: %v", err)
	}

	// Lock the retention policy.
	err = client.CompleteBucketWorm(bucketName, wormConfig.WormId)
	if err != nil {
		log.Fatalf("Error completing bucket WORM: %v", err)
	}

	log.Println("Bucket WORM policy locked successfully")
}

Query retention policies

The following sample code provides an example on how to query the retention policies of a bucket:

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		log.Fatalf("Error creating credentials provider: %v", err)
	}

	// Create an OSSClient instance. 
	// 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. Specify your actual endpoint. 
	// 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 cn-hangzhou. Specify the actual region.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Specify the version of the signature algorithm.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		log.Fatalf("Error creating OSS client: %v", err)
	}

	// Specify the name of the bucket whose retention policies you want to query.
	bucketName := "<yourBucketName>"

	// Query the retention policy of a bucket:
	wormConfig, err := client.GetBucketWorm(bucketName)
	if err != nil {
		log.Fatalf("Error getting bucket WORM configuration: %v", err)
	}

	// Query the IDs of the retention policies. 
	log.Printf("WORM Policy ID: %d", wormConfig.WormId)

	// Query the time when the retention policies were created. 
	log.Printf("Creation Date: %s", wormConfig.CreationDate)

	// Query the status of the retention policies. InProgress indicates that a retention policy is unlocked, and Locked indicates that a retention policy is locked. 
	log.Printf("State: %s", wormConfig.State)

	// Query the retention period of the retention policies. 
	log.Printf("Retention Period (days): %d", wormConfig.RetentionPeriodInDays)
}

Extend the retention period of a retention policy

The following sample code provides an example on how to extend the retention period of a locked retention policy:

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		log.Fatalf("Error creating credentials provider: %v", err)
	}

	// Create an OSSClient instance. 
	// 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. Specify your actual endpoint. 
	// 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 cn-hangzhou. Specify the actual region.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Specify the version of the signature algorithm.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		log.Fatalf("Error creating OSS client: %v", err)
	}

	// Specify the name of the bucket whose retention policy you want to extend the retention period. 
	bucketName := "<yourBucketName>"

	// Query the current WORM configuration.
	wormConfig, err := client.GetBucketWorm(bucketName)
	if err != nil {
		log.Fatalf("Error getting bucket WORM configuration: %v", err)
	}

	// Extend the retention period of the locked retention policy to 30 days. 
	err = client.ExtendBucketWorm(bucketName, 30, wormConfig.WormId)
	if err != nil {
		log.Fatalf("Error extending bucket WORM: %v", err)
	}

	log.Println("Bucket WORM protection period extended successfully")
}

References

For the complete sample code that is used to manage a retention policy, visit GitHub.
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 cancel 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 retention policies, see GetBucketWorm.
For more information about the API operation that you can call to extend the retention period of a retention policy, see ExtendBucketWorm.