When versioning is enabled for a bucket, OSS assigns a unique ID for each version of all objects in the bucket. The content and ACL of existing objects in the bucket remain unchanged. Versioning prevents unintended overwrites and deletions on your data. You can also use versioning to retrieve a previous version of an object and recover the previous version as the current version at any time.

Note
  • By default, versioning is not enabled for a bucket. To enable versioning for a bucket, you must manually configure this feature.
  • When versioning is enabled for a bucket, the bucket maintains the current versions and previous versions for its objects.
  • When versioning is not enabled for a bucket, OSS sets the object version IDs to null.

OSS allows you to upload objects and list, download, delete, and recover object versions for a versioning-enabled bucket.

Upload objects

When you upload an object to a versioning-enabled bucket, OSS assigns a unique version ID to the object.

Note When you perform operations such as PutObject, PostObject, CopyObject, or MultipartUpload on an object, OSS assigns a unique version ID to the object.
When you use the PutObject operation to upload an object with the key of example.jpg, OSS assigns a unique version ID of 111111 to the object. The following figure shows the process.
When you use the PutObject operation to upload the same object with the key of example.jpg, OSS assigns a new unique version ID of 222222 to the object and stores this version as the current version in the bucket. Version 111111 becomes a previous version. The following figure shows the process. When you use the PutObject operation to upload the same object with the key of example.jpg again, OSS assigns a new unique version ID of 333333 to the object and stores this version as the current version in the bucket. Versions 111111 and 222222 become previous versions. The following figure shows the process.

List object versions

You can call the GetBucketVersions(ListObjectVersions) operation to obtain information of all object versions in a versioning-enabled bucket, including delete markers.

Note
  • Unlike GetBucketVersions(ListObjectVersions), the GetBucket (ListObject ) operation returns only the current version of the bucket. The current version is not a delete marker.
  • Each request can return up to 1,000 versions. To list more versions of an object, you must send multiple requests to retrieve the list of all versions.

    For example, if a bucket contains two objects whose names are example.jpg and photo.jpg. The example.jpg object has 900 versions. The photo.jpg object has 500 versions. The first request returns 900 versions of the photo.jpg object and 100 versions of the photo.jpg object. Versions are returned based on the alphabetical order of keys first and then in the order in which these versions are stored.

When you call GetBucketVersions for a versioning-enabled bucket, all object versions in the bucket are returned, including delete markers. When you call GetBucket for a versioning-enabled bucket, only current versions of objects in the bucket are returned and the current versions are not delete markers. The following figure shows the process.

Download object versions

OSS allows you to download an object of the current or a specified version from a versioning-enabled bucket.

By default, the current version of the object is returned if the object version ID is not specified when you use the GetObject request to download an object. The following figure shows that current version (ID: 333333) of the object is returned.
If the current version is a delete marker, the GetObject request returns 404 Not Found.
To download an object of a specified version, specify the object version ID in the GetObject request. The following figure shows that the specified version ID is 222222.

Delete object versions

OSS allows you to specify an object version ID or configure lifecycle rules to permanently delete an object in a versioning-enabled bucket. If you do not specify an object version ID in the DeleteObject request, OSS inserts a delete marker into the bucket, and the delete marker becomes the current version of the object.

Note By default, the current version and previous versions of an object are not deleted when you perform the DeleteObject operation on a versioning-enabled bucket.
If you do not specify an object version ID in the DeleteObject request:
  • OSS inserts a delete marker into the bucket, and the delete marker becomes the current version of the object. The delete marker has a unique version ID, but does not store any data or have ACL configured. The following figure shows that the current version becomes a delete marker and the version ID is 444444.
  • If you specify an object version ID in the DeleteObject request, OSS permanently deletes the object version. The following figure shows that object version 333333 is deleted.

Recover previous versions

When versioning is enabled, all versions of objects in a bucket are preserved. You can recover a specified previous version to make it the current version.

You can use either of the following methods to recover a previous version as the current version:
  • Use CopyObject to copy a previous version of an object to the same bucket

    The copied object becomes the current version of that object and all object versions are preserved.

    In the following figure, a previous version with the version ID of 222222 is copied to the same bucket. OSS assigns a new version ID of 444444 to the object. The new version becomes the current version of the object. Therefore, the object has its previous version of 222222 and its copy 444444 as the current version.
  • Permanently delete the current version of an object

    In the following figure, after you permanently delete the current version of an object by specifying the current version ID of 222222 in the DeleteObject request, the latest previous version of 111111 becomes the current version of the object.

Note
  • We recommend that you use CopyObject to recover a previous version as the current version.
  • You can also configure lifecycle rules to delete previous versions of an object.