Enable versioning for OSS on CloudBox buckets - Object Storage Service

Versioning is a data protection feature for OSS on CloudBox buckets. When you enable versioning, OSS saves overwritten or deleted objects as historical versions. If you accidentally overwrite or delete an object, you can restore it to any of its previous versions.

Prerequisites

OSS on CloudBox is available only in the China (Hangzhou), China (Shanghai), China (Shenzhen), China (Heyuan), China (Beijing), and China (Chengdu) regions.
You have purchased a CloudBox.
You have created a VPC and a vSwitch for the CloudBox.
You have contacted technical support to request a SingleTunnel network type for your CloudBox's VPC.

Use cases

Use versioning in the following scenarios to protect your data.

Accidental data deletion

Since OSS does not have a recycle bin, versioning is the primary way to recover accidentally deleted data.
File overwrites

For frequently modified files (cloud drives, collaborative tools), versioning lets you retrieve any previous version.

Usage notes

Permissions

Only the OSS on CloudBox bucket owner or RAM users with the oss-cloudbox:PutBucketVersioning permission can configure versioning.
Feature conflicts

If versioning is enabled for a bucket, the x-oss-forbid-overwrite request header does not take effect during uploads. For more information, see PutObject.

Versioning states

A bucket's versioning can be in one of three states: Disabled (default), Enabled, or Suspended.

By default, versioning is disabled for a bucket. After you enable versioning, you cannot return the bucket to the disabled state. However, you can suspend versioning for the bucket.
When versioning is enabled for a bucket, OSS generates a globally unique random string as the version ID for each newly uploaded object.
When versioning is suspended for a bucket, OSS assigns a version ID of "null" to each newly uploaded object.

Note

When versioning is enabled for an OSS on CloudBox bucket, each object version is stored and incurs storage costs. Use lifecycle rules to delete unneeded historical versions.

Data protection

The following table describes how object overwrite and deletion behavior differs among versioning states.

Versioning state	Overwrite an object	Delete an object
Disabled	The existing object is overwritten and cannot be restored. You can only retrieve the latest version of the object.	The object is permanently deleted and cannot be retrieved.
Enabled	A new version is created. Historical versions are not affected.	The object is marked as deleted. Historical versions are not affected and can be restored.
Suspended	A new version is created. If a version of the same object already exists from the suspension period, the new version overwrites it. Other historical versions are not affected.	The object is marked as deleted. If a delete marker for the same object already exists from the suspension period, the new marker overwrites it. Other historical versions are not affected.

Enable versioning

When versioning is enabled for a bucket, OSS specifies a unique ID for each version of an object stored in the bucket.

Use the OSS console

Enable versioning when you create an OSS on CloudBox bucket
1. Log on to the OSS console.
2. In the left-side navigation pane, choose Data Service > OSS on CloudBox Buckets, and then click Create Bucket.
3. On the Create Bucket panel, configure the parameters.
  
  In the Versioning section, select Enable. For information about other parameters, see Create an OSS on CloudBox bucket.
4. Click OK.
Enable versioning for an existing OSS on CloudBox bucket
1. In the left-side navigation pane, choose Data Service > OSS on CloudBox Buckets, and then click the name of the target bucket.
2. In the left-side navigation pane, choose Content Security > Versioning.
3. Click Versioning next to Enable.

Use an Alibaba Cloud SDK

You can enable versioning by using the OSS SDK for Java, Python, or Go (Java SDK 3.15.0 or later, Python SDK V2 1.1.1 or later, or Go SDK V2 v1.2.1 or later). For OSS on CloudBox, the Python and Go SDKs are called in the same way as they are in public cloud OSS. For information about how to create a client, see SDK support.

Java

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.*;
import com.aliyun.oss.common.auth.DefaultCredentialProvider;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;

public class Demo {
    public static void main(String[] args) throws Exception {
        // Specify the data endpoint of the OSS on CloudBox bucket.
        String endpoint = "https://cb-f8z7yvzgwfkl9q0h****.cn-hangzhou.oss-cloudbox.aliyuncs.com";
        // Obtain access credentials from environment variables. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the name of the OSS on CloudBox bucket, for example, examplebucket.
        String bucketName = "examplebucket";
        // Specify the region where the OSS on CloudBox bucket is located.
        String region = "cn-hangzhou";
        // Specify the ID of the CloudBox.
        String cloudBoxId = "cb-f8z7yvzgwfkl9q0h****";

        // Create an OSSClient instance.
        // When the OSSClient instance is no longer needed, call the shutdown method to release the resources.
        ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
        conf.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(new DefaultCredentialProvider(credentialsProvider.getCredentials()))
                .clientConfiguration(conf)
                .region(region)
                .cloudBoxId(cloudBoxId)
                .build();

        try {
            // Set the versioning state of the bucket to Enabled.
            BucketVersioningConfiguration configuration = new BucketVersioningConfiguration();
            configuration.setStatus(BucketVersioningConfiguration.ENABLED);
            SetBucketVersioningRequest request = new SetBucketVersioningRequest(bucketName, configuration);
            ossClient.setBucketVersioning(request);
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Python

import alibabacloud_oss_v2 as oss

# Obtain access credentials from environment variables. Before running this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
# Use the default configuration of the SDK.
cfg = oss.config.load_default()
cfg.credentials_provider = credentials_provider
# Specify the region in which the CloudBox bucket is located, such as cn-hangzhou.
cfg.region = "cn-hangzhou"
# Specify the CloudBox ID. After you set the CloudBox ID, the SDK automatically switches the signing product to oss-cloudbox.
cfg.cloud_box_id = "cb-f8z7yvzgwfkl9q0h****"
# Specify the data domain of the CloudBox bucket in the CloudboxId.Region.oss-cloudbox.aliyuncs.com format.
cfg.endpoint = "cb-f8z7yvzgwfkl9q0h****.cn-hangzhou.oss-cloudbox.aliyuncs.com"
# Create an OSS client.
client = oss.Client(cfg)

# Enable versioning for the CloudBox bucket.
result = client.put_bucket_versioning(oss.PutBucketVersioningRequest(
    bucket="examplebucket",
    versioning_configuration=oss.VersioningConfiguration(
        status="Enabled",
    ),
))
print(f'status code: {result.status_code}, request id: {result.request_id}')

package main

import (
	"context"
	"log"

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

func main() {
	// Use the default configuration of the SDK and obtain access credentials from environment variables.
	// Before running this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		// Specify the region in which the CloudBox bucket is located, such as cn-hangzhou.
		WithRegion("cn-hangzhou").
		// Specify the data domain of the CloudBox bucket in the CloudboxId.Region.oss-cloudbox.aliyuncs.com format.
		WithEndpoint("cb-f8z7yvzgwfkl9q0h****.cn-hangzhou.oss-cloudbox.aliyuncs.com").
		// Specify the CloudBox ID. After you set the CloudBox ID, the SDK automatically switches the signing product to oss-cloudbox.
		WithCloudBoxId("cb-f8z7yvzgwfkl9q0h****")

	// Create an OSS client.
	client := oss.NewClient(cfg)

	// Enable versioning for the CloudBox bucket.
	request := &oss.PutBucketVersioningRequest{
		Bucket: oss.Ptr("examplebucket"),
		VersioningConfiguration: &oss.VersioningConfiguration{
			Status: oss.VersionEnabled,
		},
	}
	result, err := client.PutBucketVersioning(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to put bucket versioning %v", err)
	}
	log.Printf("put bucket versioning result:%#v\n", result)
}

Use the ossutil command line interface

Use ossutil to set the versioning state for a bucket. For information about how to install ossutil, see Install ossutil.

The following command enables versioning for a specified bucket.

ossutil api put-bucket-versioning --bucket examplebucket --versioning-configuration "{\"Status\":\"Enabled\"}"

For more information about this command, see put-bucket-versioning.

Use the REST API

For advanced customization, you can use the REST API directly. This requires you to write code to manually calculate the signature for each request. For more information, see PutBucketVersioning.

Suspend versioning

You can suspend versioning for a versioned bucket to stop OSS from generating new versions for objects. If a new version is generated for an object in a versioning-suspended bucket, OSS sets the ID of the new version to null and retains the previous versions of the object.