There are more AWS SDK examples available in the [AWS Doc SDK Examples](https://github.com/awsdocs/aws-doc-sdk-examples) GitHub repo.
# Use `GetObjectRetention` with an AWS SDK or CLI
The following code examples show how to use `GetObjectRetention`.
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:
+ [Lock Amazon S3 objects](s3_example_s3_Scenario_ObjectLock_section.md)
------
#### [ .NET ]
**SDK for .NET**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv3/S3/scenarios/S3ObjectLockScenario#code-examples).
```
///
/// Get the retention period for an S3 object.
///
/// The bucket of the object.
/// The object key.
/// The object retention details.
public async Task GetObjectRetention(string bucketName,
string objectKey)
{
try
{
var request = new GetObjectRetentionRequest()
{
BucketName = bucketName,
Key = objectKey
};
var response = await _amazonS3.GetObjectRetentionAsync(request);
Console.WriteLine($"\tObject retention for {objectKey} in {bucketName}: " +
$"\n\t{response.Retention.Mode} until {response.Retention.RetainUntilDate:d}.");
return response.Retention;
}
catch (AmazonS3Exception ex)
{
Console.WriteLine($"\tUnable to fetch object lock retention: '{ex.Message}'");
return new ObjectLockRetention();
}
}
```
+ For API details, see [GetObjectRetention](https://docs.aws.amazon.com/goto/DotNetSDKV3/s3-2006-03-01/GetObjectRetention) in *AWS SDK for .NET API Reference*.
------
#### [ CLI ]
**AWS CLI**
**To retrieve the object retention configuration for an object**
The following `get-object-retention` example retrieves the object retention configuration for the specified object.
```
aws s3api get-object-retention \
--bucket amzn-s3-demo-bucket-with-object-lock \
--key doc1.rtf
```
Output:
```
{
"Retention": {
"Mode": "GOVERNANCE",
"RetainUntilDate": "2025-01-01T00:00:00.000Z"
}
}
```
+ For API details, see [GetObjectRetention](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/get-object-retention.html) in *AWS CLI Command Reference*.
------
#### [ Go ]
**SDK for Go V2**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/gov2/workflows/s3_object_lock#code-examples).
```
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
}
// GetObjectRetention retrieves the object retention configuration for an S3 object.
func (actor S3Actions) GetObjectRetention(ctx context.Context, bucket string, key string) (*types.ObjectLockRetention, error) {
var retention *types.ObjectLockRetention
input := &s3.GetObjectRetentionInput{
Bucket: aws.String(bucket),
Key: aws.String(key),
}
output, err := actor.S3Client.GetObjectRetention(ctx, input)
if err != nil {
var noKey *types.NoSuchKey
var apiErr *smithy.GenericAPIError
if errors.As(err, &noKey) {
log.Printf("Object %s does not exist in bucket %s.\n", key, bucket)
err = noKey
} else if errors.As(err, &apiErr) {
switch apiErr.ErrorCode() {
case "NoSuchObjectLockConfiguration":
err = nil
case "InvalidRequest":
log.Printf("Bucket %s does not have locking enabled.", bucket)
err = nil
}
}
} else {
retention = output.Retention
}
return retention, err
}
```
+ For API details, see [GetObjectRetention](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3#Client.GetObjectRetention) in *AWS SDK for Go API Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3#code-examples).
```
// Get the retention period for an S3 object.
public ObjectLockRetention getObjectRetention(String bucketName, String key){
try {
GetObjectRetentionRequest retentionRequest = GetObjectRetentionRequest.builder()
.bucket(bucketName)
.key(key)
.build();
GetObjectRetentionResponse response = getClient().getObjectRetention(retentionRequest);
System.out.println("tObject retention for "+key +" in "+ bucketName +": " + response.retention().mode() +" until "+ response.retention().retainUntilDate() +".");
return response.retention();
} catch (S3Exception e) {
System.err.println(e.awsErrorDetails().errorMessage());
return null;
}
}
```
+ For API details, see [GetObjectRetention](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/GetObjectRetention) in *AWS SDK for Java 2.x API Reference*.
------
#### [ JavaScript ]
**SDK for JavaScript (v3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/s3#code-examples).
```
import {
GetObjectRetentionCommand,
S3Client,
S3ServiceException,
} from "@aws-sdk/client-s3";
/**
* Log the "RetainUntilDate" for an object in an S3 bucket.
* @param {{ bucketName: string, key: string }}
*/
export const main = async ({ bucketName, key }) => {
const client = new S3Client({});
try {
const { Retention } = await client.send(
new GetObjectRetentionCommand({
Bucket: bucketName,
Key: key,
}),
);
console.log(
`${key} in ${bucketName} will be retained until ${Retention.RetainUntilDate}`,
);
} catch (caught) {
if (
caught instanceof S3ServiceException &&
caught.name === "NoSuchObjectLockConfiguration"
) {
console.warn(
`The object "${key}" in the bucket "${bucketName}" does not have an ObjectLock configuration.`,
);
} else if (caught instanceof S3ServiceException) {
console.error(
`Error from S3 while getting object retention settings for "${bucketName}". ${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"));
}
}
```
+ For API details, see [GetObjectRetention](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/command/GetObjectRetentionCommand) in *AWS SDK for JavaScript API Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: The command returns the mode and date till the object would be retained.**
```
Get-S3ObjectRetention -BucketName 'amzn-s3-demo-bucket' -Key 'testfile.txt'
```
+ For API details, see [GetObjectRetention](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: The command returns the mode and date till the object would be retained.**
```
Get-S3ObjectRetention -BucketName 'amzn-s3-demo-bucket' -Key 'testfile.txt'
```
+ For API details, see [GetObjectRetention](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------