Manage the versioning feature for a CloudBox bucket - Object Storage Service

Versioning protects objects in an OSS on CloudBox bucket by preserving every overwritten or deleted object as a previous version. When accidental overwrites or deletions happen, recover any object to a previous version.

Important

All versions of an object consume storage space and incur storage fees. Configure lifecycle rules to automatically delete historical versions you no longer need. For instructions, see Configure lifecycle rules.

Prerequisites

Before you begin, make sure that you have:

OSS on CloudBox available in your region. OSS on CloudBox is supported only in China (Hangzhou), China (Shanghai), China (Shenzhen), China (Heyuan), China (Beijing), and China (Chengdu)
A cloud box purchased. For more information, see Purchase a cloud box
A Virtual Private Cloud (VPC) and a vSwitch created in the OSS on CloudBox. For more information, see Create a VPC and a vSwitch
A VPC internal network set up with a single tunnel configured for secure connection. To apply for this feature, contact technical support

Use cases

Enable versioning in these scenarios:

Recover deleted data: OSS does not provide a recycle bin. Use versioning to recover objects that have been deleted.
Recover overwritten data: In environments with frequent modifications—such as online collaborative documents or files stored in online storage—use versioning to recover a specific previous version of an object.

Usage notes

Permissions: Only the bucket owner or RAM users with the oss-cloudbox:PutBucketVersioning permission can enable versioning for an OSS on CloudBox bucket.
Feature conflict: The x-oss-forbid-overwrite header has no effect in a versioning-enabled OSS on CloudBox bucket. For more information, see PutObject.
SDK support: Versioning can only be configured using OSS SDK for Java version 3.15.0 or later.

How versioning works

Versioning states

A bucket can be in one of three versioning states: disabled, enabled, or suspended.

State	Behavior on overwrite	Behavior on deletion
Disabled (default)	The existing object is overwritten and cannot be recovered.	The object is permanently deleted.
Enabled	A new version with a globally unique version ID is created. The existing object is stored as a previous version.	A delete marker with a globally unique version ID is added as the current version. The existing object is stored as a previous version.
Suspended	A new version with a null version ID is created. If a previous null version or null delete marker exists, it is overwritten. Non-null versions are not affected.	A delete marker with a null version ID is added. If a previous null version or null delete marker exists, it is overwritten. Non-null versions are not affected.

State transitions:

The default state is disabled.
Once enabled, versioning cannot be rolled back to disabled—it can only be suspended.
Suspending versioning stops OSS from generating new versions for objects. If a new version is generated, OSS sets its ID to null and retains the previous versions of the object.

Data protection behavior

The following diagrams show how OSS handles objects when versioning is enabled or suspended. Version IDs are simplified for readability.

Overwrite in a versioning-enabled bucket: Each upload creates a new version with a unique version ID. Previous versions are retained.
Delete from a versioning-enabled bucket: OSS adds a delete marker as the current version instead of permanently deleting the object. Previous versions remain. Uploading an object with the same name after deletion creates a new version.
Overwrite in a versioning-suspended bucket: Each upload creates a new null version. If a null version already exists, it is overwritten; non-null versions are retained.
Delete from a versioning-suspended bucket: OSS adds a null delete marker as the current version. Existing non-null versions are not affected.

In both enabled and suspended states, deleted or overwritten objects are preserved as previous versions, making recovery possible.

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

Option 1: Enable versioning when creating a bucket

Log on to the OSS console.OSS
In the left-side navigation pane, choose Data Service > OSS on CloudBox Buckets.
On the OSS on CloudBox Buckets page, click Create Bucket in the upper-left corner.
In the Create Bucket panel, go to the Bucket Features section and turn on Versioning. For information about other parameters, see Create an OSS on CloudBox bucket.
Click OK.

Option 2: Enable versioning for an existing bucket

In the left-side navigation pane, choose Data Service > OSS on CloudBox Buckets.
Click the bucket for which you want to configure versioning.
In the left-side navigation tree, choose Content Security > Versioning.
On the Versioning page, click Enable to the right of Versioning.

Use OSS SDK for Java

OSS SDK for Java version 3.15.0 or later is required.

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.
        // Call the shutdown method to release resources when the OSSClient is no longer in use.
        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

For installation instructions, see Install ossutil.

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

For the full command reference, see put-bucket-versioning.

Use the RESTful API

To call the API directly, include 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.