PutObjectLockConfiguration
Places an Object Lock configuration on the specified bucket.
Description
The PutObjectLockConfiguration operation puts an Object Lock configuration on the specified bucket. The rule specified in the Object Lock configuration will be applied by default to every new object placed in the specified bucket.
important
- The bucket must have Object Lock enabled to use this operation.
- Object Lock must be enabled on the bucket when the bucket is created using the
x-amz-bucket-object-lock-enabledrequest header. - The
DefaultRetentionsettings require both a mode and a period. - The
DefaultRetentionperiod can be eitherDaysorYearsbut you must select one. You cannot specify both. - This operation requires
s3:PutBucketObjectLockConfigurationpermissions.
Request Syntax
PUT /?object-lock HTTP/1.1
Host: BucketName.qstorage.quilibrium.com
Content-MD5: Base64EncodedMD5
x-amz-expected-bucket-owner: OwnerAccountId
x-amz-request-payer: RequestPayer
x-amz-sdk-checksum-algorithm: ChecksumAlgorithm
x-amz-bucket-object-lock-token: BucketObjectLockToken
<?xml version="1.0" encoding="UTF-8"?>
<ObjectLockConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<ObjectLockEnabled>Enabled</ObjectLockEnabled>
<Rule>
<DefaultRetention>
<Mode>GOVERNANCE</Mode>
<Days>Integer</Days>
<Years>Integer</Years>
</DefaultRetention>
</Rule>
</ObjectLockConfiguration>
Values in italics indicate user input and should be replaced with actual values.
Request Parameters
URI Parameters
| Name | Description | Required | Type |
|---|---|---|---|
| Bucket | The bucket whose Object Lock configuration you want to create or replace. | Yes | String |
Headers
| Name | Description | Required | Type |
|---|---|---|---|
| x-amz-expected-bucket-owner | The account ID of the expected bucket owner | No | String |
| Content-MD5 | The base64-encoded 128-bit MD5 digest of the request body | Yes | String |
| x-amz-request-payer | Confirms that the requester knows that they will be charged for the request Valid values: requester | No | String |
| x-amz-sdk-checksum-algorithm | Indicates the algorithm used to create the checksum for the object Valid values: CRC32 | CRC32C | SHA1 | SHA256 | CRC64NVME | No | String |
| x-amz-bucket-object-lock-token | A token to allow Object Lock to be enabled for an existing bucket | No | String |
Request Elements
| Name | Description | Required | Type |
|---|---|---|---|
| ObjectLockConfiguration | Container for Object Lock configuration parameters. | Yes | Container |
| ObjectLockEnabled | Indicates whether this bucket has an Object Lock configuration enabled. Valid values: Enabled | No | String |
| Rule | Container for the Object Lock rule for the specified object. | No | ObjectLockRule |
Examples
Example 1: Set Object Lock configuration with retention period in days
PUT /?object-lock HTTP/1.1
Host: my-bucket.qstorage.quilibrium.com
Content-MD5: 1B2M2Y8AsgTpgAmY7PhCfg==
x-amz-expected-bucket-owner: 123456789012
x-amz-request-payer: requester
x-amz-sdk-checksum-algorithm: CRC32
x-amz-bucket-object-lock-token: token
<?xml version="1.0" encoding="UTF-8"?>
<ObjectLockConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<ObjectLockEnabled>Enabled</ObjectLockEnabled>
<Rule>
<DefaultRetention>
<Mode>COMPLIANCE</Mode>
<Days>30</Days>
</DefaultRetention>
</Rule>
</ObjectLockConfiguration>
Values in italics indicate user input and should be replaced with actual values.
HTTP/1.1 200 OK
x-amz-id-2: Example7qoYGN7uMuFuYS6m7a4l
x-amz-request-id: TX234S0F24A06C7
x-amz-request-charged: requester
Date: Wed, 01 Mar 2024 12:00:00 GMT
Values in italics indicate variable response values.
Example 2: Set Object Lock configuration with retention period in years
PUT /?object-lock HTTP/1.1
Host: my-bucket.qstorage.quilibrium.com
Content-MD5: 1B2M2Y8AsgTpgAmY7PhCfg==
x-amz-expected-bucket-owner: 123456789012
x-amz-request-payer: requester
x-amz-sdk-checksum-algorithm: SHA256
x-amz-bucket-object-lock-token: token
<?xml version="1.0" encoding="UTF-8"?>
<ObjectLockConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<ObjectLockEnabled>Enabled</ObjectLockEnabled>
<Rule>
<DefaultRetention>
<Mode>GOVERNANCE</Mode>
<Years>1</Years>
</DefaultRetention>
</Rule>
</ObjectLockConfiguration>
Values in italics indicate user input and should be replaced with actual values.
HTTP/1.1 200 OK
x-amz-id-2: Example7qoYGN7uMuFuYS6m7a4l
x-amz-request-id: TX234S0F24A06C7
x-amz-request-charged: requester
Date: Wed, 01 Mar 2024 12:00:00 GMT
Values in italics indicate variable response values.
Response Syntax
HTTP/1.1 200 OK
x-amz-id-2: RequestId
x-amz-request-id: AmazonRequestId
x-amz-request-charged: RequestCharged
Date: ISO8601Date
Values in italics indicate variable response values.
Response Elements
Response Headers
| Name | Description | Required | Type |
|---|---|---|---|
| x-amz-request-charged | If present, indicates that the requester was successfully charged for the request Valid values: requester | No | String |
This operation does not return a response body.
Special Errors
| Error Code | Description |
|---|---|
| InvalidRequest | The request is missing required headers or the Object Lock configuration is not valid. |
| ObjectLockConfigurationNotFoundError | This error occurs when you attempt to get an Object Lock configuration for a bucket that does not have a configuration. |
| NoSuchBucket | The specified bucket does not exist. |
| 403 | Forbidden. Authentication failed or you do not have permission to configure Object Lock. |
Permissions
You must have the s3:PutBucketObjectLockConfiguration permission.
Try It Out
Test PutObjectLockConfiguration
Set the Object Lock configuration for a bucket.
Coming Soon
This feature is currently under development and will be available soon.