PutObjectRetention with an AWS SDK or CLI
The following code examples show how to use PutObjectRetention.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:
/// <summary>
/// Set or modify a retention period on an object in an S3 bucket.
/// </summary>
/// <param name="bucketName">The bucket of the object.</param>
/// <param name="objectKey">The key of the object.</param>
/// <param name="retention">The retention mode.</param>
/// <param name="retainUntilDate">The date retention expires.</param>
/// <returns>True if successful.</returns>
public async Task<bool> ModifyObjectRetentionPeriod(string bucketName,
string objectKey, ObjectLockRetentionMode retention, DateTime retainUntilDate)
{
try
{
var request = new PutObjectRetentionRequest()
{
BucketName = bucketName,
Key = objectKey,
Retention = new ObjectLockRetention()
{
Mode = retention,
RetainUntilDate = retainUntilDate
}
};
var response = await _amazonS3.PutObjectRetentionAsync(request);
Console.WriteLine($"\tSet retention for {objectKey} in {bucketName} until {retainUntilDate:d}.");
return response.HttpStatusCode == System.Net.HttpStatusCode.OK;
}
catch (AmazonS3Exception ex)
{
Console.WriteLine($"\tError modifying retention period: '{ex.Message}'");
return false;
}
}
To set an object retention configuration for an object
The following put-object-retention example sets an object retention configuration for the specified object until 2025-01-01.
aws s3api put-object-retention \
--bucket amzn-s3-demo-bucket-with-object-lock \
--key doc1.rtf \
--retention '{ "Mode": "GOVERNANCE", "RetainUntilDate": "2025-01-01T00:00:00" }'
This command produces no output.
import (
"bytes"
"context"
"errors"
"fmt"
"log"
"time"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/feature/s3/manager"
"github.com/aws/aws-sdk-go-v2/service/s3"
"github.com/aws/aws-sdk-go-v2/service/s3/types"
"github.com/aws/smithy-go"
)
// S3Actions wraps S3 service actions.
type S3Actions struct {
S3Client *s3.Client
S3Manager *manager.Uploader
}
// PutObjectRetention sets the object retention configuration for an S3 object.
func (actor S3Actions) PutObjectRetention(ctx context.Context, bucket string, key string, retentionMode types.ObjectLockRetentionMode, retentionPeriodDays int32) error {
input := &s3.PutObjectRetentionInput{
Bucket: aws.String(bucket),
Key: aws.String(key),
Retention: &types.ObjectLockRetention{
Mode: retentionMode,
RetainUntilDate: aws.Time(time.Now().AddDate(0, 0, int(retentionPeriodDays))),
},
BypassGovernanceRetention: aws.Bool(true),
}
_, err := actor.S3Client.PutObjectRetention(ctx, input)
if err != nil {
var noKey *types.NoSuchKey
if errors.As(err, &noKey) {
log.Printf("Object %s does not exist in bucket %s.\n", key, bucket)
err = noKey
}
}
return err
}
// Set or modify a retention period on an object in an S3 bucket.
public void modifyObjectRetentionPeriod(String bucketName, String objectKey) {
// Calculate the instant one day from now.
Instant futureInstant = Instant.now().plus(1, ChronoUnit.DAYS);
// Convert the Instant to a ZonedDateTime object with a specific time zone.
ZonedDateTime zonedDateTime = futureInstant.atZone(ZoneId.systemDefault());
// Define a formatter for human-readable output.
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
// Format the ZonedDateTime object to a human-readable date string.
String humanReadableDate = formatter.format(zonedDateTime);
// Print the formatted date string.
System.out.println("Formatted Date: " + humanReadableDate);
ObjectLockRetention retention = ObjectLockRetention.builder()
.mode(ObjectLockRetentionMode.GOVERNANCE)
.retainUntilDate(futureInstant)
.build();
PutObjectRetentionRequest retentionRequest = PutObjectRetentionRequest.builder()
.bucket(bucketName)
.key(objectKey)
.retention(retention)
.build();
getClient().putObjectRetention(retentionRequest);
System.out.println("Set retention for "+objectKey +" in " +bucketName +" until "+ humanReadableDate +".");
}
import {
PutObjectRetentionCommand,
S3Client,
S3ServiceException,
} from "@aws-sdk/client-s3";
/**
* Place a 24-hour retention period on an object in an Amazon S3 bucket.
* @param {{ bucketName: string, key: string }}
*/
export const main = async ({ bucketName, key }) => {
const client = new S3Client({});
const command = new PutObjectRetentionCommand({
Bucket: bucketName,
Key: key,
BypassGovernanceRetention: false,
Retention: {
// In governance mode, users can't overwrite or delete an object version
// or alter its lock settings unless they have special permissions. With
// governance mode, you protect objects against being deleted by most users,
// but you can still grant some users permission to alter the retention settings
// or delete the objects if necessary.
Mode: "GOVERNANCE",
RetainUntilDate: new Date(new Date().getTime() + 24 * 60 * 60 * 1000),
},
});
try {
await client.send(command);
console.log("Object Retention settings updated.");
} catch (caught) {
if (
caught instanceof S3ServiceException &&
caught.name === "NoSuchBucket"
) {
console.error(
`Error from S3 while modifying the governance mode and retention period on an object. The bucket doesn't exist.`,
);
} else if (caught instanceof S3ServiceException) {
console.error(
`Error from S3 while modifying the governance mode and retention period on an object. ${caught.name}: ${caught.message}`,
);
} else {
throw caught;
}
}
};
// Call function if run directly
import { parseArgs } from "node:util";
import {
isMain,
validateArgs,
} from "@aws-doc-sdk-examples/lib/utils/util-node.js";
const loadArgs = () => {
const options = {
bucketName: {
type: "string",
required: true,
},
key: {
type: "string",
required: true,
},
};
const results = parseArgs({ options });
const { errors } = validateArgs({ options }, results);
return { errors, results };
};
if (isMain(import.meta.url)) {
const { errors, results } = loadArgs();
if (!errors) {
main(results.values);
} else {
console.error(errors.join("\n"));
}
}
Example 1: The command enables governance retention mode untill the date '31st Dec 2019 00:00:00' for 'testfile.txt' object in the given S3 bucket.
Write-S3ObjectRetention -BucketName 'amzn-s3-demo-bucket' -Key 'testfile.txt' -Retention_Mode GOVERNANCE -Retention_RetainUntilDate "2019-12-31T00:00:00"
For API details, see PutObjectRetention in AWS Tools for PowerShell Cmdlet Reference (V4).
Example 1: The command enables governance retention mode untill the date '31st Dec 2019 00:00:00' for 'testfile.txt' object in the given S3 bucket.
Write-S3ObjectRetention -BucketName 'amzn-s3-demo-bucket' -Key 'testfile.txt' -Retention_Mode GOVERNANCE -Retention_RetainUntilDate "2019-12-31T00:00:00"
For API details, see PutObjectRetention in AWS Tools for PowerShell Cmdlet Reference (V5).
Put an object retention.
s3_client.put_object_retention(
Bucket=bucket,
Key=key,
VersionId=version_id,
Retention={"Mode": "GOVERNANCE", "RetainUntilDate": far_future_date},
BypassGovernanceRetention=True,
)
For a complete list of AWS SDK developer guides and code examples, see Developing with Amazon S3 using the AWS SDKs. This topic also includes information about getting started and details about previous SDK versions.
PutObjectLockConfiguration
RestoreObject
Did this page help you? - Yes
Thanks for letting us know we're doing a good job!
If you've got a moment, please tell us what we did right so we can do more of it.
Did this page help you? - No
Thanks for letting us know this page needs work. We're sorry we let you down.
If you've got a moment, please tell us how we can make the documentation better.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4