When versioning is enabled for a bucket, Object Storage Service (OSS) generates a unique ID for each version of all objects in the bucket. The content and access control list (ACL) of existing objects in the bucket remain unchanged. Versioning prevents your data from being accidentally overwritten or deleted and allows you to query or restore previous versions of objects.

Usage notes

Take note of the following items when you upload, list, download, delete, and restore objects in versioning-enabled buckets:

  • When versioning is enabled for a bucket, a current version and its previous versions are stored for each object in the bucket.
  • The version ID of an object that is uploaded before versioning is enabled is set to null.
  • For ease of viewing, all version IDs in the following figures are in the simple format.

For more information about versioning, see Overview.

Upload objects

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

Note OSS generates unique version IDs for objects uploaded by using PutObject, PostObject, CopyObject, and MultipartUpload.
In the following figure, when you use the PutObject operation to upload an object whose key is example.jpg, OSS generates a unique version ID of 111111 for the object.

When you use the PutObject operation to upload an object that has the same key as the existing object example.jpg, OSS generates a new version with a unique version ID of 222222 for the object and stores the new version as the current version of the object. Version 111111 is stored as a previous version. When you use the PutObject operation to upload an object that has the same key again, OSS generates a new version with a unique version ID of 333333 for the object and stores the new version as the current version of the object. In the following figure, versions 111111 and 222222 are stored as previous versions.

You can use the cp command and OSS SDKs for the following programming languages to upload objects to a versioning-enabled bucket: OSS SDK for Java, OSS SDK for PHP, OSS SDK for Node.js, OSS SDK for Python, OSS SDK for .NET, OSS SDK for Go, and OSS SDK for C++.

List objects

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

  • Compared with the GetBucketVersions (ListObjectVersions) operation, the GetBucket (ListObject) operation returns only the current object versions that are not delete markers in a bucket.
  • Up to 1,000 object versions can be returned for a single GetBucketVersions (ListObjectVersions) request. You can send multiple GetBucketVersions (ListObjectVersions) requests to obtain all object versions in a versioning-enabled bucket.

    For example, 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. If you send a GetBucketVersions (ListObjectVersions) request, the 900 versions of the example.jpg object and 100 versions of the photo.jpg object are returned. Versions are returned in alphabetical order of object keys first and then in the order of time when the versions are generated.

In the following figure, all object versions including delete markers are returned when the GetBucketVersions (ListObjectVersions) operation is called. Only current object versions that are not delete markers are returned when the GetBucket(ListObject) operation is called. Therefore, only the current version of the photo.jpg object, whose version ID is 444444, is returned.

You can use the ls command and the following OSS SDKs to list objects in a versioning-enabled bucket: OSS SDK for Java, OSS SDK for Node.js, OSS SDK for Python, and OSS SDK for Go.

Download objects

You can download the current version or a specified version of an object from a versioning-enabled bucket.

By default, if a GetObject request in which no version ID is specified is sent to download an object, the current version of the object is returned. In the following figure, the current version of the object, whose version ID is 333333, is returned.

If a GetRequest in which the no version ID is specified is sent to download an object and the current version of the object is a delete marker, 404 Not Found is returned.

To download a specific version of an object, you must specify the version ID in the GetObject request. In the following figure, a request in which a version ID is specified is sent to download the object whose version ID is 222222.

You can use the cp command and OSS SDKs for the following programming languages to download objects from a versioning-enabled bucket: OSS SDK for Java, OSS SDK for PHP, OSS SDK for Node.js, OSS SDK for Python, OSS SDK for .NET, OSS SDK for Go, and OSS SDK for C++.

Delete objects

You can specify an object version ID in the DeleteObject request or configure lifecycle rules to permanently delete a version of an object in a versioning-enabled bucket. If you do not specify an object version ID in the DeleteObject request, OSS adds a delete marker as the current version of the object.

Notice
  • By default, if you do not specify a version ID in the DeleteObject request, the current version and previous versions of the object are not deleted.
  • We recommend that you do not enable the OSS-HDFS service and versioning for a bucket at the same time.

    If you enable versioning for a bucket with the OSS-HDFS service enabled, data that is overwritten or deleted is saved as previous versions. When you overwrite or delete data in the .dlsdata/ directory by using the methods that are supported by the OSS-HDFS service, a message that indicates that the data is successfully overwritten or deleted is displayed. OSS retains the data that is overwritten or deleted as previous versions because versioning is enabled for the bucket.

    In this case, you can specify version IDs to delete previous versions of objects from the .dlsdata/ directory.

In addition, you can specify the Expiration element in lifecycle rules to delete the expired current version of objects in a versioning-enabled bucket. You can also specify the NoncurrentVersionExpiration element in lifecycle rules to permanently delete the expired previous versions of objects in a versioning-enabled bucket. The two elements have the following differences:

  • The Expiration element is specified in lifecycle rules to delete the expired current version of objects. When an object is deleted based on a lifecycle rule in which the Expiration element is specified, OSS stores the current version of the object as a previous version and adds a delete marker as the new current version of the object.
  • The NoncurrentVersionExpiration element is specified in lifecycle rules to delete expired previous versions of objects. A previous version deleted based on a lifecycle rule in which the NoncurrentVersionExpiration element is specified is permanently deleted and cannot be restored.

For more information about how to use versioning with lifecycle rules, see Configuration elements.

The following examples describe how OSS deletes an object when the version ID is specified and not specified in the DeleteObject request.

  • If the version ID is not specified in the DeleteObject request, OSS adds a delete marker as the current version of the object to delete. The delete marker has a unique version ID but does not have data and ACL. In the following figure, a delete marker with the version ID of 444444 is added as the current version.
  • If the version ID is specified in the DeleteObject request, the specified version is permanently deleted. In the following figure, the version whose ID is 333333 is permanently deleted.

You can use the rm command and OSS SDKs for the following programming languages to delete objects from a versioning-enabled bucket: OSS SDK for Java, OSS SDK for PHP, OSS SDK for Node.js, OSS SDK for Python, OSS SDK for .NET, OSS SDK for Go, and OSS SDK for C++.

Restore objects

When versioning is enabled for a bucket, all versions of objects in the bucket are preserved. You can restore a specified previous version of an object as the current version.

You can restore a previous version of an object as the current version by using one of the following methods:
  • Use CopyObject to copy the previous version to the same bucket

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

    In the following figure, a previous version whose ID is 222222 is copied to the same bucket. OSS adds the copied version as a new version whose ID is 444444. The new version becomes the current version of the object. As a result, the object has two versions that have the same content: 222222 and 444444. Version 222222 is a previous version and version 444444 is the current version.
  • Permanently delete the current version of the object

    In the following figure, the current version whose ID is 222222 is permanently deleted by using a DeleteObject request in which the version ID is specified. The most recent previous version whose ID is 111111 becomes the current version of the object.

Notice We recommend that you use CopyObject to restore a previous version as the current version because the current version cannot be restored after it is permanently deleted.

You can use the cp command and OSS SDKs for the following programming languages to restore a previous version as the current version in a versioning-enabled bucket: OSS SDK for Java, OSS SDK for PHP, OSS SDK for Node.js, OSS SDK for Python, OSS SDK for .NET, OSS SDK for Go, and OSS SDK for C++.