Configuring WORM Retention for an Object

Function

This API configures or updates the WORM retention period for objects uploaded to a WORM-enabled bucket. The retention period is configured using the retention parameter in the API.

• If you did not configure a retention period or apply the default bucket-level protection rule when uploading an object, you can call this API to configure a retention period for the object.
• If you already configured a retention period or applied the default bucket-level protection rule when uploading an object, you can call this API to prolong the retention period for the object. The retention period cannot be shortened.
• The retention period of an object can only be prolonged. It cannot be shortened or deleted.

Working with Other Functions

Constraints

• Before enabling bucket-level WORM, you need to enable versioning. Configuring WORM on OBS Console automatically enables versioning for the bucket, and versioning cannot be suspended afterward. When configuring WORM using APIs, you must first call the API that enables versioning for the bucket. WORM protects objects based on the object version IDs. Only object versions with any WORM retention policy configured can be protected. Assume that object test.txt 001 is protected by WORM. If another file with the same name is uploaded, a new object version test.txt 002 with no WORM policy configured will be generated. In such case, test.txt 002 is not protected and can be deleted. When you download an object without specifying a version ID, the current object version (test.txt 002) will be downloaded.
• A lifecycle rule cannot delete WORM-protected objects, but can transition their storage class. After an object is no longer protected, it will be deleted when meeting the expiration rule in a lifecycle configuration.
• Buckets with WORM enabled do not support cross-region replication.
• If you have deregistered your account or your account has been frozen, the WORM-protected objects will be permanently deleted.
• WORM-based protection is not available for migration.
• The metadata of a WORM-protected object can still be modified.
• Parallel file systems do not support WORM.

• WORM must be enabled for the bucket, and the retention period can only be prolonged, not shortened.

Authorization

To call this API, you must be the object owner or have the permission to configure WORM retention for an object. 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 must have the obs:object:PutObjectRetention 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 must have the obs:object:putObjectRetention 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:object:putObjectRetention	Write	object *	g:EnterpriseProjectId	-	-
    		-	obs:EpochTime obs:SourceIp obs:TlsVersion obs:CustomDomain

• If you use bucket policies for authorization, you must have the obs:object:PutObjectRetention permission. For details, see Creating a Custom Bucket Policy.

URI

PUT /{object_key}?retention

Calling Method

For details, see Calling APIs. Before calling this API, calculate the API signature and add it to the request.

You can debug this API in API Explorer.

Request Syntax

PUT /ObjectName?retention&versionId=versionid HTTP/1.1 
Host: bucketname.obs.region.myhuaweicloud.com 
Date: date
Authorization: authorization

<?xml version="1.0" encoding="UTF-8"?> 
<Retention xmlns="http://obs.cn-north-4.myhuaweicloud.com/doc/2015-06-30/">
    <Mode>String</Mode>
    <RetainUntilDate>Timestamp</RetainUntilDate>
</Retention>

URI Parameters

Table 1 describes the request parameters.

Request Headers

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

Request Body

Response Syntax

HTTP/1.1 status_code
Date: date
Content-Length: length

Response Headers

This response uses common headers. For details, see Table 1.

Response Body

This response contains no elements.

Error Responses

Table 4 describes possible special errors in this request.

Refer to Error Code Overview for all other errors.

Sample Request

PUT /objectname?retention HTTP/1.1
Host: bucketname.obs.region.myhuaweicloud.com 
Date: Wed, 01 Jul 2015 02:25:05 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:75/Y4Ng1izvzc1nTGxpMXTE6ynw=
Content-Type: application/xml
Content-Length: 157
<?xml version="1.0" encoding="UTF-8"?> 
<Retention xmlns="http://obs.cn-north-4.myhuaweicloud.com/doc/2015-06-30/">
    <Mode>COMPLIANCE</Mode>
    <RetainUntilDate>1435728035000</RetainUntilDate>
</Retention>

Sample Response

HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: BF260000016435CE298386946AE4C482
x-obs-id-2: 32AAAQAAEAABSAAgAAEAABAAAQAAEAABCT9W2tcvLmMJ+plfdopaD62S0npbaRUz
Date: Wed, 01 Jul 2015 02:25:06 GMT
Content-Length: 0

Helpful Links

• For more information about WORM, see Configuring WORM to Protect Objects from Being Overwritten or Deleted.
• For details about the billing items involved in API operations, see Billing Items.