There are more AWS SDK examples available in the [AWS Doc SDK Examples](https://github.com/awsdocs/aws-doc-sdk-examples) GitHub repo. # Actions for Amazon S3 Control using AWS SDKs The following code examples demonstrate how to perform individual Amazon S3 Control actions with AWS SDKs. Each example includes a link to GitHub, where you can find instructions for setting up and running the code. The following examples include only the most commonly used actions. For a complete list, see the [Amazon S3 Control API Reference](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html). **Topics** + [`CreateJob`](s3-control_example_s3-control_CreateJob_section.md) + [`DeleteJobTagging`](s3-control_example_s3-control_DeleteJobTagging_section.md) + [`DescribeJob`](s3-control_example_s3-control_DescribeJob_section.md) + [`GetJobTagging`](s3-control_example_s3-control_GetJobTagging_section.md) + [`PutJobTagging`](s3-control_example_s3-control_PutJobTagging_section.md) + [`UpdateJobPriority`](s3-control_example_s3-control_UpdateJobPriority_section.md) + [`UpdateJobStatus`](s3-control_example_s3-control_UpdateJobStatus_section.md) # Use `CreateJob` with an AWS SDK or CLI The following code examples show how to use `CreateJob`. 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: + [Learn the basics](s3-control_example_s3-control_Basics_section.md) ------ #### [ CLI ] **AWS CLI** **To create an Amazon S3 batch operations job** The following `create-job` example creates an Amazon S3 batch operations job to tag objects as `confidential` in the bucket ``employee-records`. ``` aws s3control create-job \ --account-id 123456789012 \ --operation '{"S3PutObjectTagging": { "TagSet": [{"Key":"confidential", "Value":"true"}] }}' \ --report '{"Bucket":"arn:aws:s3:::employee-records-logs","Prefix":"batch-op-create-job", "Format":"Report_CSV_20180820","Enabled":true,"ReportScope":"AllTasks"}' \ --manifest '{"Spec":{"Format":"S3BatchOperations_CSV_20180820","Fields":["Bucket","Key"]},"Location":{"ObjectArn":"arn:aws:s3:::employee-records-logs/inv-report/7a6a9be4-072c-407e-85a2-ec3e982f773e.csv","ETag":"69f52a4e9f797e987155d9c8f5880897"}}' \ --priority 42 \ --role-arn arn:aws:iam::123456789012:role/S3BatchJobRole ``` Output: ``` { "JobId": "93735294-df46-44d5-8638-6356f335324e" } ``` + For API details, see [CreateJob](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3control/create-job.html) in *AWS CLI Command 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/src/main/java/com/example/s3/batch#code-examples). Create an asynchronous S3 job. ``` /** * Creates an asynchronous S3 job using the AWS Java SDK. * * @param accountId the AWS account ID associated with the job * @param iamRoleArn the ARN of the IAM role to be used for the job * @param manifestLocation the location of the job manifest file in S3 * @param reportBucketName the name of the S3 bucket to store the job report * @param uuid a unique identifier for the job * @return a CompletableFuture that represents the asynchronous creation of the S3 job. * The CompletableFuture will return the job ID if the job is created successfully, * or throw an exception if there is an error. */ public CompletableFuture createS3JobAsync(String accountId, String iamRoleArn, String manifestLocation, String reportBucketName, String uuid) { String[] bucketName = new String[]{""}; String[] parts = reportBucketName.split(":::"); if (parts.length > 1) { bucketName[0] = parts[1]; } else { System.out.println("The input string does not contain the expected format."); } return CompletableFuture.supplyAsync(() -> getETag(bucketName[0], "job-manifest.csv")) .thenCompose(eTag -> { ArrayList tagSet = new ArrayList<>(); S3Tag s3Tag = S3Tag.builder() .key("keyOne") .value("ValueOne") .build(); S3Tag s3Tag2 = S3Tag.builder() .key("keyTwo") .value("ValueTwo") .build(); tagSet.add(s3Tag); tagSet.add(s3Tag2); S3SetObjectTaggingOperation objectTaggingOperation = S3SetObjectTaggingOperation.builder() .tagSet(tagSet) .build(); JobOperation jobOperation = JobOperation.builder() .s3PutObjectTagging(objectTaggingOperation) .build(); JobManifestLocation jobManifestLocation = JobManifestLocation.builder() .objectArn(manifestLocation) .eTag(eTag) .build(); JobManifestSpec manifestSpec = JobManifestSpec.builder() .fieldsWithStrings("Bucket", "Key") .format("S3BatchOperations_CSV_20180820") .build(); JobManifest jobManifest = JobManifest.builder() .spec(manifestSpec) .location(jobManifestLocation) .build(); JobReport jobReport = JobReport.builder() .bucket(reportBucketName) .prefix("reports") .format("Report_CSV_20180820") .enabled(true) .reportScope("AllTasks") .build(); CreateJobRequest jobRequest = CreateJobRequest.builder() .accountId(accountId) .description("Job created using the AWS Java SDK") .manifest(jobManifest) .operation(jobOperation) .report(jobReport) .priority(42) .roleArn(iamRoleArn) .clientRequestToken(uuid) .confirmationRequired(false) .build(); // Create the job asynchronously. return getAsyncClient().createJob(jobRequest) .thenApply(CreateJobResponse::jobId); }) .handle((jobId, ex) -> { if (ex != null) { Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex; if (cause instanceof S3ControlException) { throw new CompletionException(cause); } else { throw new RuntimeException(cause); } } return jobId; }); } ``` Create a compliance retention job. ``` /** * Creates a compliance retention job in Amazon S3 Control. *

* A compliance retention job in Amazon S3 Control is a feature that allows you to * set a retention period for objects stored in an S3 bucket. * This feature is particularly useful for organizations that need to comply with * regulatory requirements or internal policies that mandate the retention of data for * a specific duration. * * @param s3ControlClient The S3ControlClient instance to use for the API call. * @return The job ID of the created compliance retention job. */ public static String createComplianceRetentionJob(final S3ControlClient s3ControlClient, String roleArn, String bucketName, String accountId) { final String manifestObjectArn = "arn:aws:s3:::amzn-s3-demo-manifest-bucket/compliance-objects-manifest.csv"; final String manifestObjectVersionId = "your-object-version-Id"; Instant jan2025 = Instant.parse("2025-01-01T00:00:00Z"); JobOperation jobOperation = JobOperation.builder() .s3PutObjectRetention(S3SetObjectRetentionOperation.builder() .retention(S3Retention.builder() .mode(S3ObjectLockRetentionMode.COMPLIANCE) .retainUntilDate(jan2025) .build()) .build()) .build(); JobManifestLocation manifestLocation = JobManifestLocation.builder() .objectArn(manifestObjectArn) .eTag(manifestObjectVersionId) .build(); JobManifestSpec manifestSpec = JobManifestSpec.builder() .fieldsWithStrings("Bucket", "Key") .format("S3BatchOperations_CSV_20180820") .build(); JobManifest manifestToPublicApi = JobManifest.builder() .location(manifestLocation) .spec(manifestSpec) .build(); // Report details. final String jobReportBucketArn = "arn:aws:s3:::" + bucketName; final String jobReportPrefix = "reports/compliance-objects-bops"; JobReport jobReport = JobReport.builder() .enabled(true) .reportScope(JobReportScope.ALL_TASKS) .bucket(jobReportBucketArn) .prefix(jobReportPrefix) .format(JobReportFormat.REPORT_CSV_20180820) .build(); final Boolean requiresConfirmation = true; final int priority = 10; CreateJobRequest request = CreateJobRequest.builder() .accountId(accountId) .description("Set compliance retain-until to 1 Jan 2025") .manifest(manifestToPublicApi) .operation(jobOperation) .priority(priority) .roleArn(roleArn) .report(jobReport) .confirmationRequired(requiresConfirmation) .build(); // Create the job and get the result. CreateJobResponse result = s3ControlClient.createJob(request); return result.jobId(); } ``` Create a legal hold off job. ``` /** * Creates a compliance retention job in Amazon S3 Control. *

* A compliance retention job in Amazon S3 Control is a feature that allows you to * set a retention period for objects stored in an S3 bucket. * This feature is particularly useful for organizations that need to comply with * regulatory requirements or internal policies that mandate the retention of data for * a specific duration. * * @param s3ControlClient The S3ControlClient instance to use for the API call. * @return The job ID of the created compliance retention job. */ public static String createComplianceRetentionJob(final S3ControlClient s3ControlClient, String roleArn, String bucketName, String accountId) { final String manifestObjectArn = "arn:aws:s3:::amzn-s3-demo-manifest-bucket/compliance-objects-manifest.csv"; final String manifestObjectVersionId = "your-object-version-Id"; Instant jan2025 = Instant.parse("2025-01-01T00:00:00Z"); JobOperation jobOperation = JobOperation.builder() .s3PutObjectRetention(S3SetObjectRetentionOperation.builder() .retention(S3Retention.builder() .mode(S3ObjectLockRetentionMode.COMPLIANCE) .retainUntilDate(jan2025) .build()) .build()) .build(); JobManifestLocation manifestLocation = JobManifestLocation.builder() .objectArn(manifestObjectArn) .eTag(manifestObjectVersionId) .build(); JobManifestSpec manifestSpec = JobManifestSpec.builder() .fieldsWithStrings("Bucket", "Key") .format("S3BatchOperations_CSV_20180820") .build(); JobManifest manifestToPublicApi = JobManifest.builder() .location(manifestLocation) .spec(manifestSpec) .build(); // Report details. final String jobReportBucketArn = "arn:aws:s3:::" + bucketName; final String jobReportPrefix = "reports/compliance-objects-bops"; JobReport jobReport = JobReport.builder() .enabled(true) .reportScope(JobReportScope.ALL_TASKS) .bucket(jobReportBucketArn) .prefix(jobReportPrefix) .format(JobReportFormat.REPORT_CSV_20180820) .build(); final Boolean requiresConfirmation = true; final int priority = 10; CreateJobRequest request = CreateJobRequest.builder() .accountId(accountId) .description("Set compliance retain-until to 1 Jan 2025") .manifest(manifestToPublicApi) .operation(jobOperation) .priority(priority) .roleArn(roleArn) .report(jobReport) .confirmationRequired(requiresConfirmation) .build(); // Create the job and get the result. CreateJobResponse result = s3ControlClient.createJob(request); return result.jobId(); } ``` Create a new governance retention job. ``` /** * Before running this Java V2 code example, set up your development * environment, including your credentials. * * For more information, see the following documentation topic: * * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html */ public class CreateGovernanceRetentionJob { public static void main(String[]args) throws ParseException { final String usage = """ Usage: Where: manifestObjectArn - The Amazon Resource Name (ARN) of the S3 object that contains the manifest file for the governance objects.\s bucketName - The ARN of the S3 bucket where the job report will be stored. roleArn - The ARN of the IAM role that will be used to perform the governance retention operation. accountId - Your AWS account Id. manifestObjectVersionId = A unique value that is used as the `eTag` property of the `JobManifestLocation` object. """; if (args.length != 4) { System.out.println(usage); return; } String manifestObjectArn = args[0]; String jobReportBucketArn = args[1]; String roleArn = args[2]; String accountId = args[3]; String manifestObjectVersionId = args[4]; S3ControlClient s3ControlClient = S3ControlClient.create(); createGovernanceRetentionJob(s3ControlClient, manifestObjectArn, jobReportBucketArn, roleArn, accountId, manifestObjectVersionId); } public static String createGovernanceRetentionJob(final S3ControlClient s3ControlClient, String manifestObjectArn, String jobReportBucketArn, String roleArn, String accountId, String manifestObjectVersionId) throws ParseException { final JobManifestLocation manifestLocation = JobManifestLocation.builder() .objectArn(manifestObjectArn) .eTag(manifestObjectVersionId) .build(); final JobManifestSpec manifestSpec = JobManifestSpec.builder() .format(JobManifestFormat.S3_BATCH_OPERATIONS_CSV_20180820) .fields(Arrays.asList(JobManifestFieldName.BUCKET, JobManifestFieldName.KEY)) .build(); final JobManifest manifestToPublicApi = JobManifest.builder() .location(manifestLocation) .spec(manifestSpec) .build(); final String jobReportPrefix = "reports/governance-objects"; final JobReport jobReport = JobReport.builder() .enabled(true) .reportScope(JobReportScope.ALL_TASKS) .bucket(jobReportBucketArn) .prefix(jobReportPrefix) .format(JobReportFormat.REPORT_CSV_20180820) .build(); final SimpleDateFormat format = new SimpleDateFormat("dd/MM/yyyy"); final Date jan30th = format.parse("30/01/2025"); final S3SetObjectRetentionOperation s3SetObjectRetentionOperation = S3SetObjectRetentionOperation.builder() .retention(S3Retention.builder() .mode(S3ObjectLockRetentionMode.GOVERNANCE) .retainUntilDate(jan30th.toInstant()) .build()) .build(); final JobOperation jobOperation = JobOperation.builder() .s3PutObjectRetention(s3SetObjectRetentionOperation) .build(); final Boolean requiresConfirmation = true; final int priority = 10; final CreateJobRequest request = CreateJobRequest.builder() .accountId(accountId) .description("Put governance retention") .manifest(manifestToPublicApi) .operation(jobOperation) .priority(priority) .roleArn(roleArn) .report(jobReport) .confirmationRequired(requiresConfirmation) .build(); final CreateJobResponse result = s3ControlClient.createJob(request); return result.jobId(); } } ``` + For API details, see [CreateJob](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3control-2018-08-20/CreateJob) in *AWS SDK for Java 2.x 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/batch#code-examples). ``` def create_s3_batch_job(self, account_id: str, role_arn: str, manifest_location: str, report_bucket_name: str) -> str: """ Create an S3 batch operation job. Args: account_id (str): AWS account ID role_arn (str): IAM role ARN for batch operations manifest_location (str): Location of the manifest file report_bucket_name (str): Bucket for job reports Returns: str: Job ID Raises: ClientError: If job creation fails """ try: bucket_name = manifest_location.split(':::')[1].split('/')[0] manifest_key = 'job-manifest.csv' manifest_obj = self.s3_client.head_object( Bucket=bucket_name, Key=manifest_key ) etag = manifest_obj['ETag'].strip('"') response = self.s3control_client.create_job( AccountId=account_id, Operation={ 'S3PutObjectTagging': { 'TagSet': [ { 'Key': 'BatchTag', 'Value': 'BatchValue' }, ] } }, Report={ 'Bucket': report_bucket_name, 'Format': 'Report_CSV_20180820', 'Enabled': True, 'Prefix': 'batch-op-reports', 'ReportScope': 'AllTasks' }, Manifest={ 'Spec': { 'Format': 'S3BatchOperations_CSV_20180820', 'Fields': ['Bucket', 'Key'] }, 'Location': { 'ObjectArn': manifest_location, 'ETag': etag } }, Priority=10, RoleArn=role_arn, Description='Batch job for tagging objects', ConfirmationRequired=True ) job_id = response['JobId'] print(f"The Job id is {job_id}") return job_id except ClientError as e: print(f"Error creating batch job: {e}") if 'Message' in str(e): print(f"Detailed error message: {e.response['Message']}") raise ``` + For API details, see [CreateJob](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/CreateJob) in *AWS SDK for Python (Boto3) API Reference*. ------ # Use `DeleteJobTagging` with an AWS SDK The following code examples show how to use `DeleteJobTagging`. 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: + [Learn the basics](s3-control_example_s3-control_Basics_section.md) ------ #### [ 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/src/main/java/com/example/s3/batch#code-examples). ``` /** * Asynchronously deletes the tags associated with a specific batch job. * * @param jobId The ID of the batch job whose tags should be deleted. * @param accountId The ID of the account associated with the batch job. * @return A CompletableFuture that completes when the job tags have been successfully deleted, or an exception is thrown if the deletion fails. */ public CompletableFuture deleteBatchJobTagsAsync(String jobId, String accountId) { DeleteJobTaggingRequest jobTaggingRequest = DeleteJobTaggingRequest.builder() .accountId(accountId) .jobId(jobId) .build(); return asyncClient.deleteJobTagging(jobTaggingRequest) .thenAccept(response -> { System.out.println("You have successfully deleted " + jobId + " tagging."); }) .exceptionally(ex -> { System.err.println("Failed to delete job tags: " + ex.getMessage()); throw new RuntimeException(ex); }); } ``` + For API details, see [DeleteJobTagging](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3control-2018-08-20/DeleteJobTagging) in *AWS SDK for Java 2.x 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/batch#code-examples). ``` def delete_job_tags(self, job_id: str, account_id: str) -> None: """ Delete all tags from a batch job. Args: job_id (str): ID of the batch job account_id (str): AWS account ID """ try: self.s3control_client.delete_job_tagging( AccountId=account_id, JobId=job_id ) print(f"You have successfully deleted {job_id} tagging.") except ClientError as e: print(f"Error deleting job tags: {e}") raise ``` + For API details, see [DeleteJobTagging](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/DeleteJobTagging) in *AWS SDK for Python (Boto3) API Reference*. ------ # Use `DescribeJob` with an AWS SDK or CLI The following code examples show how to use `DescribeJob`. 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: + [Learn the basics](s3-control_example_s3-control_Basics_section.md) ------ #### [ CLI ] **AWS CLI** **To describe an Amazon S3 batch operations job** The following `describe-job` provides configuration parameters and status for the specified batch operations job. ``` aws s3control describe-job \ --account-id 123456789012 \ --job-id 93735294-df46-44d5-8638-6356f335324e ``` Output: ``` { "Job": { "TerminationDate": "2019-10-03T21:49:53.944Z", "JobId": "93735294-df46-44d5-8638-6356f335324e", "FailureReasons": [], "Manifest": { "Spec": { "Fields": [ "Bucket", "Key" ], "Format": "S3BatchOperations_CSV_20180820" }, "Location": { "ETag": "69f52a4e9f797e987155d9c8f5880897", "ObjectArn": "arn:aws:s3:::employee-records-logs/inv-report/7a6a9be4-072c-407e-85a2-ec3e982f773e.csv" } }, "Operation": { "S3PutObjectTagging": { "TagSet": [ { "Value": "true", "Key": "confidential" } ] } }, "RoleArn": "arn:aws:iam::123456789012:role/S3BatchJobRole", "ProgressSummary": { "TotalNumberOfTasks": 8, "NumberOfTasksFailed": 0, "NumberOfTasksSucceeded": 8 }, "Priority": 42, "Report": { "ReportScope": "AllTasks", "Format": "Report_CSV_20180820", "Enabled": true, "Prefix": "batch-op-create-job", "Bucket": "arn:aws:s3:::employee-records-logs" }, "JobArn": "arn:aws:s3:us-west-2:123456789012:job/93735294-df46-44d5-8638-6356f335324e", "CreationTime": "2019-10-03T21:48:48.048Z", "Status": "Complete" } } ``` + For API details, see [DescribeJob](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3control/describe-job.html) in *AWS CLI Command 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/src/main/java/com/example/s3/batch#code-examples). ``` /** * Asynchronously describes the specified job. * * @param jobId the ID of the job to describe * @param accountId the ID of the AWS account associated with the job * @return a {@link CompletableFuture} that completes when the job description is available * @throws RuntimeException if an error occurs while describing the job */ public CompletableFuture describeJobAsync(String jobId, String accountId) { DescribeJobRequest jobRequest = DescribeJobRequest.builder() .jobId(jobId) .accountId(accountId) .build(); return getAsyncClient().describeJob(jobRequest) .thenAccept(response -> { System.out.println("Job ID: " + response.job().jobId()); System.out.println("Description: " + response.job().description()); System.out.println("Status: " + response.job().statusAsString()); System.out.println("Role ARN: " + response.job().roleArn()); System.out.println("Priority: " + response.job().priority()); System.out.println("Progress Summary: " + response.job().progressSummary()); // Print out details about the job manifest. JobManifest manifest = response.job().manifest(); System.out.println("Manifest Location: " + manifest.location().objectArn()); System.out.println("Manifest ETag: " + manifest.location().eTag()); // Print out details about the job operation. JobOperation operation = response.job().operation(); if (operation.s3PutObjectTagging() != null) { System.out.println("Operation: S3 Put Object Tagging"); System.out.println("Tag Set: " + operation.s3PutObjectTagging().tagSet()); } // Print out details about the job report. JobReport report = response.job().report(); System.out.println("Report Bucket: " + report.bucket()); System.out.println("Report Prefix: " + report.prefix()); System.out.println("Report Format: " + report.format()); System.out.println("Report Enabled: " + report.enabled()); System.out.println("Report Scope: " + report.reportScopeAsString()); }) .exceptionally(ex -> { System.err.println("Failed to describe job: " + ex.getMessage()); throw new RuntimeException(ex); }); } ``` + For API details, see [DescribeJob](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3control-2018-08-20/DescribeJob) in *AWS SDK for Java 2.x 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/batch#code-examples). ``` def describe_job_details(self, job_id: str, account_id: str) -> None: """ Describe detailed information about a batch job. Args: job_id (str): ID of the batch job account_id (str): AWS account ID """ try: response = self.s3control_client.describe_job( AccountId=account_id, JobId=job_id ) job = response['Job'] print(f"Job ID: {job['JobId']}") print(f"Description: {job.get('Description', 'N/A')}") print(f"Status: {job['Status']}") print(f"Role ARN: {job['RoleArn']}") print(f"Priority: {job['Priority']}") if 'ProgressSummary' in job: progress = job['ProgressSummary'] print(f"Progress Summary: Total={progress.get('TotalNumberOfTasks', 0)}, " f"Succeeded={progress.get('NumberOfTasksSucceeded', 0)}, " f"Failed={progress.get('NumberOfTasksFailed', 0)}") except ClientError as e: print(f"Error describing job: {e}") raise ``` + For API details, see [DescribeJob](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/DescribeJob) in *AWS SDK for Python (Boto3) API Reference*. ------ # Use `GetJobTagging` with an AWS SDK The following code examples show how to use `GetJobTagging`. 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: + [Learn the basics](s3-control_example_s3-control_Basics_section.md) ------ #### [ 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/src/main/java/com/example/s3/batch#code-examples). ``` /** * Asynchronously retrieves the tags associated with a specific job in an AWS account. * * @param jobId the ID of the job for which to retrieve the tags * @param accountId the ID of the AWS account associated with the job * @return a {@link CompletableFuture} that completes when the job tags have been retrieved, or with an exception if the operation fails * @throws RuntimeException if an error occurs while retrieving the job tags */ public CompletableFuture getJobTagsAsync(String jobId, String accountId) { GetJobTaggingRequest request = GetJobTaggingRequest.builder() .jobId(jobId) .accountId(accountId) .build(); return asyncClient.getJobTagging(request) .thenAccept(response -> { List tags = response.tags(); if (tags.isEmpty()) { System.out.println("No tags found for job ID: " + jobId); } else { for (S3Tag tag : tags) { System.out.println("Tag key is: " + tag.key()); System.out.println("Tag value is: " + tag.value()); } } }) .exceptionally(ex -> { System.err.println("Failed to get job tags: " + ex.getMessage()); throw new RuntimeException(ex); // Propagate the exception }); } ``` + For API details, see [GetJobTagging](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3control-2018-08-20/GetJobTagging) in *AWS SDK for Java 2.x 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/batch#code-examples). ``` def get_job_tags(self, job_id: str, account_id: str) -> None: """ Get tags associated with a batch job. Args: job_id (str): ID of the batch job account_id (str): AWS account ID """ try: response = self.s3control_client.get_job_tagging( AccountId=account_id, JobId=job_id ) tags = response.get('Tags', []) if tags: print(f"Tags for job {job_id}:") for tag in tags: print(f" {tag['Key']}: {tag['Value']}") else: print(f"No tags found for job ID: {job_id}") except ClientError as e: print(f"Error getting job tags: {e}") raise ``` + For API details, see [GetJobTagging](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/GetJobTagging) in *AWS SDK for Python (Boto3) API Reference*. ------ # Use `PutJobTagging` with an AWS SDK The following code examples show how to use `PutJobTagging`. 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: + [Learn the basics](s3-control_example_s3-control_Basics_section.md) ------ #### [ 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/src/main/java/com/example/s3/batch#code-examples). ``` /** * Asynchronously adds tags to a job in the system. * * @param jobId the ID of the job to add tags to * @param accountId the account ID associated with the job * @return a CompletableFuture that completes when the tagging operation is finished */ public CompletableFuture putJobTaggingAsync(String jobId, String accountId) { S3Tag departmentTag = S3Tag.builder() .key("department") .value("Marketing") .build(); S3Tag fiscalYearTag = S3Tag.builder() .key("FiscalYear") .value("2020") .build(); PutJobTaggingRequest putJobTaggingRequest = PutJobTaggingRequest.builder() .jobId(jobId) .accountId(accountId) .tags(departmentTag, fiscalYearTag) .build(); return asyncClient.putJobTagging(putJobTaggingRequest) .thenRun(() -> { System.out.println("Additional Tags were added to job " + jobId); }) .exceptionally(ex -> { System.err.println("Failed to add tags to job: " + ex.getMessage()); throw new RuntimeException(ex); // Propagate the exception }); } ``` + For API details, see [PutJobTagging](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3control-2018-08-20/PutJobTagging) in *AWS SDK for Java 2.x 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/batch#code-examples). ``` def put_job_tags(self, job_id: str, account_id: str) -> None: """ Add tags to a batch job. Args: job_id (str): ID of the batch job account_id (str): AWS account ID """ try: self.s3control_client.put_job_tagging( AccountId=account_id, JobId=job_id, Tags=[ {'Key': 'Environment', 'Value': 'Development'}, {'Key': 'Team', 'Value': 'DataProcessing'} ] ) print(f"Additional tags were added to job {job_id}") except ClientError as e: print(f"Error adding job tags: {e}") raise ``` + For API details, see [PutJobTagging](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/PutJobTagging) in *AWS SDK for Python (Boto3) API Reference*. ------ # Use `UpdateJobPriority` with an AWS SDK or CLI The following code examples show how to use `UpdateJobPriority`. 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: + [Learn the basics](s3-control_example_s3-control_Basics_section.md) ------ #### [ CLI ] **AWS CLI** **To update the job priority of an Amazon S3 batch operations job** The following `update-job-priority` example updates the specified job to a new priority. ``` aws s3control update-job-priority \ --account-id 123456789012 \ --job-id 8d9a18fe-c303-4d39-8ccc-860d372da386 \ --priority 52 ``` Output: ``` { "JobId": "8d9a18fe-c303-4d39-8ccc-860d372da386", "Priority": 52 } ``` + For API details, see [UpdateJobPriority](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3control/update-job-priority.html) in *AWS CLI Command 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/src/main/java/com/example/s3/batch#code-examples). ``` /** * Updates the priority of a job asynchronously. * * @param jobId the ID of the job to update * @param accountId the ID of the account associated with the job * @return a {@link CompletableFuture} that represents the asynchronous operation, which completes when the job priority has been updated or an error has occurred */ public CompletableFuture updateJobPriorityAsync(String jobId, String accountId) { UpdateJobPriorityRequest priorityRequest = UpdateJobPriorityRequest.builder() .accountId(accountId) .jobId(jobId) .priority(60) .build(); CompletableFuture future = new CompletableFuture<>(); getAsyncClient().updateJobPriority(priorityRequest) .thenAccept(response -> { System.out.println("The job priority was updated"); future.complete(null); // Complete the CompletableFuture on successful execution }) .exceptionally(ex -> { System.err.println("Failed to update job priority: " + ex.getMessage()); future.completeExceptionally(ex); // Complete the CompletableFuture exceptionally on error return null; // Return null to handle the exception }); return future; } ``` + For API details, see [UpdateJobPriority](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3control-2018-08-20/UpdateJobPriority) in *AWS SDK for Java 2.x 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/batch#code-examples). ``` def update_job_priority(self, job_id: str, account_id: str) -> None: """ Update the priority of a batch job and start it. Args: job_id (str): ID of the batch job account_id (str): AWS account ID """ try: response = self.s3control_client.describe_job( AccountId=account_id, JobId=job_id ) current_status = response['Job']['Status'] print(f"Current job status: {current_status}") if current_status in ['Ready', 'Suspended']: self.s3control_client.update_job_priority( AccountId=account_id, JobId=job_id, Priority=60 ) print("The job priority was updated") try: self.s3control_client.update_job_status( AccountId=account_id, JobId=job_id, RequestedJobStatus='Ready' ) print("Job activated successfully") except ClientError as activation_error: print(f"Note: Could not activate job automatically: {activation_error}") print("Job priority was updated successfully. Job may need manual activation in the console.") elif current_status in ['Active', 'Completing', 'Complete']: print(f"Job is in '{current_status}' state - priority cannot be updated") if current_status == 'Completing': print("Job is finishing up and will complete soon.") elif current_status == 'Complete': print("Job has already completed successfully.") else: print("Job is currently running.") else: print(f"Job is in '{current_status}' state - priority update not allowed") except ClientError as e: print(f"Error updating job priority: {e}") print("Continuing with the scenario...") return ``` + For API details, see [UpdateJobPriority](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/UpdateJobPriority) in *AWS SDK for Python (Boto3) API Reference*. ------ # Use `UpdateJobStatus` with an AWS SDK or CLI The following code examples show how to use `UpdateJobStatus`. 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: + [Learn the basics](s3-control_example_s3-control_Basics_section.md) ------ #### [ CLI ] **AWS CLI** **To update the status of an Amazon S3 batch operations job** The following `update-job-status` example cancels the specified job which is awaiting approval. ``` aws s3control update-job-status \ --account-id 123456789012 \ --job-id 8d9a18fe-c303-4d39-8ccc-860d372da386 \ --requested-job-status Cancelled ``` Output: ``` { "Status": "Cancelled", "JobId": "8d9a18fe-c303-4d39-8ccc-860d372da386" } ``` The following `update-job-status` example confirms and runs the specified which is awaiting approval. ``` aws s3control update-job-status \ --account-id 123456789012 \ --job-id 5782949f-3301-4fb3-be34-8d5bab54dbca \ --requested-job-status Ready Output:: { "Status": "Ready", "JobId": "5782949f-3301-4fb3-be34-8d5bab54dbca" } ``` The following `update-job-status` example cancels the specified job which is running. ``` aws s3control update-job-status \ --account-id 123456789012 \ --job-id 5782949f-3301-4fb3-be34-8d5bab54dbca \ --requested-job-status Cancelled Output:: { "Status": "Cancelling", "JobId": "5782949f-3301-4fb3-be34-8d5bab54dbca" } ``` + For API details, see [UpdateJobStatus](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3control/update-job-status.html) in *AWS CLI Command 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/src/main/java/com/example/s3/batch#code-examples). ``` /** * Cancels a job asynchronously. * * @param jobId The ID of the job to be canceled. * @param accountId The ID of the account associated with the job. * @return A {@link CompletableFuture} that completes when the job status has been updated to "CANCELLED". * If an error occurs during the update, the returned future will complete exceptionally. */ public CompletableFuture cancelJobAsync(String jobId, String accountId) { UpdateJobStatusRequest updateJobStatusRequest = UpdateJobStatusRequest.builder() .accountId(accountId) .jobId(jobId) .requestedJobStatus(String.valueOf(JobStatus.CANCELLED)) .build(); return asyncClient.updateJobStatus(updateJobStatusRequest) .thenAccept(updateJobStatusResponse -> { System.out.println("Job status updated to: " + updateJobStatusResponse.status()); }) .exceptionally(ex -> { System.err.println("Failed to cancel job: " + ex.getMessage()); throw new RuntimeException(ex); // Propagate the exception }); } ``` + For API details, see [UpdateJobStatus](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3control-2018-08-20/UpdateJobStatus) in *AWS SDK for Java 2.x 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/batch#code-examples). ``` def cancel_job(self, job_id: str, account_id: str) -> None: """ Cancel an S3 batch job. Args: job_id (str): ID of the batch job account_id (str): AWS account ID """ try: response = self.s3control_client.describe_job( AccountId=account_id, JobId=job_id ) current_status = response['Job']['Status'] print(f"Current job status: {current_status}") if current_status in ['Ready', 'Suspended', 'Active']: self.s3control_client.update_job_status( AccountId=account_id, JobId=job_id, RequestedJobStatus='Cancelled' ) print(f"Job {job_id} was successfully canceled.") elif current_status in ['Completing', 'Complete']: print(f"Job is in '{current_status}' state - cannot be cancelled") if current_status == 'Completing': print("Job is finishing up and will complete soon.") elif current_status == 'Complete': print("Job has already completed successfully.") else: print(f"Job is in '{current_status}' state - cancel not allowed") except ClientError as e: print(f"Error canceling job: {e}") raise ``` + For API details, see [UpdateJobStatus](https://docs.aws.amazon.com/goto/boto3/s3control-2018-08-20/UpdateJobStatus) in *AWS SDK for Python (Boto3) API Reference*. ------