Versioning is a data protection feature for OSS on CloudBox buckets. After you enable versioning, objects that are overwritten or deleted are saved as previous versions. If an object is accidentally overwritten or deleted, you can restore it to any of its previous versions.
Prerequisites
OSS on CloudBox is supported only in the China (Hangzhou), China (Shanghai), China (Shenzhen), China (Heyuan), China (Beijing), and China (Chengdu) regions.
A cloud box is purchased. For more information, see Purchase a cloud box.
A Virtual Private Cloud (VPC) and a vSwitch are created in the OSS on CloudBox. For more information, see Create a VPC and a vSwitch.
A VPC internal network is set up, and a single tunnel is configured to provide secure connection. To apply for this feature, please contact technical support.
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
Permissions
Only the owner of the OSS on CloudBox bucket and Resource Access Management (RAM) users who are granted 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 for file uploads. 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, versioning for a bucket is disabled. After versioning is enabled, it cannot be disabled. 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 generates "null" as the version ID for each newly uploaded object.
Note When versioning is enabled for an OSS on CloudBox bucket, all versions of an object are stored. These versions consume storage space. You can configure lifecycle rules to delete previous 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 Java SDK
You can enable versioning using the Java software development kit (SDK). The Java SDK must be version 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 this 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, for example, examplebucket.
String bucketName = "examplebucket";
// Specify the region where the OSS on CloudBox bucket is located.
String region = "cn-hangzhou";
// Specify the CloudBox ID.
String cloudBoxId = "cb-f8z7yvzgwfkl9q0h****";
// Create an OSSClient instance.
// When the OSSClient instance is no longer used, call the shutdown method to release 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();
}
}
}
}
Use ossutil
You can use ossutil to configure versioning for a bucket. For information about its installation, see Install ossutil.
Below is the sample command for enabling versioning.
ossutil api put-bucket-versioning --bucket examplebucket --versioning-configuration "{\"Status\":\"Enabled\"}"
For more information about this command, see put-bucket-versioning.
Use a REST API
If your program requires a high level of customization, you can send REST API requests directly. If you use this method, you must manually write code to calculate signatures. 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 navigation pane on the left, choose . Then, in the bucket list, click the destination bucket.
In the left-side navigation pane, choose .
Use the Java SDK
You can suspend versioning using the Java SDK. The Java SDK must be version 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 this 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, for example, examplebucket.
String bucketName = "examplebucket";
// Specify the region where the OSS on CloudBox bucket is located. For example, if the bucket is in the China (Hangzhou) region, set Region to cn-hangzhou.
String region = "cn-hangzhou";
// Specify the CloudBox ID.
String cloudBoxId = "cb-f8z7yvzgwfkl9q0h****";
// Create an OSSClient instance.
// When the OSSClient instance is no longer used, call the shutdown method to release 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 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 use ossutil to configure versioning for a bucket. For information about its installation, see Install ossutil.
Below is the sample command for suspending versioning.
ossutil api put-bucket-versioning --bucket examplebucket --versioning-configuration "{\"Status\":\"Suspended\"}"
For more information about this command, see put-bucket-versioning.
Use a REST API
If your program requires a high level of customization, you can send REST API requests directly. If you use this method, you must manually write code to calculate signatures. For more information, see PutBucketVersioning.