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.

Notice
  • 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.
    Notice 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 a different region, you can use the -e option to specify the endpoint of the region in which the specified bucket resides. If you use ossutil to switch to a bucket that belongs to another Alibaba Cloud account, you can use the -i option to specify the AccessKey ID of the specified account, and use the -k option 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.