Configuring WORM Retention for an Object

Function

This API is used to configure or update the retention period for objects uploaded to a bucket with WORM enabled.

• 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 of an object can only be modified, but not deleted.

Working with Other Functions

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}

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

<Retention>
    <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.

Common errors are included in Table 2.

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
<Retention>
    <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.