Configuring Versioning for a Bucket

Functions

This operation restores an object that is mistakenly overwritten or deleted. You can use versioning to save, query, and restore objects of different versions. Versioning allows you to easily recover lost data due to misoperations or program faults. Versioning can also be used for retaining and archiving data.

By default, versioning is disabled for a bucket.

Once WORM is enabled for a bucket, OBS automatically enables versioning for the bucket and the versioning cannot be suspended for that bucket.

You can perform this operation to enable or suspend versioning for a bucket.

After versioning is enabled for a bucket:

• OBS creates a unique version ID for each uploaded object. Namesake objects are not overwritten and are distinguished by their own version IDs.
• You can download objects by specifying version IDs. By default, the latest object is downloaded if the version ID is not specified.
• You can specify a version ID to permanently delete a specific object. If an object is deleted with no version ID specified, only a delete marker with a unique version ID is generated, but the object is not physically deleted.
• The latest objects in a bucket are returned by default after a GET Object request. You can also send a request to obtain a bucket's objects with all version IDs.
• Except delete markers, storage space occupied by objects with all version IDs, excluding object metadata, is billed.

After versioning is suspended for a bucket:

• Existing objects with version IDs are not affected.
• The system creates version ID null to an uploaded object and the object will be overwritten after a namesake one is uploaded.
• You can download objects by specifying version IDs. By default, the latest object is downloaded if the version ID is not specified.
• You can specify a version ID to delete a specific object. If an object is deleted with no version ID specified, OBS creates a delete marker with a version ID of null and deletes the object whose version ID is null.
• Except delete markers, storage space occupied by objects with all version IDs, excluding object metadata, is billed.

Only the bucket owner can set versioning for the bucket.

Authorization Information

To call this API, you must be the bucket owner or have the permission to configure versioning for a bucket. You are advised to use IAM or bucket policies for authorization. For details about OBS authorization methods, see Differences Between OBS Permissions Control Methods.

• If you use IAM for authorization, you need to use either role/policy-based authorization or identity policy-based authorization and configure the required permissions:
  • If you use role/policy-based authorization (IAM v3 APIs in the old IAM version), you need to grant the obs:bucket:PutBucketVersioning permission. For details, see Creating a Custom IAM Policy.
  • If you use identity policy-based authorization (IAM v5 APIs in the new IAM version), you need to grant the obs:bucket:putBucketVersioning permission, as shown in the following table. For details, see Creating a Custom IAM Identity Policy.

    Action	Access Level	Resource Type (*: Required)	Condition Key	Alias	Dependencies
    obs:bucket:putBucketVersioning	Write	bucket *	g:EnterpriseProjectId g:ResourceTag/<tag-key>	-	-
    		-	obs:EpochTime obs:SourceIp obs:TlsVersion obs:CustomDomain

• If you use bucket policies for authorization, you need to grant the obs:bucket:putBucketVersioning permission. For details, see Creating a Custom Bucket Policy.

Request Syntax

1
2
3
4
5
6
7
8
9

PUT /?versioning HTTP/1.1 
Host: bucketname.obs.region.myhuaweicloud.com 
Date: date
Authorization: authorization
Content-Length: length

<VersioningConfiguration> 
    <Status>status</Status> 
</VersioningConfiguration>

Request Parameters

This request contains no parameters.

Request Headers

This request uses common headers. For details, see Table 3.

Request Elements

This request contains elements to configure the bucket versioning in XML format. Table 1 lists the request elements.

Response Syntax

1
2
3
4

HTTP/1.1 status_code
Date: date

Content-Length: length

Response Headers

The response to the request uses common headers. For details, see Table 1.

Response Elements

This response contains no elements.

Error Responses

No special error responses are returned. For details about error responses, see Table 2.

Sample Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

PUT /?versioning HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.com
Accept: */*
Date: WED, 01 Jul 2015 03:14:18 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:sc2PM13Wlfcoc/YZLK0MwsI2Zpo=
Content-Length: 89

<VersioningConfiguration>     
    <Status>Enabled</Status> 
</VersioningConfiguration>

Sample Response

1
2
3
4
5
6

HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: BF26000001643672B973EEBC5FBBF909
x-obs-id-2: 32AAAQAAEAABSAAgAAEAABAAAQAAEAABCSH6rPRHjQCa62fcNpCCPs7+1Aq/hKzE
Date: Date: WED, 01 Jul 2015 03:14:18 GMT
Content-Length: 0

Sample Request: Suspending Versioning

PUT /?versioning HTTP/1.1
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:iqSPeUBl66PwXDApxjRKk6hlcN4=
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.com
Date: WED, 01 Jul 2015 02:37:22 GMT
Content-Type: application/xml
 
<VersioningConfiguration>
    <Status>Suspended</Status>
</VersioningConfiguration>

Sample Response: Suspending Versioning

x-obs-id-2: 32AAAQAAEAABSAAgAAEAABAAAQAAEAABCSjqfl2JttwovZb7kTM+xkyQQyhNyOOC
x-obs-request-id: 0000018A2C044BC6D24722440C5EC81C
Server: OBS
Content-Length: 0
Date: WED, 01 Jul 2015 02:37:22 GMT