All Products
Search
Document Center

Object Storage Service:bucket-versioning

Last Updated:Dec 26, 2023

To restore an object to a previous version at any time after it is accidentally overwritten or deleted, run the bucket-versioning command to enable versioning. Object Storage Service (OSS) allows you to configure versioning for a bucket to protect objects that are stored in the bucket. After you enable versioning for a bucket, existing objects in the bucket are stored as previous versions when they are overwritten or deleted.

Usage notes

  • 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 Get started with 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 in the preceding command.

    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: Versioning is enabled 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, see Manage objects in a versioning-enabled bucket.

    • suspended: Versioning is suspended for the bucket. When an object is uploaded to a bucket for which versioning is suspended, OSS generates a version ID of null for the uploaded object. For more information, 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 versioning-enabled bucket.

  • Examples

    Run the following command to enable versioning for a bucket named examplebucket:

    ./ossutil64 bucket-versioning --method put oss://examplebucket enabled

    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

    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:

    bucket versioning status:Suspended
    
    0.168791(s) elapsed

    If a similar output is displayed, versioning is disabled for the bucket:

    bucket versioning status:Null
    
    0.158691(s) elapsed

Related operations

  • OSS manages an object that is uploaded to a versioning-enabled bucket and an unversioned bucket in the same way. After you enable versioning for a bucket, OSS generates a globally unique version ID for the object that you upload to the 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 restore 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 sync command, see View options.