jobs

Creates, updates, deletes, gets or lists a jobs resource.

Overview

Name	jobs
Type	Resource
Id	aws.s3control.jobs

Fields

The following fields are returned by SELECT queries:

describe_job

Name	Datatype	Description
confirmation_required	boolean	Indicates whether confirmation is required before Amazon S3 begins running the specified job. Confirmation is required only for jobs created through the Amazon S3 console.
creation_time	string	A timestamp indicating when this job was created.
description	string	The description for this job, if one was provided in this job's Create Job request.
failure_reasons	string	If the specified job failed, this field contains information describing the failure.
generated_manifest_descriptor	string	The attribute of the JobDescriptor containing details about the job's generated manifest.
job_arn	string	The Amazon Resource Name (ARN) for this job.
job_id	string	The ID for the specified job.
manifest	string	The configuration information for the specified job's manifest object.
manifest_generator	string	The manifest generator that was used to generate a job manifest for this job.
operation	string	The operation that the specified job is configured to run on the objects listed in the manifest.
priority	integer	The priority of the specified job.
progress_summary	string	Describes the total number of tasks that the specified job has run, the number of tasks that succeeded, and the number of tasks that failed.
report	string	Contains the configuration information for the job-completion report if you requested one in the Create Job request.
role_arn	string	The Amazon Resource Name (ARN) for the Identity and Access Management (IAM) role assigned to run the tasks for this job.
status	string	The current status of the specified job.
status_update_reason	string	The reason for updating the job.
suspended_cause	string	The reason why the specified job was suspended. A job is only suspended if you create it through the Amazon S3 console. When you create the job, it enters the Suspended state to await confirmation before running. After you confirm the job, it automatically exits the Suspended state.
suspended_date	string	The timestamp when this job was suspended, if it has been suspended.
termination_date	string	A timestamp indicating when this job terminated. A job's termination date is the date and time when it succeeded, failed, or was canceled.

list_jobs

Name	Datatype	Description
creation_time	string	A timestamp indicating when the specified job was created.
description	string	The user-specified description that was included in the specified job's Create Job request.
job_id	string	The ID for the specified job.
operation	string	The operation that the specified job is configured to run on every object listed in the manifest.
priority	integer	The current priority for the specified job.
progress_summary	string	Describes the total number of tasks that the specified job has run, the number of tasks that succeeded, and the number of tasks that failed.
status	string	The specified job's current status.
termination_date	string	A timestamp indicating when the specified job terminated. A job's termination date is the date and time when it succeeded, failed, or was canceled.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_job	select	x-amz-account-id, id, region		Retrieves the configuration parameters and status for a Batch Operations job. For more information, see S3 Batch Operations in the Amazon S3 User Guide. Permissions To use the DescribeJob operation, you must have permission to perform the s3:DescribeJob action. Related actions include: CreateJob ListJobs UpdateJobPriority UpdateJobStatus
list_jobs	select	x-amz-account-id, region	jobStatuses, nextToken, maxResults	Lists current S3 Batch Operations jobs as well as the jobs that have ended within the last 90 days for the Amazon Web Services account making the request. For more information, see S3 Batch Operations in the Amazon S3 User Guide. Permissions To use the ListJobs operation, you must have permission to perform the s3:ListJobs action. Related actions include: CreateJob DescribeJob UpdateJobPriority UpdateJobStatus
create_job	insert	x-amz-account-id, region, ClientRequestToken, RoleArn		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: DescribeJob ListJobs UpdateJobPriority UpdateJobStatus JobOperation
update_job_priority	update	x-amz-account-id, id, priority, region		Updates an existing S3 Batch Operations job's priority. For more information, see S3 Batch Operations in the Amazon S3 User Guide. Permissions To use the UpdateJobPriority operation, you must have permission to perform the s3:UpdateJobPriority action. Related actions include: CreateJob ListJobs DescribeJob UpdateJobStatus
update_job_status	update	x-amz-account-id, id, requestedJobStatus, region	statusUpdateReason	Updates the status for the specified job. Use this operation to confirm that you want to run a job or to cancel an existing job. For more information, see S3 Batch Operations in the Amazon S3 User Guide. Permissions To use the UpdateJobStatus operation, you must have permission to perform the s3:UpdateJobStatus action. Related actions include: CreateJob ListJobs DescribeJob UpdateJobStatus

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
id	string	The ID of the job whose status you want to update.
priority	integer	The priority you want to assign to this job.
region	string	AWS region (default: us-east-1)
requestedJobStatus	string	The status that you want to move the specified job to.
x-amz-account-id	string	The Amazon Web Services account ID associated with the S3 Batch Operations job.
jobStatuses	array	The List Jobs request returns jobs that match the statuses listed in this element.
maxResults	integer	The maximum number of jobs that Amazon S3 will include in the List Jobs response. If there are more jobs than this number, the response will include a pagination token in the NextToken field to enable you to retrieve the next page of results.
nextToken	string	A pagination token to request the next page of results. Use the token that Amazon S3 returned in the NextToken element of the ListJobsResult from the previous List Jobs request.
statusUpdateReason	string	A description of the reason why you want to change the specified job's status. This field can be any string up to the maximum length.

SELECT examples

describe_job

Retrieves the configuration parameters and status for a Batch Operations job. For more information, see S3 Batch Operations in the Amazon S3 User Guide. Permissions To use the DescribeJob operation, you must have permission to perform the s3:DescribeJob action. Related actions include: CreateJob ListJobs UpdateJobPriority UpdateJobStatus

SELECT
confirmation_required,
creation_time,
description,
failure_reasons,
generated_manifest_descriptor,
job_arn,
job_id,
manifest,
manifest_generator,
operation,
priority,
progress_summary,
report,
role_arn,
status,
status_update_reason,
suspended_cause,
suspended_date,
termination_date
FROM aws.s3control.jobs
WHERE `x-amz-account-id` = '{{ x-amz-account-id }}' -- required
AND id = '{{ id }}' -- required
AND region = '{{ region }}' -- required
;

list_jobs

Lists current S3 Batch Operations jobs as well as the jobs that have ended within the last 90 days for the Amazon Web Services account making the request. For more information, see S3 Batch Operations in the Amazon S3 User Guide. Permissions To use the ListJobs operation, you must have permission to perform the s3:ListJobs action. Related actions include: CreateJob DescribeJob UpdateJobPriority UpdateJobStatus

SELECT
creation_time,
description,
job_id,
operation,
priority,
progress_summary,
status,
termination_date
FROM aws.s3control.jobs
WHERE `x-amz-account-id` = '{{ x-amz-account-id }}' -- required
AND region = '{{ region }}' -- required
AND jobStatuses = '{{ jobStatuses }}'
AND nextToken = '{{ nextToken }}'
AND maxResults = '{{ maxResults }}'
;

INSERT examples

create_job

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: DescribeJob ListJobs UpdateJobPriority UpdateJobStatus JobOperation

INSERT INTO aws.s3control.jobs (
ConfirmationRequired,
Operation,
Report,
ClientRequestToken,
Manifest,
Description,
Priority,
RoleArn,
Tags,
ManifestGenerator,
`x-amz-account-id`,
region
)
SELECT 
{{ ConfirmationRequired }},
'{{ Operation }}',
'{{ Report }}',
'{{ ClientRequestToken }}' /* required */,
'{{ Manifest }}',
'{{ Description }}',
{{ Priority }},
'{{ RoleArn }}' /* required */,
'{{ Tags }}',
'{{ ManifestGenerator }}',
'{{ x-amz-account-id }}',
'{{ region }}'
RETURNING
job_id
;

Manifest

# Description fields are for documentation purposes
- name: jobs
props:
  - name: x-amz-account-id
    value: "{{ x-amz-account-id }}"
    description: Required parameter for the jobs resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the jobs resource.
  - name: ConfirmationRequired
    value: {{ ConfirmationRequired }}
  - name: Operation
    description: |
      The operation that you want this job to perform on every object listed in the manifest. For more information about the available operations, see Operations in the Amazon S3 User Guide.
    value:
      LambdaInvoke:
        FunctionArn: "{{ FunctionArn }}"
        InvocationSchemaVersion: "{{ InvocationSchemaVersion }}"
        UserArguments: "{{ UserArguments }}"
      S3PutObjectCopy:
        TargetResource: "{{ TargetResource }}"
        CannedAccessControlList: "{{ CannedAccessControlList }}"
        AccessControlGrants:
          - Grantee:
              TypeIdentifier: "{{ TypeIdentifier }}"
              Identifier: "{{ Identifier }}"
              DisplayName: "{{ DisplayName }}"
            Permission: "{{ Permission }}"
        MetadataDirective: "{{ MetadataDirective }}"
        ModifiedSinceConstraint: "{{ ModifiedSinceConstraint }}"
        NewObjectMetadata:
          CacheControl: "{{ CacheControl }}"
          ContentDisposition: "{{ ContentDisposition }}"
          ContentEncoding: "{{ ContentEncoding }}"
          ContentLanguage: "{{ ContentLanguage }}"
          UserMetadata: "{{ UserMetadata }}"
          ContentLength: {{ ContentLength }}
          ContentMD5: "{{ ContentMD5 }}"
          ContentType: "{{ ContentType }}"
          HttpExpiresDate: "{{ HttpExpiresDate }}"
          RequesterCharged: {{ RequesterCharged }}
          SSEAlgorithm: "{{ SSEAlgorithm }}"
        NewObjectTagging:
          - Key: "{{ Key }}"
            Value: "{{ Value }}"
        RedirectLocation: "{{ RedirectLocation }}"
        RequesterPays: {{ RequesterPays }}
        StorageClass: "{{ StorageClass }}"
        UnModifiedSinceConstraint: "{{ UnModifiedSinceConstraint }}"
        SSEAwsKmsKeyId: "{{ SSEAwsKmsKeyId }}"
        TargetKeyPrefix: "{{ TargetKeyPrefix }}"
        ObjectLockLegalHoldStatus: "{{ ObjectLockLegalHoldStatus }}"
        ObjectLockMode: "{{ ObjectLockMode }}"
        ObjectLockRetainUntilDate: "{{ ObjectLockRetainUntilDate }}"
        BucketKeyEnabled: {{ BucketKeyEnabled }}
        ChecksumAlgorithm: "{{ ChecksumAlgorithm }}"
      S3PutObjectAcl:
        AccessControlPolicy:
          AccessControlList:
            Owner:
              ID: "{{ ID }}"
              DisplayName: "{{ DisplayName }}"
            Grants:
              - Grantee:
                  TypeIdentifier: "{{ TypeIdentifier }}"
                  Identifier: "{{ Identifier }}"
                  DisplayName: "{{ DisplayName }}"
                Permission: "{{ Permission }}"
          CannedAccessControlList: "{{ CannedAccessControlList }}"
      S3PutObjectTagging:
        TagSet:
          - Key: "{{ Key }}"
            Value: "{{ Value }}"
      S3DeleteObjectTagging: "{{ S3DeleteObjectTagging }}"
      S3InitiateRestoreObject:
        ExpirationInDays: {{ ExpirationInDays }}
        GlacierJobTier: "{{ GlacierJobTier }}"
      S3PutObjectLegalHold:
        LegalHold:
          Status: "{{ Status }}"
      S3PutObjectRetention:
        BypassGovernanceRetention: {{ BypassGovernanceRetention }}
        Retention:
          RetainUntilDate: "{{ RetainUntilDate }}"
          Mode: "{{ Mode }}"
      S3ReplicateObject: "{{ S3ReplicateObject }}"
      S3ComputeObjectChecksum:
        ChecksumAlgorithm: "{{ ChecksumAlgorithm }}"
        ChecksumType: "{{ ChecksumType }}"
      S3UpdateObjectEncryption:
        ObjectEncryption:
          SSEKMS:
            KMSKeyArn: "{{ KMSKeyArn }}"
            BucketKeyEnabled: {{ BucketKeyEnabled }}
  - name: Report
    description: |
      Contains the configuration parameters for a job-completion report.
    value:
      Bucket: "{{ Bucket }}"
      Format: "{{ Format }}"
      Enabled: {{ Enabled }}
      Prefix: "{{ Prefix }}"
      ReportScope: "{{ ReportScope }}"
      ExpectedBucketOwner: "{{ ExpectedBucketOwner }}"
  - name: ClientRequestToken
    value: "{{ ClientRequestToken }}"
  - name: Manifest
    description: |
      Contains the configuration information for a job's manifest.
    value:
      Spec:
        Format: "{{ Format }}"
        Fields:
          - "{{ Fields }}"
      Location:
        ObjectArn: "{{ ObjectArn }}"
        ObjectVersionId: "{{ ObjectVersionId }}"
        ETag: "{{ ETag }}"
  - name: Description
    value: "{{ Description }}"
  - name: Priority
    value: {{ Priority }}
  - name: RoleArn
    value: "{{ RoleArn }}"
  - name: Tags
    value:
      - Key: "{{ Key }}"
        Value: "{{ Value }}"
  - name: ManifestGenerator
    description: |
      Configures the type of the job's ManifestGenerator.
    value:
      S3JobManifestGenerator:
        ExpectedBucketOwner: "{{ ExpectedBucketOwner }}"
        SourceBucket: "{{ SourceBucket }}"
        ManifestOutputLocation:
          ExpectedManifestBucketOwner: "{{ ExpectedManifestBucketOwner }}"
          Bucket: "{{ Bucket }}"
          ManifestPrefix: "{{ ManifestPrefix }}"
          ManifestEncryption:
            SSES3: "{{ SSES3 }}"
            SSEKMS:
              KeyId: "{{ KeyId }}"
          ManifestFormat: "{{ ManifestFormat }}"
        Filter:
          EligibleForReplication: {{ EligibleForReplication }}
          CreatedAfter: "{{ CreatedAfter }}"
          CreatedBefore: "{{ CreatedBefore }}"
          ObjectReplicationStatuses:
            - "{{ ObjectReplicationStatuses }}"
          KeyNameConstraint:
            MatchAnyPrefix:
              - "{{ MatchAnyPrefix }}"
            MatchAnySuffix:
              - "{{ MatchAnySuffix }}"
            MatchAnySubstring:
              - "{{ MatchAnySubstring }}"
          ObjectSizeGreaterThanBytes: {{ ObjectSizeGreaterThanBytes }}
          ObjectSizeLessThanBytes: {{ ObjectSizeLessThanBytes }}
          MatchAnyStorageClass:
            - "{{ MatchAnyStorageClass }}"
          MatchAnyObjectEncryption:
            - SSES3: "{{ SSES3 }}"
              SSEKMS:
                KmsKeyArn: "{{ KmsKeyArn }}"
                BucketKeyEnabled: {{ BucketKeyEnabled }}
              DSSEKMS:
                KmsKeyArn: "{{ KmsKeyArn }}"
              SSEC: "{{ SSEC }}"
              NOTSSE: "{{ NOTSSE }}"
        EnableManifestOutput: {{ EnableManifestOutput }}

UPDATE examples

update_job_priority

Updates an existing S3 Batch Operations job's priority. For more information, see S3 Batch Operations in the Amazon S3 User Guide. Permissions To use the UpdateJobPriority operation, you must have permission to perform the s3:UpdateJobPriority action. Related actions include: CreateJob ListJobs DescribeJob UpdateJobStatus

UPDATE aws.s3control.jobs
SET 
-- No updatable properties
WHERE 
`x-amz-account-id` = '{{ x-amz-account-id }}' --required
AND id = '{{ id }}' --required
AND priority = '{{ priority }}' --required
AND region = '{{ region }}' --required
RETURNING
job_id,
priority;

update_job_status

Updates the status for the specified job. Use this operation to confirm that you want to run a job or to cancel an existing job. For more information, see S3 Batch Operations in the Amazon S3 User Guide. Permissions To use the UpdateJobStatus operation, you must have permission to perform the s3:UpdateJobStatus action. Related actions include: CreateJob ListJobs DescribeJob UpdateJobStatus

UPDATE aws.s3control.jobs
SET 
-- No updatable properties
WHERE 
`x-amz-account-id` = '{{ x-amz-account-id }}' --required
AND id = '{{ id }}' --required
AND requestedJobStatus = '{{ requestedJobStatus }}' --required
AND region = '{{ region }}' --required
AND statusUpdateReason = '{{ statusUpdateReason}}'
RETURNING
job_id,
status,
status_update_reason;