By enabling versioning, you can store multiple versions of an object in the same bucket. For example, you can store multiple objects with the same object key “picture.jpg” in one bucket, but the objects have different version IDs such as 100000, 100101, and 120002. You can query, delete, or restore the objects by version ID. Versioning enables you to recover from data loss caused by accidental deletion or application failure. Versioning is ideal for the following scenarios:
There are three versioning states for a bucket: not enabled, enabled, or suspended.
- Once versioning is enabled for the bucket, it cannot return to the prior status (initial status). However, you can suspend versioning for the bucket so that subsequent uploads of objects will not generate multiple versions.
- For objects existing in the bucket before versioning is enabled, the version ID is "null".
- Enabling or suspending versioning will change the way COS makes requests when handling the objects but not the objects themselves.
- Only the root account and authorized sub-accounts can suspend versioning for a bucket.
You can upload, query, and delete objects in a bucket no matter what the versioning state is. When versioning is enabled or suspended, you can query and delete objects with or without version IDs.
For objects in the bucket before versioning is enabled, their version ID will be “null”. Enabling versioning will change the way COS handles the objects, such as how COS makes requests, but not the objects themselves. Objects with the same name uploaded thereafter will be stored in the same bucket with different version IDs. You can manage objects in a bucket with versioning enabled as described below:
An object is uploaded to both buckets with versioning enabled and not enabled in the same way, but with different version IDs. If versioning is enabled, COS will assign a unique version ID to any object uploaded to the bucket; if versioning is not enabled, the version ID will remain null.
If versioning is enabled for a bucket, when you perform PUT, POST, and COPY operations, COS will automatically assign a unique version ID to the objects added to the bucket.
As you can see below, when an object is uploaded to a bucket with versioning enabled, COS will assign it a unique version ID.
COS stores object version information in the versions parameter associated with the bucket and returns object versions in the order of storage time from the newest to the oldest.
You can query all versions of a particular object using the versions parameter together with the prefix request parameter. For more information on prefix, see GET Bucket Object Versions.
Below is a sample request for getting all versions of a specific object:
GET /?versions&prefix=ObjectKey HTTP/1.1
A GET request with no version ID specified returns the current version of an object. The following figure shows how a GET request returns the current version (the latest version) of the
A GET request with a version ID specified returns the specified version of an object. The following figure shows how a GET versionId request returns the specified version of the object. The request can also return the current version.
If you only want to query the metadata of an object instead of its content, you can use the HEAD operation. By default, you get the metadata of the latest version. To query the metadata of a specific object version, you need to specify its version ID when submitting the request.
To query the metadata of an object version:
You can delete unnecessary object versions whenever you want. When you make a DELETE request in a versioning-enabled bucket, there will be two scenarios:
Perform a simple DELETE operation with no version ID specified.
This is similar to putting the deleted objects to the "recycle bin". The objects are not permanently deleted and can be restored if needed.
As you can see below, if you do not specify a version ID, the DELETE operation will not delete the 123.txt object; instead, it will insert a delete marker and add a new version ID.
COS will insert a delete marker with a new version ID for the deleted objects. The delete marker will become the current version of the deleted objects. When you try to GET the objects with a delete marker, COS will assume that the objects do not exist and will return a 404 error.
If you delete an object with a version ID specified, the specified version of the object will be deleted permanently.
Versioning can be used to restore previous versions. You can do it in two ways:
When you suspend versioning, existing objects in your bucket do not change. What changes is how COS handles objects in future requests. The section below describes how to manage objects in a bucket where versioning is suspended.
Once you suspend bucket versioning, when you use PUT, POST, or COPY operations, COS will automatically add a “null” version ID to objects added to the bucket thereafter as shown below:
If there are versioned objects in the bucket, the objects newly uploaded to the bucket will become the current version with a version ID of null as shown below:
If there is already a null version in the bucket, it will be overwritten, and the original object content will also be replaced accordingly as shown below:
A GET Object request in a versioning-suspended bucket returns the current version of an object.
If versioning is suspended, a DELETE request will result in one of the following:
If an object has a null version in the bucket, the null version of the object will be deleted.
As you can see below, when you use a simple DELETE operation, COS will insert a delete marker for objects with a version ID of null.
Since a delete marker does not have content, you will lose the original content of the null version when a delete marker replaces it.
If an object does not have a null version in the bucket, a new delete marker will be added to the bucket.
As you can see below, if an object does not have a null version in the bucket, a simple DELETE will not remove anything; COS will just insert a delete marker.
Even in a bucket where versioning is suspended, the root account is still able to delete a specified version permanently.
The following figure shows that deleting a specified object version will delete the object permanently.
Only the root account can delete a specified object version permanently.