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 configuring object-level WORM, you must enable bucket-level WORM. If an object is protected by both bucket-level and object-level WORM, the object-level WORM policy takes precedence.
• The retention period of object-level WORM can only be extended but cannot be shortened.
• If you have deregistered your account or your account has been frozen, the WORM-protected objects will be permanently deleted.
• WORM does not protect parts generated during multipart uploads.
• When configuring bucket logging, do not store logs in a bucket with an active WORM retention policy. Because old files cannot be deleted, storage cost will continue to increase.
• If a bucket has WORM enabled, an append upload on this bucket will fail, with a 403 error returned.
• Only the compliance mode is supported.

• 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.region.example.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.region.example.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.