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.
- 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.
When you upload an object to a versioning-enabled bucket, OSS assigns a unique version ID to the object.
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.
- 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.
Download object versions
OSS allows you to download an object of the current or a specified version from a versioning-enabled bucket.
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.
- 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.
- 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.
- 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.