putObjectRetention method
Puts retention on the object version or enables/disables a previously set lock.
To be able to put locks on object versions, enable object lock in the bucket. For this, use the putObjectLockConfiguration method.
Only a user with the storage.admin role can change a lock once it was set. For a governance-mode retention, use a header that confirms retention bypass (see below). You can only extend compliance-mode retention. To check retention status, use the getObjectRetention method.
For more information on getting started with the API and the general request format, see How to use the S3 API.
Request
PUT /{bucket}/{key}?retention&versionId={versionId} HTTP/2
Path parameters
| Parameter | Description |
|---|---|
bucket |
Bucket name. |
key |
Object key. |
Query parameters
| Parameter | Description |
|---|---|
retention |
Required parameter that indicates the type of operation. |
versionId |
Object version ID. This is a required parameter. |
Headers
Use the appropriate common headers in your request.
Moreover, if governance-mode retention is set for an object version, make sure to use the below-specified header to bypass the retention and confirm its change.
| Header | Description |
|---|---|
X-Amz-Bypass-Governance-Retention |
Header that confirms bypassing of the governance retention. Set it to true. |
Data schema
<Retention xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Mode>string</Mode>
<RetainUntilDate>timestamp</RetainUntilDate>
</Retention>
| Element | Description |
|---|---|
Retention |
Root element with retention settings. To remove governance-mode retention (if you have the Path: |
Mode |
Type of retention:
Path: |
RetainUntilDate |
Lock end date and time in the RFC3339 format, e.g., Path: |
Response
Headers
Responses can only contain common response headers.
Response codes
For a list of possible responses, see Responses.