Menu
AWS IoT
Developer Guide

CreateJob

Creates a job.

Request syntax:

PUT /jobs/jobId Content-type: application/json { "targets": [ "string" ], "documentSource": "string", "document": "string", "description": "string", "presignedUrlConfig": { "roleArn": "string", "expiresInSec": "long" }, "targetSelection": "string", "jobExecutionsRolloutConfig": { "maximumPerMinute": "integer" }, "documentParameters": { "string": "string" } }

URI Request Parameters:

Name

Type

Req?

Description

jobId

JobId

yes

A job identifier which must be unique for your AWS account. We recommend using a UUID. Alpha-numeric characters, "-" and "_" are valid for use here.

Request Body Parameters:

Name

Type

Req?

Description

targets

JobTargets

yes

A list of things and thing groups to which the job should be sent.

documentSource

JobDocumentSource

no

An S3 link to the job document.

document

JobDocument

no

The job document.

description

JobDescription

no

A short text description of the job.

presignedUrlConfig

PresignedUrlConfig

no

Configuration information for pre-signed S3 URLs.

targetSelection

TargetSelection

no

Specifies whether the job will continue to run (CONTINUOUS), or will be complete after all those things specified as targets have completed the job (SNAPSHOT). If continuous, the job may also be run on a thing when a change is detected in a target. For example, a job will run on a thing when the thing is added to a target group, even after the job was completed by all things originally in the group.

jobExecutionsRolloutConfig

JobExecutionsRolloutConfig

no

Allows you to create a staged rollout of the job.

documentParameters

JobDocumentParameters

no

Parameters for the job document.

Response syntax:

Content-type: application/json { "jobArn": "string", "jobId": "string", "description": "string" }

Response Body Parameters:

Name

Type

Req?

Description

jobArn

JobArn

no

The job ARN.

jobId

JobId

no

The unique identifier you assigned to this job.

description

JobDescription

no

The job description.

Errors:

InvalidRequestException

The contents of the request were invalid. For example, this code is returned when an UpdateJobExecution request contains invalid status details. The message contains details about the error.

HTTP response code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP response code: 404

ResourceAlreadyExistsException

The resource already exists.

HTTP response code: 409

LimitExceededException

The number of attached entities exceeds the limit.

HTTP response code: 410

ThrottlingException

The rate exceeds the limit.

HTTP response code: 429

ServiceUnavailableException

The service is temporarily unavailable.

HTTP response code: 503

CLI

Synopsis:

aws iot create-job \ --job-id <value> \ --targets <value> \ [--document-source <value>] \ [--document <value>] \ [--description <value>] \ [--presigned-url-config <value>] \ [--target-selection <value>] \ [--job-executions-rollout-config <value>] \ [--document-parameters <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "jobId": "string", "targets": [ "string" ], "documentSource": "string", "document": "string", "description": "string", "presignedUrlConfig": { "roleArn": "string", "expiresInSec": "long" }, "targetSelection": "string", "jobExecutionsRolloutConfig": { "maximumPerMinute": "integer" }, "documentParameters": { "string": "string" } }

cli-input-json fields:

Name

Type

Description

jobId

string

length max:64 min:1

pattern: [a-zA-Z0-9_-]+

A job identifier which must be unique for your AWS account. We recommend using a UUID. Alpha-numeric characters, "-" and "_" are valid for use here.

targets

list

member: TargetArn

A list of things and thing groups to which the job should be sent.

TargetArn

string

documentSource

string

length max:1350 min:1

An S3 link to the job document.

document

string

length max:32768

The job document.

description

string

length max:2028

pattern: [^\\p{C}]+

A short text description of the job.

presignedUrlConfig

PresignedUrlConfig

Configuration information for pre-signed S3 URLs.

roleArn

string

length max:2048 min:20

The ARN of an IAM role that grants grants permission to download files from the S3 bucket where the job data/updates are stored. The role must also grant permission for IoT to download the files.

expiresInSec

long

java class: java.lang.Long

range- max:3600 min:60

How long (in seconds) pre-signed URLs are valid. Valid values are 60 - 3600, the default value is 3600 seconds. Pre-signed URLs are generated when Jobs receives an MQTT request for the job document.

targetSelection

string

enum: CONTINUOUS | SNAPSHOT

java class: com.amazonaws.iot.laser.TargetSelection

Specifies whether the job will continue to run (CONTINUOUS), or will be complete after all those things specified as targets have completed the job (SNAPSHOT). If continuous, the job may also be run on a thing when a change is detected in a target. For example, a job will run on a thing when the thing is added to a target group, even after the job was completed by all things originally in the group.

jobExecutionsRolloutConfig

JobExecutionsRolloutConfig

Allows you to create a staged rollout of the job.

maximumPerMinute

integer

java class: java.lang.Integer

range- max:1000 min:1

The maximum number of things that will be notified of a pending job, per minute. This parameter allows you to create a staged rollout.

documentParameters

map

key: ParameterKey

value: ParameterValue

Parameters for the job document.

ParameterKey

string

length max:128 min:1

pattern: [a-zA-Z0-9:_-]+

ParameterValue

string

length max:1024 min:1

pattern: [^\\p{C}]+

Output:

{ "jobArn": "string", "jobId": "string", "description": "string" }

cli output fields:

Name

Type

Description

jobArn

string

The job ARN.

jobId

string

length max:64 min:1

pattern: [a-zA-Z0-9_-]+

The unique identifier you assigned to this job.

description

string

length max:2028

pattern: [^\\p{C}]+

The job description.

On this page: