How to configure versioning for an OSS on CloudBox bucket - Object Storage Service

You can enable versioning for an Object Storage Service (OSS) on CloudBox bucket to protect objects stored in the OSS on CloudBox bucket. When you overwrite or delete objects that are stored in a versioning-enabled OSS on CloudBox bucket, OSS saves the objects as previous versions in the OSS on CloudBox bucket. After you enable versioning for an OSS on CloudBox bucket, you can recover objects in the OSS on CloudBox bucket to a previous version to protect your data from being accidentally overwritten or deleted.

Prerequisites

OSS on CloudBox is supported only in the China (Hangzhou), China (Shenzhen), China (Heyuan), China (Beijing), and China (Chengdu) regions.
A cloud box is purchased. For more information, see Purchase a cloud box.

Scenarios

To ensure data security, we recommend that you enable versioning in the following scenarios:

Recover deleted data
OSS does not provide the recycle bin feature. You can use the versioning feature to recover deleted data.
Recover overwritten data
Numerous temporary versions are created in scenarios in which modifications are frequently made, such as online collaborative documents and documents stored in online storage. You can use the versioning feature to recover a specific version of an object stored in the bucket.

Usage notes

Required permissions
Only the OSS on CloudBox bucket owner or RAM users who have the oss-cloudbox:PutBucketVersioning permission can enable versioning for an OSS on CloudBox bucket.
Feature conflicts
The x-oss-forbid-overwrite header in a request to upload data to a versioning-enabled OSS on CloudBox bucket does not take effect. For more information, see Request headers.

Versioning states

A bucket can be in one of the following versioning states: disabled, enabled, and suspended.

By default, the versioning state of an OSS on CloudBox bucket is disabled. After versioning is enabled for an OSS on CloudBox bucket, the versioning state of the OSS on CloudBox bucket cannot be rolled back to disabled. However, you can suspend versioning for an OSS on CloudBox bucket for which versioning is enabled.
When an object is uploaded to an OSS on CloudBox bucket for which versioning is enabled, OSS generates a random string as the globally unique version ID of the object.
When an object is uploaded to an OSS on CloudBox bucket for which versioning is suspended, OSS generates the "null" string as the version ID of the object.

Note

In a versioning-enabled OSS on CloudBox bucket, all versions of an object are stored. These versions consume storage space and you are charged storage fees. We recommend that you configure lifecycle rules to delete historical versions that you no longer need.

Data protection

The following table describes how OSS processes deleted and overwritten data in buckets in different versioning states to help you understand the data protection mechanism of versioning.

Versioning state	Object overwriting	Object deletion
Disabled	The existing object is overwritten and cannot be recovered.	The object is deleted and no longer stored in OSS.
Enabled	A new version with a unique ID is generated for the object. The existing object is stored as a previous version.	A delete marker with a globally unique version ID is added to the object as the current version. The existing object is stored as a previous version.
Suspended	A new version whose version ID is null is generated for the object. If the object already has a previous version or delete marker whose version ID is null, the previous version or delete marker is overwritten by the new null version. Other previous versions or delete markers whose version IDs are not null are not affected.	A delete marker whose version ID is null is added to the object. If the object already has a previous version or delete marker whose version ID is null, the previous version or delete marker is overwritten by the new delete marker. Other previous versions or delete markers whose version IDs are not null are not affected.

The following figures show how OSS processes data when an object with the same name as an existing object is uploaded to or an object is deleted from a bucket for which versioning is enabled or suspended. For readability, all version IDs in the figures are in the simple format.

Overwrite an object in a versioning-enabled bucket
When you upload an object repeatedly to a versioning-enabled bucket, the object is overwritten in each upload. A version with a unique version ID is generated for the object each time the object is overwritten.
Delete an object from a versioning-enabled bucket
When you delete an object from a versioning-enabled bucket, OSS adds a delete marker to the object as the current version of the object instead of permanently deleting the object. The previous versions of the object are not deleted. If you upload an object with the same name after the delete marker is added, a new version with a unique version ID is added as the current version.
Overwrite an object in a versioning-suspended bucket
When you upload an object with the same name as an existing object in a bucket for which versioning is suspended, a new version whose version ID is null is added to the bucket and the previous versions of the object are retained. If you upload another object with the same name to the bucket again, a new version whose version ID is null overwrites the previous null version.
Delete an object from a versioning-suspended bucket
When you delete an object from a bucket for which versioning is suspended, OSS adds a delete marker to the object as the current version of the object instead of permanently deleting this object. The previous versions of the object are not deleted.

In summary, deleted and overwritten data is stored as previous versions in a versioning-enabled or versioning-suspended bucket. You can recover objects in the bucket to a previous version to protect your data from being accidentally overwritten or deleted.

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.
3. On the OSS on CloudBox Buckets page, click Create Bucket in the upper-left corner.
4. In the Create Bucket panel, configure the parameters.
  In the Bucket Features section, turn on Versioning. For more information about how to configure other parameters, see Create an OSS on CloudBox bucket.
5. 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.
2. On the OSS on CloudBox Buckets page, click the OSS on CloudBox bucket for which you want to configure versioning.
3. In the left-side navigation tree, choose Content Security > Versioning.
4. On the Versioning page, click Enable to the right of Versioning.

Use OSS SDK for Java

You can enable versioning only by using OSS SDK for Java. The version of OSS SDK for Java must be 3.15.0 or later.

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 the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the name of the OSS on CloudBox bucket. Example: examplebucket. 
        String bucketName = "examplebucket";
        // Specify the region in which the OSS on CloudBox bucket is located. 
        String region = "cn-hangzhou";
        // Specify the ID of the cloud box. 
        String cloudBoxId = "cb-f8z7yvzgwfkl9q0h****";

        // Create an OSSClient instance. 
        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 OSS on CloudBox 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();
            }
        }
    }
}

Use ossutil

You can enable versioning by using ossutil. For more information, see Configure the versioning status of a bucket.

Use the OSS API

If your business requires a high level of customization, you can directly call RESTful APIs. To directly call an API, you must include the signature calculation in your code. 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.

Use the OSS console

In the left-side navigation pane, choose Data Service > OSS on CloudBox Buckets.
On the OSS on CloudBox Buckets page, click the OSS on CloudBox bucket for which you want to suspend versioning.
In the left-side navigation pane, choose Redundancy for Fault Tolerance > Versioning.

Use OSS SDK for Java

You can suspend versioning only by using OSS SDK for Java. The version of OSS SDK for Java must be 3.15.0 or later.

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 the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the name of the OSS on CloudBox bucket. Example: examplebucket. 
        String bucketName = "examplebucket";
        // Specify the region in which the OSS on CloudBox bucket is located. 
        String region = "cn-hangzhou";
        // Specify the ID of the cloud box. 
        String cloudBoxId = "cb-f8z7yvzgwfkl9q0h****";

        // Create an OSSClient instance. 
        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 OSS on CloudBox bucket to SUSPENDED. 
            BucketVersioningConfiguration configuration = new BucketVersioningConfiguration();
            configuration.setStatus(BucketVersioningConfiguration.SUSPENDED);
            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();
            }
        }
    }
}

Use ossutil

You can suspend versioning by using ossutil. For more information, see Configure the versioning status of a bucket.

Use the OSS API