bucket-versioning - Object Storage Service - Alibaba Cloud Documentation Center

Object Storage Service (OSS) allows you to configure versioning for a bucket to protect objects stored in the bucket. After you enable versioning for a bucket, data that is overwritten or deleted in the bucket is saved as a previous version. Versioning allows you to recover a previous version of an object to protect the object from being accidentally overwritten or deleted. This topic describes how to run the bucket-versioning command to configure or query the versioning status of a bucket.

Important

Sample command lines in this topic are based on the 64-bit Linux system. For other systems, replace ./ossutil64 in the commands with the corresponding binary name. For more information, see ossutil.
For more information about versioning, see Overview.

Configure the versioning status of a bucket

Command syntax

./ossutil64 bucket-versioning --method put oss://bucketname versioning

The following table describes the parameters that you can configure when you run this command to configure the versioning status of a bucket.


Parameter	Description
bucketname	The name of the bucket whose versioning status you want to configure.
versioning	The versioning status of the bucket that you want to configure. Valid values: enabled: OSS enables versioning for the bucket. When an object is uploaded to a bucket that has versioning enabled, OSS generates a random string as the globally unique version ID of the object. For more information about how to manage objects in a versioned bucket, see Manage objects in a versioning-enabled bucket. suspended: OSS suspends versioning for the bucket. When an object is uploaded to a bucket for which versioning is suspended, OSS generates a string null as the version ID of the object. For more information about how to manage objects in a bucket for which versioning is suspended, see Manage objects in a versioning-suspended bucket. Important By default, the versioning status of a bucket is disabled. After versioning is enabled for a bucket, the versioning status of the bucket cannot be set back to disabled. However, you can suspend versioning for a versioned bucket.

Examples
You can run the following command to enable versioning for a bucket named examplebucket:
```
./ossutil64 bucket-versioning --method put oss://examplebucket enabled
```
You can run the following command to suspend versioning for a bucket named examplebucket:
```
./ossutil64 bucket-versioning --method put oss://examplebucket suspended
```
If a similar output is displayed, the versioning status of the bucket named examplebucket is configured:
```
0.261209(s) elapsed
```

Query the versioning status of a bucket

Command syntax

./ossutil64 bucket-versioning --method get oss://bucketname

Examples
You can run the following command to query the versioning status of a bucket named examplebucket:
```
./ossutil64 bucket-versioning --method get oss://examplebucket
```
If a similar output is displayed, versioning is enabled for the bucket:
```
bucket versioning status:Enabled

0.218001(s) elapsed
```
If a similar output is displayed, versioning is suspended for the bucket named examplebucket:
```
bucket versioning status:Suspended

0.168791(s) elapsed
```
If a similar output is displayed, versioning is disabled for the bucket named examplebucket:
```
bucket versioning status:Null

0.158691(s) elapsed
```

Related operations

OSS manages an object that is uploaded to a versioned bucket and an unversioned bucket in the same way. However, OSS generates a globally unique version ID for an object that is uploaded to a versioned bucket. For more information, see Upload objects.
After you enable versioning for a bucket, objects that are overwritten or deleted in the bucket are saved as previous versions. You can specify a version ID to download the specified version of an object. For more information, see Download objects. You can specify a version ID to recover the specified previous version of an object. For more information, see Copy objects.

Common options

If you use ossutil to switch to a bucket that is located in another region, add the -e option to the command to specify the endpoint of the region in which the specified bucket is located. If you use ossutil to switch to a bucket that belongs to another Alibaba Cloud account, you can add the -i option to the command to specify the AccessKey ID of the specified account, and add the -k option to the command to specify the AccessKey secret of the specified account.

For example, you can run the following command to enable versioning for a bucket named examplebucket, which is located in the China (Hangzhou) region and is owned by another Alibaba Cloud account:

./ossutil64 bucket-versioning--method put oss://examplebucket enabled -e oss-cn-hangzhou.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA****  -k 67DLVBkH7EamOjy2W5RVAHUY9H****

For more information about other common options that you can use for the bucket-versioning command, see Common options.