object_retentions

Creates, updates, deletes, gets or lists an object_retentions resource.

Overview

Name	object_retentions
Type	Resource
Id	aws.s3.object_retentions

Fields

The following fields are returned by SELECT queries:

get_object_retention

Name	Datatype	Description
mode	string	Indicates the Retention mode for the specified object.
retain_until_date	string	The date on which this Object Lock Retention will expire.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_object_retention	select	bucket, key, region	versionId, x-amz-request-payer, x-amz-expected-bucket-owner	This operation is not supported for directory buckets. Retrieves an object's retention settings. For more information, see Locking Objects. This functionality is not supported for Amazon S3 on Outposts. The following action is related to GetObjectRetention: GetObjectAttributes You must URL encode any signed header values that contain spaces. For example, if your header value is my file.txt, containing two spaces after my, you must URL encode this value to my%20%20file.txt.
put_object_retention	replace	bucket, key, region	x-amz-request-payer, versionId, x-amz-bypass-governance-retention, Content-MD5, x-amz-sdk-checksum-algorithm, x-amz-expected-bucket-owner	This operation is not supported for directory buckets. Places an Object Retention configuration on an object. For more information, see Locking Objects. Users or accounts require the s3:PutObjectRetention permission in order to place an Object Retention configuration on objects. Bypassing a Governance Retention configuration requires the s3:BypassGovernanceRetention permission. This functionality is not supported for Amazon S3 on Outposts. You must URL encode any signed header values that contain spaces. For example, if your header value is my file.txt, containing two spaces after my, you must URL encode this value to my%20%20file.txt.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
bucket	string	The bucket name that contains the object you want to apply this Object Retention configuration to. Access points - When you use this action with an access point for general purpose buckets, you must provide the alias of the access point in place of the bucket name or specify the access point ARN. When you use this action with an access point for directory buckets, you must provide the access point name in place of the bucket name. When using the access point ARN, you must direct requests to the access point hostname. The access point hostname takes the form AccessPointName-AccountId.s3-accesspoint.Region.amazonaws.com. When using this action with an access point through the Amazon Web Services SDKs, you provide the access point ARN in place of the bucket name. For more information about access point ARNs, see Using access points in the Amazon S3 User Guide.
key	string	The key name for the object that you want to apply this Object Retention configuration to.
region	string	AWS region (default: us-east-1)
Content-MD5	string	The MD5 hash for the request body. For requests made using the Amazon Web Services Command Line Interface (CLI) or Amazon Web Services SDKs, this field is calculated automatically.
versionId	string	The version ID for the object that you want to apply this Object Retention configuration to.
x-amz-bypass-governance-retention	boolean	Indicates whether this action should bypass Governance-mode restrictions.
x-amz-expected-bucket-owner	string	The account ID of the expected bucket owner. If the account ID that you provide does not match the actual owner of the bucket, the request fails with the HTTP status code 403 Forbidden (access denied).
x-amz-request-payer	string
x-amz-sdk-checksum-algorithm	string	Indicates the algorithm used to create the checksum for the object when you use the SDK. This header will not provide any additional functionality if you don't use the SDK. When you send this header, there must be a corresponding x-amz-checksum or x-amz-trailer header sent. Otherwise, Amazon S3 fails the request with the HTTP status code 400 Bad Request. For more information, see Checking object integrity in the Amazon S3 User Guide. If you provide an individual checksum, Amazon S3 ignores any provided ChecksumAlgorithm parameter.

SELECT examples

get_object_retention

This operation is not supported for directory buckets. Retrieves an object's retention settings. For more information, see Locking Objects. This functionality is not supported for Amazon S3 on Outposts. The following action is related to GetObjectRetention: GetObjectAttributes You must URL encode any signed header values that contain spaces. For example, if your header value is my file.txt, containing two spaces after my, you must URL encode this value to my%20%20file.txt.

SELECT
mode,
retain_until_date
FROM aws.s3.object_retentions
WHERE bucket = '{{ bucket }}' -- required
AND key = '{{ key }}' -- required
AND region = '{{ region }}' -- required
AND versionId = '{{ versionId }}'
AND `x-amz-request-payer` = '{{ x-amz-request-payer }}'
AND `x-amz-expected-bucket-owner` = '{{ x-amz-expected-bucket-owner }}'
;

REPLACE examples

put_object_retention

This operation is not supported for directory buckets. Places an Object Retention configuration on an object. For more information, see Locking Objects. Users or accounts require the s3:PutObjectRetention permission in order to place an Object Retention configuration on objects. Bypassing a Governance Retention configuration requires the s3:BypassGovernanceRetention permission. This functionality is not supported for Amazon S3 on Outposts. You must URL encode any signed header values that contain spaces. For example, if your header value is my file.txt, containing two spaces after my, you must URL encode this value to my%20%20file.txt.

REPLACE aws.s3.object_retentions
SET 
Retention = '{{ Retention }}'
WHERE 
bucket = '{{ bucket }}' --required
AND key = '{{ key }}' --required
AND region = '{{ region }}' --required
AND `x-amz-request-payer` = '{{ x-amz-request-payer}}'
AND versionId = '{{ versionId}}'
AND `x-amz-bypass-governance-retention` = {{ x-amz-bypass-governance-retention}}
AND `Content-MD5` = '{{ Content-MD5}}'
AND `x-amz-sdk-checksum-algorithm` = '{{ x-amz-sdk-checksum-algorithm}}'
AND `x-amz-expected-bucket-owner` = '{{ x-amz-expected-bucket-owner}}'
RETURNING
line_items;