CreateJob - Amazon Simple Storage Service

CreateJob

This operation creates an S3 Batch Operations job.

You can use S3 Batch Operations to perform large-scale batch actions on Amazon S3 objects. Batch Operations can run a single action on lists of Amazon S3 objects that you specify. For more information, see S3 Batch Operations in the Amazon S3 User Guide.

Permissions

For information about permissions required to use the Batch Operations, see Granting permissions for S3 Batch Operations in the Amazon S3 User Guide.

Related actions include:

Request Syntax

POST /v20180820/jobs HTTP/1.1 Host: s3-control.amazonaws.com x-amz-account-id: AccountId <?xml version="1.0" encoding="UTF-8"?> <CreateJobRequest xmlns="http://awss3control.amazonaws.com/doc/2018-08-20/"> <ConfirmationRequired>boolean</ConfirmationRequired> <Operation> <LambdaInvoke> <FunctionArn>string</FunctionArn> <InvocationSchemaVersion>string</InvocationSchemaVersion> <UserArguments> <entry> <key>string</key> <value>string</value> </entry> </UserArguments> </LambdaInvoke> <S3DeleteObjectTagging> </S3DeleteObjectTagging> <S3InitiateRestoreObject> <ExpirationInDays>integer</ExpirationInDays> <GlacierJobTier>string</GlacierJobTier> </S3InitiateRestoreObject> <S3PutObjectAcl> <AccessControlPolicy> <AccessControlList> <Grants> <S3Grant> <Grantee> <DisplayName>string</DisplayName> <Identifier>string</Identifier> <TypeIdentifier>string</TypeIdentifier> </Grantee> <Permission>string</Permission> </S3Grant> </Grants> <Owner> <DisplayName>string</DisplayName> <ID>string</ID> </Owner> </AccessControlList> <CannedAccessControlList>string</CannedAccessControlList> </AccessControlPolicy> </S3PutObjectAcl> <S3PutObjectCopy> <AccessControlGrants> <S3Grant> <Grantee> <DisplayName>string</DisplayName> <Identifier>string</Identifier> <TypeIdentifier>string</TypeIdentifier> </Grantee> <Permission>string</Permission> </S3Grant> </AccessControlGrants> <BucketKeyEnabled>boolean</BucketKeyEnabled> <CannedAccessControlList>string</CannedAccessControlList> <ChecksumAlgorithm>string</ChecksumAlgorithm> <MetadataDirective>string</MetadataDirective> <ModifiedSinceConstraint>timestamp</ModifiedSinceConstraint> <NewObjectMetadata> <CacheControl>string</CacheControl> <ContentDisposition>string</ContentDisposition> <ContentEncoding>string</ContentEncoding> <ContentLanguage>string</ContentLanguage> <ContentLength>long</ContentLength> <ContentMD5>string</ContentMD5> <ContentType>string</ContentType> <HttpExpiresDate>timestamp</HttpExpiresDate> <RequesterCharged>boolean</RequesterCharged> <SSEAlgorithm>string</SSEAlgorithm> <UserMetadata> <entry> <key>string</key> <value>string</value> </entry> </UserMetadata> </NewObjectMetadata> <NewObjectTagging> <S3Tag> <Key>string</Key> <Value>string</Value> </S3Tag> </NewObjectTagging> <ObjectLockLegalHoldStatus>string</ObjectLockLegalHoldStatus> <ObjectLockMode>string</ObjectLockMode> <ObjectLockRetainUntilDate>timestamp</ObjectLockRetainUntilDate> <RedirectLocation>string</RedirectLocation> <RequesterPays>boolean</RequesterPays> <SSEAwsKmsKeyId>string</SSEAwsKmsKeyId> <StorageClass>string</StorageClass> <TargetKeyPrefix>string</TargetKeyPrefix> <TargetResource>string</TargetResource> <UnModifiedSinceConstraint>timestamp</UnModifiedSinceConstraint> </S3PutObjectCopy> <S3PutObjectLegalHold> <LegalHold> <Status>string</Status> </LegalHold> </S3PutObjectLegalHold> <S3PutObjectRetention> <BypassGovernanceRetention>boolean</BypassGovernanceRetention> <Retention> <Mode>string</Mode> <RetainUntilDate>timestamp</RetainUntilDate> </Retention> </S3PutObjectRetention> <S3PutObjectTagging> <TagSet> <S3Tag> <Key>string</Key> <Value>string</Value> </S3Tag> </TagSet> </S3PutObjectTagging> <S3ReplicateObject> </S3ReplicateObject> </Operation> <Report> <Bucket>string</Bucket> <Enabled>boolean</Enabled> <Format>string</Format> <Prefix>string</Prefix> <ReportScope>string</ReportScope> </Report> <ClientRequestToken>string</ClientRequestToken> <Manifest> <Location> <ETag>string</ETag> <ObjectArn>string</ObjectArn> <ObjectVersionId>string</ObjectVersionId> </Location> <Spec> <Fields> <member>string</member> </Fields> <Format>string</Format> </Spec> </Manifest> <Description>string</Description> <Priority>integer</Priority> <RoleArn>string</RoleArn> <Tags> <S3Tag> <Key>string</Key> <Value>string</Value> </S3Tag> </Tags> <ManifestGenerator> <S3JobManifestGenerator> <EnableManifestOutput>boolean</EnableManifestOutput> <ExpectedBucketOwner>string</ExpectedBucketOwner> <Filter> <CreatedAfter>timestamp</CreatedAfter> <CreatedBefore>timestamp</CreatedBefore> <EligibleForReplication>boolean</EligibleForReplication> <KeyNameConstraint> <MatchAnyPrefix> <member>string</member> </MatchAnyPrefix> <MatchAnySubstring> <member>string</member> </MatchAnySubstring> <MatchAnySuffix> <member>string</member> </MatchAnySuffix> </KeyNameConstraint> <MatchAnyStorageClass> <member>string</member> </MatchAnyStorageClass> <ObjectReplicationStatuses> <member>string</member> </ObjectReplicationStatuses> <ObjectSizeGreaterThanBytes>long</ObjectSizeGreaterThanBytes> <ObjectSizeLessThanBytes>long</ObjectSizeLessThanBytes> </Filter> <ManifestOutputLocation> <Bucket>string</Bucket> <ExpectedManifestBucketOwner>string</ExpectedManifestBucketOwner> <ManifestEncryption> <SSE-KMS> <KeyId>string</KeyId> </SSE-KMS> <SSE-S3> </SSE-S3> </ManifestEncryption> <ManifestFormat>string</ManifestFormat> <ManifestPrefix>string</ManifestPrefix> </ManifestOutputLocation> <SourceBucket>string</SourceBucket> </S3JobManifestGenerator> </ManifestGenerator> </CreateJobRequest>

URI Request Parameters

The request uses the following URI parameters.

x-amz-account-id

The AWS account ID that creates the job.

Length Constraints: Maximum length of 64.

Pattern: ^\d{12}$

Required: Yes

Request Body

The request accepts the following data in XML format.

CreateJobRequest

Root level tag for the CreateJobRequest parameters.

Required: Yes

ClientRequestToken

An idempotency token to ensure that you don't accidentally submit the same request twice. You can use any string up to the maximum length.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Required: Yes

ConfirmationRequired

Indicates whether confirmation is required before Amazon S3 runs the job. Confirmation is only required for jobs created through the Amazon S3 console.

Type: Boolean

Required: No

Description

A description for this job. You can use any string within the permitted length. Descriptions don't need to be unique and can be used for multiple jobs.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Required: No

Manifest

Configuration parameters for the manifest.

Type: JobManifest data type

Required: No

ManifestGenerator

The attribute container for the ManifestGenerator details. Jobs must be created with either a manifest file or a ManifestGenerator, but not both.

Type: JobManifestGenerator data type

Note: This object is a Union. Only one member of this object can be specified or returned.

Required: No

Operation

The action that you want this job to perform on every object listed in the manifest. For more information about the available actions, see Operations in the Amazon S3 User Guide.

Type: JobOperation data type

Required: Yes

Priority

The numerical priority for this job. Higher numbers indicate higher priority.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 2147483647.

Required: Yes

Report

Configuration parameters for the optional job-completion report.

Type: JobReport data type

Required: Yes

RoleArn

The Amazon Resource Name (ARN) for the AWS Identity and Access Management (IAM) role that Batch Operations will use to run this job's action on every object in the manifest.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: arn:[^:]+:iam::\d{12}:role/.*

Required: Yes

Tags

A set of tags to associate with the S3 Batch Operations job. This is an optional parameter.

Type: Array of S3Tag data types

Required: No

Response Syntax

HTTP/1.1 200 <?xml version="1.0" encoding="UTF-8"?> <CreateJobResult> <JobId>string</JobId> </CreateJobResult>

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

CreateJobResult

Root level tag for the CreateJobResult parameters.

Required: Yes

JobId

The ID for this job. Amazon S3 generates this ID automatically and returns it after a successful Create Job request.

Type: String

Length Constraints: Minimum length of 5. Maximum length of 36.

Pattern: [a-zA-Z0-9\-\_]+

Errors

BadRequestException

HTTP Status Code: 400

IdempotencyException

HTTP Status Code: 400

InternalServiceException

HTTP Status Code: 500

TooManyRequestsException

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: