There are more AWS SDK examples available in the [AWS Doc SDK Examples](https://github.com/awsdocs/aws-doc-sdk-examples) GitHub repo.
# Use `PutObjectLegalHold` with an AWS SDK or CLI
The following code examples show how to use `PutObjectLegalHold`.
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).
```
///
/// Set or modify a legal hold on an object in an S3 bucket.
///
/// The bucket of the object.
/// The key of the object.
/// The On or Off status for the legal hold.
/// True if successful.
public async Task ModifyObjectLegalHold(string bucketName,
string objectKey, ObjectLockLegalHoldStatus holdStatus)
{
try
{
var request = new PutObjectLegalHoldRequest()
{
BucketName = bucketName,
Key = objectKey,
LegalHold = new ObjectLockLegalHold()
{
Status = holdStatus
}
};
var response = await _amazonS3.PutObjectLegalHoldAsync(request);
Console.WriteLine($"\tModified legal hold for {objectKey} in {bucketName}.");
return response.HttpStatusCode == System.Net.HttpStatusCode.OK;
}
catch (AmazonS3Exception ex)
{
Console.WriteLine($"\tError modifying legal hold: '{ex.Message}'");
return false;
}
}
```
+ For API details, see [PutObjectLegalHold](https://docs.aws.amazon.com/goto/DotNetSDKV3/s3-2006-03-01/PutObjectLegalHold) in *AWS SDK for .NET API Reference*.
------
#### [ CLI ]
**AWS CLI**
**To apply a Legal Hold to an object**
The following `put-object-legal-hold` example sets a Legal Hold on the object `doc1.rtf`.
```
aws s3api put-object-legal-hold \
--bucket amzn-s3-demo-bucket-with-object-lock \
--key doc1.rtf \
--legal-hold Status=ON
```
This command produces no output.
+ For API details, see [PutObjectLegalHold](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/put-object-legal-hold.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
}
// PutObjectLegalHold sets the legal hold configuration for an S3 object.
func (actor S3Actions) PutObjectLegalHold(ctx context.Context, bucket string, key string, versionId string, legalHoldStatus types.ObjectLockLegalHoldStatus) error {
input := &s3.PutObjectLegalHoldInput{
Bucket: aws.String(bucket),
Key: aws.String(key),
LegalHold: &types.ObjectLockLegalHold{
Status: legalHoldStatus,
},
}
if versionId != "" {
input.VersionId = aws.String(versionId)
}
_, err := actor.S3Client.PutObjectLegalHold(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
}
```
+ For API details, see [PutObjectLegalHold](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3#Client.PutObjectLegalHold) 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).
```
// Set or modify a legal hold on an object in an S3 bucket.
public void modifyObjectLegalHold(String bucketName, String objectKey, boolean legalHoldOn) {
ObjectLockLegalHold legalHold ;
if (legalHoldOn) {
legalHold = ObjectLockLegalHold.builder()
.status(ObjectLockLegalHoldStatus.ON)
.build();
} else {
legalHold = ObjectLockLegalHold.builder()
.status(ObjectLockLegalHoldStatus.OFF)
.build();
}
PutObjectLegalHoldRequest legalHoldRequest = PutObjectLegalHoldRequest.builder()
.bucket(bucketName)
.key(objectKey)
.legalHold(legalHold)
.build();
getClient().putObjectLegalHold(legalHoldRequest) ;
System.out.println("Modified legal hold for "+ objectKey +" in "+bucketName +".");
}
```
+ For API details, see [PutObjectLegalHold](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/PutObjectLegalHold) 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 {
PutObjectLegalHoldCommand,
S3Client,
S3ServiceException,
} from "@aws-sdk/client-s3";
/**
* Apply a legal hold configuration to the specified object.
* @param {{ bucketName: string, objectKey: string, legalHoldStatus: "ON" | "OFF" }}
*/
export const main = async ({ bucketName, objectKey, legalHoldStatus }) => {
if (!["OFF", "ON"].includes(legalHoldStatus.toUpperCase())) {
throw new Error(
"Invalid parameter. legalHoldStatus must be 'ON' or 'OFF'.",
);
}
const client = new S3Client({});
const command = new PutObjectLegalHoldCommand({
Bucket: bucketName,
Key: objectKey,
LegalHold: {
// Set the status to 'ON' to place a legal hold on the object.
// Set the status to 'OFF' to remove the legal hold.
Status: legalHoldStatus,
},
});
try {
await client.send(command);
console.log(
`Legal hold status set to "${legalHoldStatus}" for "${objectKey}" in "${bucketName}"`,
);
} catch (caught) {
if (
caught instanceof S3ServiceException &&
caught.name === "NoSuchBucket"
) {
console.error(
`Error from S3 while modifying legal hold status for "${objectKey}" in "${bucketName}". The bucket doesn't exist.`,
);
} else if (caught instanceof S3ServiceException) {
console.error(
`Error from S3 while modifying legal hold status for "${objectKey}" in "${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,
},
objectKey: {
type: "string",
required: true,
},
legalHoldStatus: {
type: "string",
default: "ON",
},
};
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 [PutObjectLegalHold](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/command/PutObjectLegalHoldCommand) in *AWS SDK for JavaScript API Reference*.
------
#### [ Python ]
**SDK for Python (Boto3)**
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/python/example_code/s3/scenarios/object-locking#code-examples).
Put an object legal hold.
```
def set_legal_hold(s3_client, bucket: str, key: str) -> None:
"""
Set a legal hold on a specific file in a bucket.
Args:
s3_client: Boto3 S3 client.
bucket: The name of the bucket containing the file.
key: The key of the file to set the legal hold on.
"""
print()
logger.info("Setting legal hold on file [%s] in bucket [%s]", key, bucket)
try:
before_status = "OFF"
after_status = "ON"
s3_client.put_object_legal_hold(
Bucket=bucket, Key=key, LegalHold={"Status": after_status}
)
logger.debug(
"Legal hold set successfully on file [%s] in bucket [%s]", key, bucket
)
_print_legal_hold_update(bucket, key, before_status, after_status)
except Exception as e:
logger.error(
"Failed to set legal hold on file [%s] in bucket [%s]: %s", key, bucket, e
)
```
+ For API details, see [PutObjectLegalHold](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutObjectLegalHold) in *AWS SDK for Python (Boto3) API Reference*.
------
#### [ SAP ABAP ]
**SDK for SAP ABAP**
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/sap-abap/services/s3#code-examples).
```
TRY.
" Example: Set legal hold status to ON
" iv_status = 'ON'
lo_s3->putobjectlegalhold(
iv_bucket = iv_bucket_name
iv_key = iv_object_key
io_legalhold = NEW /aws1/cl_s3_objlocklegalhold(
iv_status = iv_status ) ).
MESSAGE 'Object legal hold status set.' TYPE 'I'.
CATCH /aws1/cx_s3_nosuchbucket.
MESSAGE 'Bucket does not exist.' TYPE 'E'.
CATCH /aws1/cx_s3_nosuchkey.
MESSAGE 'Object key does not exist.' TYPE 'E'.
ENDTRY.
```
+ For API details, see [PutObjectLegalHold](https://docs.aws.amazon.com/sdk-for-sap-abap/v1/api/latest/index.html) in *AWS SDK for SAP ABAP API reference*.
------