Menu
AWS IoT
Developer Guide

Using the AWS IoT Jobs APIs

There are two categories of API used in AWS IoT Jobs:

  • Those used for management and control of jobs.

  • Those used by the devices executing those jobs.

In general, job management and control uses an HTTPS protocol API. Devices can use either an MQTT or an HTTPS protocol API. (The HTTPS API is designed for a low volume of calls typical when creating and tracking jobs. It usually opens a connection for a single request, and then closes the connection after the response is received. The MQTT API allows long polling. It is designed for large amounts of traffic that can scale to millions of devices.)

Note

Each Jobs HTTPS API has a corresponding command that allows you to call the API from the AWS CLI. The commands are lowercase, with hyphens between the words that make up the name of the API. For example, you can invoke the CreateJob API on the CLI by typing:

aws iot create-job ...

Job Management and Control API

Job Management and Control Data Types

The following data types are used by management and control applications to communicate with Jobs.

Job

Job data typesyntax (1)description (1)
Job data type

The Job object contains details about a job.

syntax (1)
{ "jobArn": "string", "jobId": "string", "status": "IN_PROGRESS|CANCELED|COMPLETED", "targetSelection": "CONTINUOUS|SNAPSHOT", "comment": "string", "targets": ["string"], "description": "string", "createdAt": timestamp, "lastUpdatedAt": timestamp, "completedAt": timestamp, "jobProcessDetails": { "processingTargets": ["string"], "numberOfCanceledThings": "long", "numberOfSucceededThings": "long", "numberOfFailedThings": "long", "numberOfRejectedThings": "long", "numberOfQueuedThings": "long", "numberOfInProgressThings": "long", "numberOfRemovedThings": "long", }, "presignedUrlConfig": { "expiresInSec": number, "roleArn": "string" }, "jobExecutionRolloutConfig": { "maximumPerMinute": "integer" } }
description (1)
jobArn

An ARN identifying the job with the format "arn:aws:iot:region:account:job/jobId".

jobId

The unique identifier you assigned to this job when it was created.

status

The status of the job, one of IN_PROGRESS, CANCELED, or COMPLETED.

targetSelection

Specifies whether the job continues to run (CONTINUOUS) or is complete after those things specified as targets have completed the job (SNAPSHOT). If CONTINUOUS, the job might also be run on a thing when a change is detected in a target. For example, a job runs 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.

comment

If the job was updated, describes the reason for the update.

targets

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

description

A short text description of the job.

createdAt

The time, in milliseconds since the epoch, when the job was created.

lastUpdatedAt

The time, in milliseconds since the epoch, when the job was last updated.

completedAt

The time, in milliseconds since the epoch, when the job was completed.

jobProcessDetails

Details about the job process:

processingTargets

A list of AWS IoT things and thing groups that are currently executing the job.

numberOfCanceledThings

The number of AWS IoT things that canceled the job.

numberOfSucceededThings

The number of AWS IoT things that successfully completed the job.

numberOfFailedThings

The number of AWS IoT things that failed to complete the job.

numberOfRejectedThings

The number of AWS IoT things that rejected the job.

numberOfQueuedThings

The number of AWS IoT things that are awaiting execution of the job.

numberOfInProgressThings

The number of AWS IoT things that are currently executing the job.

numberOfRemovedThings

The number of AWS IoT things that are no longer scheduled to execute the job because they have been deleted or removed from the group that was a target of the job.

presignedUrlConfig

Configuration information for presigned Amazon S3 URLs.

expiresInSec

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

roleArn

The ARN of an IAM role that grants permission to download files from an Amazon S3 bucket. The role must also grant permission for AWS IoT to download the files. For more information about how to create and configure the role, see Create Jobs.

jobExecutionRolloutConfig

Allows you to create a staged rollout of a job.

maximumPerMinute

The maximum number of things (devices) to which the job will be sent for execution, per minute.

JobSummary

JobSummary data typesyntax (2)description (2)
JobSummary data type

The JobSummary object contains a job summary.

syntax (2)
{ "jobArn": "string", "jobId": "string", "status": "IN_PROGRESS|CANCELED|COMPLETED", "description": "string", "targetSelection": "CONTINUOUS|SNAPSHOT", "thingGroupId": "string", "createdAt": timestamp, "lastUpdatedAt": timestamp, "completedAt": timestamp }
description (2)
jobArn

An ARN that identifies the job.

jobId

The unique identifier you assigned to this job when it was created.

status

The job status. Can be one of IN_PROGRESS, CANCELED, or COMPLETED.

targetSelection

Specifies whether the job continues to run (CONTINUOUS) or is complete after all those things specified as targets have completed the job (SNAPSHOT). If CONTINUOUS, the job might also be run on a thing when a change is detected in a target. For example, a job runs 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.

thingGroupId

The ID of the thing group.

createdAt

The UNIX timestamp for when the job was created.

lastUpdatedAt

The UNIX timestamp for when the job was last updated.

completedAt

The UNIX timestamp for when the job was completed.

JobExecution

JobExection data typesyntax (3)description (3)
JobExection data type

The JobExecution object represents the execution of a job on a particular device.

syntax (3)
{ "jobId": "string", "executionNumber": 1234567890, "thingArn": "string", "queuedAt": timestamp, "lastUpdatedAt": timestamp, "startedAt": timestamp, "status": "QUEUED|IN_PROGRESS|FAILED|SUCCESS|CANCELED|REJECTED|REMOVED", "statusDetails": { "detailsMap": { "string": "string" ... }, "status": "string" }, }
description (3)
jobId

The unique identifier you assigned to this job when it was created.

executionNumber

A number that identifies this job execution on this particular device. It can be used later in commands that return or update job execution information.

thingArn

The AWS IoT thing ARN.

queuedAt

The time, in milliseconds since the epoch, when the job execution was queued.

lastUpdatedAt

The time, in milliseconds since the epoch, when the job execution was last updated.

startedAt

The time, in milliseconds since the epoch, when the job execution was started.

status

The status of the job execution. Can be one of "QUEUED", "IN_PROGRESS", "FAILED", "SUCCESS", "CANCELED", "REJECTED", or "REMOVED".

statusDetails

A collection of name/value pairs that describe the status of the job execution.

JobExecutionSummary

JobExecutionSummary data typesyntax (4)description (4)
JobExecutionSummary data type

The JobExecutionSummary object contains job execution summary information:

syntax (4)
{ "executionNumber": 1234567890, "queuedAt": timestamp, "lastUpdatedAt": timestamp, "startedAt": timestamp, "status": "QUEUED|IN_PROGRESS|FAILED|SUCCESS|CANCELED|REJECTED|REMOVED" }
description (4)
executionNumber

A number that identifies a particular job execution on a particular device. It can be used later in commands that return or update job execution information.

queuedAt

The time, in milliseconds since the epoch, when the job execution was queued.

lastUpdatedAt

The time, in milliseconds since the epoch, when the job execution was last updated.

startAt

The time, in milliseconds since the epoch, when the job execution was started.

status

The status of the job execution: QUEUED, IN_PROGRESS, FAILED, SUCCESS, CANCELED, REJECTED, or REMOVED.

JobExecutionSummaryForJob

JobExecutionSummaryForJob data typesyntax (5)description (5)
JobExecutionSummaryForJob data type

The JobExecutionSummaryForJob object contains a summary of information about job executions for a specific job.

syntax (5)
{ "executionSummary": [ { "thingArn": "string", "jobExecutionSummary": { JobExecutionSummary } } ... ] }
description (5)
thingArn

The AWS IoT thing ARN.

jobExecutionSummary

An JobExecutionSummary object.

JobExecutionSummaryForThing

JobExecutionSummaryForThing data typesyntax (6)description (6)
JobExecutionSummaryForThing data type

The JobExecutionSummaryForThing object contains a summary of information about a job execution on a specific thing.

syntax (6)
{ "jobId": "string", "jobExecutionSummary": { JobExecutionSummary } }
description (6)
jobId

The unique identifier you assigned to this job when it was created.

jobExecutionSummary

A JobExecutionSummary object.

Job Management and Control HTTPS Commands

The following commands are available for management and control applications over the HTTPS protocol.

AssociateTargetsWithJob

AssociateTargetsWithJob commandHTTPS (1)CLI (1)MQTT (1)
AssociateTargetsWithJob command

Associates a group with a continuous job. For more information, see CreateJob. The following criteria must be met:

  • The job must have been created with the targetSelection field set to "CONTINUOUS".

  • The job status must currently be "IN_PROGRESS".

  • The total number of targets associated with a job must not exceed 100.

HTTPS (1)

Request:

POST /jobs/jobId/targets { "targets": [ "string" ], "comment": "string" }
jobId

The unique identifier you assigned to this job when it was created.

targets

A list of thing group ARNs that define the targets of the job.

comment

Optional. A comment string that describes why the job was associated with the targets.

Response:

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

An ARN identifying the job.

jobId

The unique identifier you assigned to this job when it was created.

description

A short text description of the job.

CLI (1)

Synopsis:

aws iot associate-targets-with-job \ --targets <value> \ --job-id <value> \ [--comment <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "targets": [ "string" ], "jobId": "string", "comment": "string" }

cli-input-json fields:

Name

Type

Description

targets

list

member: TargetArn

A list of thing group ARNs that define the targets of the job.

TargetArn

string

jobId

string

length max:64 min:1

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

The unique identifier you assigned to this job when it was created.

comment

string

length max:2028

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

An optional comment string describing why the job was associated with the targets.

Output:

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

cli output fields:

Name

Type

Description

jobArn

string

An ARN identifying the job.

jobId

string

length max:64 min:1

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

The unique identifier you assigned to this job when it was created.

description

string

length max:2028

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

A short text description of the job.

MQTT (1)

Not available.

CancelJob

CancelJob commandHTTPS (2)CLI (2)MQTT (2)
CancelJob command

Cancels a job.

HTTPS (2)

Request:

PUT /jobs/jobId/cancel { "comment": "string" }
jobId

The unique identifier you assigned to this job when it was created.

comment

[Optional] A comment string describing why the job was canceled.

Response:

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

The job ARN.

jobId

The unique identifier you assigned to this job when it was created.

description

A short text description of the job.

CLI (2)

Synopsis:

aws iot cancel-job \ --job-id <value> \ [--comment <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "jobId": "string", "comment": "string" }

cli-input-json fields:

Name

Type

Description

jobId

string

length max:64 min:1

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

The unique identifier you assigned to this job when it was created.

comment

string

length max:2028

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

An optional comment string describing why the job was canceled.

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 when it was created.

description

string

length max:2028

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

A short text description of the job.

MQTT (2)

Not available.

CreateJob

CreateJob commandHTTPS (3)CLI (3)MQTT (3)
CreateJob command

Creates a job. You can provide the job document as a link to a file in an Amazon S3 bucket (documentSource parameter) or in the body of the request (document parameter).

A job can be made continuous by setting the optional targetSelection parameter to "CONTINUOUS". (The default is "SNAPSHOT".) A continuous job can be used to onboard or upgrade devices as they are added to a group because it continues to run and is executed on newly added things, even after the things in the group at the time the job was created have completed the job.

The following validations are performed on arguments to the CreateJob API:

  • The targets argument must be a list of valid thing or thing group ARNs. All things and thing groups must be in your AWS account.

  • The documentSource argument must be a valid Amazon S3 URL to a job document. Amazon S3 URLs are of the form: https://s3.amazonaws.com/bucketName/objectName.

  • The document stored in the URL specified by the documentSource argument must be a UTF-8 encoded JSON document.

  • The size of a job document is limited to 32 KB due to the limit on the size of an MQTT message(128 KB) and encryption.

  • The jobId must be unique within your AWS account.

HTTPS (3)

Request:

PUT /jobs/jobId { "targets": [ "string" ], "document": "string", "documentSource": "string", "description": "string", "presignedUrlConfigData": { "roleArn": "string", "expiresInSec": "integer" }, "targetSelection": "CONTINUOUS|SNAPSHOT", "jobExecutionsRolloutConfig": { "maximumPerMinute": "integer" } }
jobId

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

targets

A list of thing or thing group ARNs that defines the targets of the job.

document

Optional. The job document.

documentSource

Optional. An Amazon S3 link to the job document.

description

Optional. A short text description of the job.

presignedUrlConfigData

Optional. Configuration information for presigned Amazon S3 URLs.

roleArn

The ARN of the IAM role that contains permissions to access the Amazon S3 bucket. This is the bucket that contains the data that devices download with the presigned Amazon S3 URLs. This role must also grant AWS IoT permission to assume the role. For more information, see Create Jobs.

expiresInSec

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

targetSelection

Optional. Specifies whether the job continues to run (CONTINUOUS) or is complete after all those things specified as targets have completed the job (SNAPSHOT). If CONTINUOUS, the job might also be scheduled to run on a thing when a change is detected in a target. For example, a job is scheduled to 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.

jobExecutionRolloutConfig

Optional. Allows you to create a staged rollout of a job.

maximumPerMinute

The maximum number of things on which the job is sent for execution, per minute. Valid values are 1 to 1000. If not specified, the default is 1000. The actual number of things that receive the job might be less during any particular minute interval (due to system latency), but will not be more than the specified value.

Response:

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

The ARN of the job.

jobId

The unique identifier you assigned to this job.

description

An optional short text description of the job.

CLI (3)

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.

MQTT (3)

Not available.

DescribeJob

DescribeJob commandHTTPS (4)CLI (4)MQTT (4)
DescribeJob command

Gets the details of the specified job.

HTTPS (4)

Request:

GET /jobs/jobId
jobId

The unique identifier you assigned to this job when it was created.

Response:

{ "documentSource": "string", "job": Job }
documentSource

An Amazon S3 link to the job document.

job

A Job object.

CLI (4)

Synopsis:

aws iot describe-job \ --job-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "jobId": "string" }

cli-input-json fields:

Name

Type

Description

jobId

string

length max:64 min:1

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

The unique identifier you assigned to this job when it was created.

Output:

{ "documentSource": "string", "job": { "jobArn": "string", "jobId": "string", "targetSelection": "string", "status": "string", "comment": "string", "targets": [ "string" ], "description": "string", "presignedUrlConfig": { "roleArn": "string", "expiresInSec": "long" }, "jobExecutionsRolloutConfig": { "maximumPerMinute": "integer" }, "createdAt": "timestamp", "lastUpdatedAt": "timestamp", "completedAt": "timestamp", "jobProcessDetails": { "processingTargets": [ "string" ], "numberOfCanceledThings": "integer", "numberOfSucceededThings": "integer", "numberOfFailedThings": "integer", "numberOfRejectedThings": "integer", "numberOfQueuedThings": "integer", "numberOfInProgressThings": "integer", "numberOfRemovedThings": "integer" }, "documentParameters": { "string": "string" } } }

cli output fields:

Name

Type

Description

documentSource

string

length max:1350 min:1

An S3 link to the job document.

job

Job

Information about the job.

jobArn

string

An ARN identifying the job with format "arn:aws:iot:region:account:job/jobId".

jobId

string

length max:64 min:1

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

The unique identifier you assigned to this job when it was created.

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 device when the thing representing the device is added to a target group, even after the job was completed by all things originally in the group.

status

string

enum: IN_PROGRESS | CANCELED | COMPLETED

java class: ccom.amazonaws.iot.laser.common.JobStatus

The status of the job, one of IN_PROGRESS, CANCELED, or COMPLETED.

comment

string

length max:2028

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

If the job was updated, describes the reason for the update.

targets

list

member: TargetArn

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

TargetArn

string

description

string

length max:2028

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

A short text description of the job.

presignedUrlConfig

PresignedUrlConfig

Configuration 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.

jobExecutionsRolloutConfig

JobExecutionsRolloutConfig

Allows you to create a staged rollout of a 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.

createdAt

timestamp

The time, in milliseconds since the epoch, when the job was created.

lastUpdatedAt

timestamp

The time, in milliseconds since the epoch, when the job was last updated.

completedAt

timestamp

The time, in milliseconds since the epoch, when the job was completed.

jobProcessDetails

JobProcessDetails

Details about the job process.

processingTargets

list

member: ProcessingTargetName

java class: java.util.List

The devices on which the job is executing.

ProcessingTargetName

string

numberOfCanceledThings

integer

java class: java.lang.Integer

The number of things that cancelled the job.

numberOfSucceededThings

integer

java class: java.lang.Integer

The number of things which successfully completed the job.

numberOfFailedThings

integer

java class: java.lang.Integer

The number of things that failed executing the job.

numberOfRejectedThings

integer

java class: java.lang.Integer

The number of things that rejected the job.

numberOfQueuedThings

integer

java class: java.lang.Integer

The number of things that are awaiting execution of the job.

numberOfInProgressThings

integer

java class: java.lang.Integer

The number of things currently executing the job.

numberOfRemovedThings

integer

java class: java.lang.Integer

The number of things that are no longer scheduled to execute the job because they have been deleted or have been removed from the group that was a target of the job.

documentParameters

map

key: ParameterKey

value: ParameterValue

The parameters specified 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}]+

MQTT (4)

Not available.

DescribeJobExecution

DescribeJobExecution commandHTTPS (5)CLI (5)MQTT (5)
DescribeJobExecution command

Gets details of a job execution. The job's execution status must be SUCCEEDED or FAILED.

HTTPS (5)

Request:

GET /things/thingName/jobs/jobId?executionNumber=executionNumber
jobId

The unique identifier you assigned to this job when it was created.

thingName

The thing name associated with the device the job execution is running on.

executionNumber

Optional. A number that is used to specify a particular job execution on a particular device. (See JobExecution.) If not specified, the latest job execution is returned.

Response:

{ "execution": { JobExecution } }
execution

A JobExecution object.

CLI (5)

Synopsis:

aws iot describe-job-execution \ --job-id <value> \ --thing-name <value> \ [--execution-number <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "jobId": "string", "thingName": "string", "executionNumber": "long" }

cli-input-json fields:

Name

Type

Description

jobId

string

length max:64 min:1

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

The unique identifier you assigned to this job when it was created.

thingName

string

length max:128 min:1

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

The name of the thing on which the job execution is running.

executionNumber

long

java class: java.lang.Long

A string (consisting of the digits "0" through "9" which is used to specify a particular job execution on a particular device.

Output:

{ "execution": { "jobId": "string", "status": "string", "statusDetails": { "detailsMap": { "string": "string" } }, "thingArn": "string", "queuedAt": "timestamp", "startedAt": "timestamp", "lastUpdatedAt": "timestamp", "executionNumber": "long" } }

cli output fields:

Name

Type

Description

execution

JobExecution

Information about the job execution.

jobId

string

length max:64 min:1

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

The unique identifier you assigned to the job when it was created.

status

string

enum: QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | REJECTED | REMOVED | CANCELED

java class: com.amazonaws.iot.laser.common.JobExecutionStatus

The status of the job execution (IN_PROGRESS, QUEUED, FAILED, SUCCESS, CANCELED, or REJECTED).

statusDetails

JobExecutionStatusDetails

A collection of name/value pairs that describe the status of the job execution.

detailsMap

map

key: DetailsKey

value: DetailsValue

The job execution status.

DetailsKey

string

length max:128 min:1

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

DetailsValue

string

length max:1024 min:1

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

thingArn

string

The ARN of the thing on which the job execution is running.

queuedAt

timestamp

The time, in milliseconds since the epoch, when the job execution was queued.

startedAt

timestamp

The time, in milliseconds since the epoch, when the job execution started.

lastUpdatedAt

timestamp

The time, in milliseconds since the epoch, when the job execution was last updated.

executionNumber

long

java class: java.lang.Long

A string (consisting of the digits "0" through "9") which identifies this particular job execution on this particular device. It can be used in commands which return or update job execution information.

MQTT (5)

Not available.

GetJobDocument

GetJobDocument commandHTTPS (6)CLI (6)MQTT (6)
GetJobDocument command

Gets the job document for a job.

Note

Placeholder URLs are not replaced with presigned Amazon S3 URLs in the document returned. Presigned URLs are generated only when Jobs receives a request over MQTT.

HTTPS (6)

Request:

GET /jobs/jobId/job-document
jobId

The unique identifier you assigned to this job when it was created.

Response:

{ "document": "string" }
document

The job document content.

CLI (6)

Synopsis:

aws iot get-job-document \ --job-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "jobId": "string" }

cli-input-json fields:

Name

Type

Description

jobId

string

length max:64 min:1

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

The unique identifier you assigned to this job when it was created.

Output:

{ "document": "string" }

cli output fields:

Name

Type

Description

document

string

length max:32768

The job document content.

MQTT (6)

Not available.

ListJobExecutionsForJob

ListExecutionsForJob commandHTTPS (7)CLI (7)MQTT (7)
ListExecutionsForJob command

Gets a list of job executions for a job.

HTTPS (7)

Request:

GET /jobs/jobId/things?status=status&maxResults=maxResults&nextToken=nextToken
jobId

The unique identifier you assigned to this job when it was created.

status

Optional. A filter that lets you search for jobs that have the specified status: QUEUED, IN_PROGRESS, SUCCESS, FAILED, REJECTED, REMOVED, or CANCELED.

maxResults

Optional. The maximum number of results to be returned per request.

nextToken

Optional. The token to retrieve the next set of results.

Response:

{ "executionSummaries": [ JobExecutionSummary ... ] }
executionSummaries

A list of JobExecutionSummary objects associated with the specified job ID.

CLI (7)

Synopsis:

aws iot list-job-executions-for-job \ --job-id <value> \ [--status <value>] \ [--max-results <value>] \ [--next-token <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "jobId": "string", "status": "string", "maxResults": "integer", "nextToken": "string" }

cli-input-json fields:

Name

Type

Description

jobId

string

length max:64 min:1

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

The unique identifier you assigned to this job when it was created.

status

string

enum: QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | REJECTED | REMOVED | CANCELED

java class: com.amazonaws.iot.laser.common.JobExecutionStatus

The status of the job.

maxResults

integer

java class: java.lang.Integer

range- max:250 min:1

The maximum number of results to be returned per request.

nextToken

string

The token to retrieve the next set of results.

Output:

{ "executionSummaries": [ { "thingArn": "string", "jobExecutionSummary": { "status": "string", "queuedAt": "timestamp", "startedAt": "timestamp", "lastUpdatedAt": "timestamp", "executionNumber": "long" } } ], "nextToken": "string" }

cli output fields:

Name

Type

Description

executionSummaries

list

member: JobExecutionSummaryForJob

java class: java.util.List

A list of job execution summaries.

JobExecutionSummaryForJob

JobExecutionSummaryForJob

thingArn

string

The ARN of the thing on which the job execution is running.

jobExecutionSummary

JobExecutionSummary

Contains a subset of information about a job execution.

status

string

enum: QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | REJECTED | REMOVED | CANCELED

java class: com.amazonaws.iot.laser.common.JobExecutionStatus

The status of the job execution.

queuedAt

timestamp

The time, in milliseconds since the epoch, when the job execution was queued.

startedAt

timestamp

The time, in milliseconds since the epoch, when the job execution started.

lastUpdatedAt

timestamp

The time, in milliseconds since the epoch, when the job execution was last updated.

executionNumber

long

java class: java.lang.Long

A string (consisting of the digits "0" through "9") which identifies this particular job execution on this particular device. It can be used later in commands which return or update job execution information.

nextToken

string

The token for the next set of results, or null if there are no additional results.

MQTT (7)

Not available.

ListJobExecutionsForThing

ListJobExecutionsForThing commandHTTPS (8)CLI (8)MQTT (8)
ListJobExecutionsForThing command

Gets a list of job executions for a thing.

HTTPS (8)

Request:

GET /things/thingName/jobs?status=status&maxResults=maxResults&nextToken=nextToken
thingName

The name of the thing for which JobExecutions will be listed.

status

An optional filter that lets you search for jobs that have the specified status: QUEUED, IN_PROGRESS, SUCCESS, FAILED, REJECTED, REMOVED, or CANCELED.

maxResults

The maximum number of results to be returned per request.

nextToken

The token for the next set of results, or null if there are no additional results.

Response:

{ "executionSummaries": [ JobExecutionSummary ... ] }
executionSummaries

A list of the JobExecutionSummary objects for the job executions associated with the specified thing.

CLI (8)

Synopsis:

aws iot list-job-executions-for-thing \ --thing-name <value> \ [--status <value>] \ [--max-results <value>] \ [--next-token <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "thingName": "string", "status": "string", "maxResults": "integer", "nextToken": "string" }

cli-input-json fields:

Name

Type

Description

thingName

string

length max:128 min:1

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

The thing name.

status

string

enum: QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | REJECTED | REMOVED | CANCELED

java class: com.amazonaws.iot.laser.common.JobExecutionStatus

An optional filter that lets you search for jobs that have the specified status.

maxResults

integer

java class: java.lang.Integer

range- max:250 min:1

The maximum number of results to be returned per request.

nextToken

string

The token to retrieve the next set of results.

Output:

{ "executionSummaries": [ { "jobId": "string", "jobExecutionSummary": { "status": "string", "queuedAt": "timestamp", "startedAt": "timestamp", "lastUpdatedAt": "timestamp", "executionNumber": "long" } } ], "nextToken": "string" }

cli output fields:

Name

Type

Description

executionSummaries

list

member: JobExecutionSummaryForThing

java class: java.util.List

A list of job execution summaries.

JobExecutionSummaryForThing

JobExecutionSummaryForThing

jobId

string

length max:64 min:1

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

The unique identifier you assigned to this job when it was created.

jobExecutionSummary

JobExecutionSummary

Contains a subset of information about a job execution.

status

string

enum: QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | REJECTED | REMOVED | CANCELED

java class: com.amazonaws.iot.laser.common.JobExecutionStatus

The status of the job execution.

queuedAt

timestamp

The time, in milliseconds since the epoch, when the job execution was queued.

startedAt

timestamp

The time, in milliseconds since the epoch, when the job execution started.

lastUpdatedAt

timestamp

The time, in milliseconds since the epoch, when the job execution was last updated.

executionNumber

long

java class: java.lang.Long

A string (consisting of the digits "0" through "9") which identifies this particular job execution on this particular device. It can be used later in commands which return or update job execution information.

nextToken

string

The token for the next set of results, or null if there are no additional results.

MQTT (8)

Not available.

ListJobs

ListJobs commandHTTPS (9)CLI (9)MQTT (9)
ListJobs command

Gets a list of the jobs in your AWS account.

HTTPS (9)

Request:

GET /jobs?status=status&targetSelection=targetSelection&thingGroupName=thingGroupName&thingGroupId=thingGroupId&maxResults=maxResults&nextToken=nextToken
status

Optional. A filter that lets you search for jobs that have the specified status: IN_PROGRESS, CANCELED, or COMPLETED.

targetSelection

Optional. A filter that lets you search for jobs that have the specified targetSelection value: CONTINUOUS or SNAPSHOT.

thingGroupName

Optional. A filter that lets you search for jobs that have the specified thing group name as a target.

thingGroupId

Optional. A filter that lets you search for jobs that have the specified thing group ID as a target.

maxResults

Optional. The maximum number of results to be returned per request.

nextToken

Optional. The token to retrieve the next set of results.

Response:

{ "jobs": [ JobSummary ... ], }
jobs

A list of JobSummary objects, one for each job in your AWS account that matches the specified filtering criteria.

CLI (9)

Synopsis:

aws iot list-jobs \ [--status <value>] \ [--target-selection <value>] \ [--max-results <value>] \ [--next-token <value>] \ [--thing-group-name <value>] \ [--thing-group-id <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "status": "string", "targetSelection": "string", "maxResults": "integer", "nextToken": "string", "thingGroupName": "string", "thingGroupId": "string" }

cli-input-json fields:

Name

Type

Description

status

string

enum: IN_PROGRESS | CANCELED | COMPLETED

java class: ccom.amazonaws.iot.laser.common.JobStatus

An optional filter that lets you search for jobs that have the specified status.

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.

maxResults

integer

java class: java.lang.Integer

range- max:250 min:1

The maximum number of results to return per request.

nextToken

string

The token to retrieve the next set of results.

thingGroupName

string

length max:128 min:1

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

A filter that limits the returned jobs to those for the specified group.

thingGroupId

string

length max:128 min:1

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

A filter that limits the returned jobs to those for the specified group.

Output:

{ "jobs": [ { "jobArn": "string", "jobId": "string", "thingGroupId": "string", "targetSelection": "string", "status": "string", "createdAt": "timestamp", "lastUpdatedAt": "timestamp", "completedAt": "timestamp" } ], "nextToken": "string" }

cli output fields:

Name

Type

Description

jobs

list

member: JobSummary

java class: java.util.List

A list of jobs.

JobSummary

JobSummary

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 when it was created.

thingGroupId

string

length max:128 min:1

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

The ID of the thing group.

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.

status

string

enum: IN_PROGRESS | CANCELED | COMPLETED

java class: ccom.amazonaws.iot.laser.common.JobStatus

The job summary status.

createdAt

timestamp

The time, in milliseconds since the epoch, when the job was created.

lastUpdatedAt

timestamp

The time, in milliseconds since the epoch, when the job was last updated.

completedAt

timestamp

The time, in milliseconds since the epoch, when the job completed.

nextToken

string

The token for the next set of results, or null if there are no additional results.

MQTT (9)

Not available.

Jobs Device MQTT and HTTPS APIs

Device MQTT and HTTPS Data Types

The following data types are used to communicate with Jobs over the MQTT and HTTPS protocols.

JobExecution

JobExecution data typesyntax (7)description (7)
JobExecution data type

Contains data about a job execution.

syntax (7)
{ "jobId" : "string", "thingName" : "string", "jobDocument" : "string", "status": "QUEUED|IN_PROGRESS|FAILED|SUCCESS|CANCELED|REJECTED|REMOVED", "statusDetails": { "string": "string" } "queuedAt" : "timestamp", "startedAt" : "timestamp", "lastUpdatedAt" : "timestamp", "versionNumber" : "number", "executionNumber": "long" }
description (7)
jobId

The unique identifier you assigned to this job when it was created.

thingName

The name of the thing that is executing the job.

jobDocument

The content of the job document.

status

The status of the job execution. Can be one of: "QUEUED", "IN_PROGRESS", "FAILED", "SUCCESS", "CANCELED", "REJECTED", or "REMOVED".

statusDetails

A collection of name/value pairs that describe the status of the job execution.

queuedAt

The time, in milliseconds since the epoch, when the job execution was enqueued.

startedAt

The time, in milliseconds since the epoch, when the job execution was started.

lastUpdatedAt

The time, in milliseconds since the epoch, when the job execution was last updated.

versionNumber

The version of the job execution. Job execution versions are incremented each time they are updated by a device.

executionNumber

A number that identifies a particular job execution on a particular device. It can be used later in commands that return or update job execution information.

JobExecutionState

JobExecutionState data typesyntax (8)description (8)
JobExecutionState data type

Contains data about the state of a job execution.

syntax (8)
{ "status": "QUEUED|IN_PROGRESS|FAILED|SUCCESS|CANCELED|REJECTED|REMOVED", "statusDetails": { "string": "string" ... } "versionNumber": "number" }
description (8)
status

The status of the job execution. Can be one of: "QUEUED", "IN_PROGRESS", "FAILED", "SUCCESS", "CANCELED", "REJECTED", or "REMOVED".

statusDetails

A collection of name/value pairs that describe the status of the job execution.

versionNumber

The version of the job execution. Job execution versions are incremented each time they are updated by a device.

JobExecutionSummary

JobExecutionSummary data typesyntax (9)description (9)
JobExecutionSummary data type

Contains a subset of information about a job execution.

syntax (9)
{ "jobId": "string", "queuedAt": timestamp, "startedAt": timestamp, "lastUpdatedAt": timestamp, "versionNumber": "number", "executionNumber": "long" }
description (9)
jobId

The unique identifier you assigned to this job when it was created.

queuedAt

The time, in milliseconds since the epoch, when the job execution was enqueued.

startedAt

The time, in milliseconds since the epoch, when the job execution started.

lastUpdatedAt

The time, in milliseconds since the epoch, when the job execution was last updated.

versionNumber

The version of the job execution. Job execution versions are incremented each time AWS IoT Jobs receives an update from a device.

executionNumber

A number that identifies a particular job execution on a particular device.

ErrorResponse

ErrorRepsonse data typesyntax (10)description (10)
ErrorRepsonse data type

Contains information about an error that occurred during a Jobs operation.

syntax (10)
{ "code": "ErrorCode", "message": "string", "clientToken": "string", "timestamp": timestamp, "executionState": JobExecutionState }
description (10)
code

ErrorCode can be set to:

InvalidTopic

The request was sent to a topic in the Jobs namespace that does not map to any API.

InvalidJson

The contents of the request could not be interpreted as valid UTF-8-encoded JSON.

InvalidRequest

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.

InvalidStateTransition

An update attempted to change the job execution to a state that is invalid because of the job execution's current state (for example, an attempt to change a request in state SUCCESS to state IN_PROGRESS). In this case, the body of the error message also contains the executionState field.

ResourceNotFound

The JobExecution specified by the request topic does not exist.

VersionMismatch

The expected version specified in the request does not match the version of the job execution in Jobs. In this case, the body of the error message also contains the executionState field.

InternalError

There was an internal error processing the request.

RequestThrottled

The request was throttled.

TerminalStateReached

Occurs when a command to describe a job is performed on a job that is in a terminal state.

message

An error message string.

clientToken

An arbitrary string used to correlate a request with its reply.

timestamp

The time, in milliseconds since the epoch.

executionState

A JobExecutionState object. This field is included only when the code field has the value InvalidStateTransition or VersionMismatch. This makes it unnecessary in these cases to perform a separate DescribeJobExecution request to obtain the current job execution status data.

Device Commands

The following commands are available over the MQTT and HTTPS protocols.

GetPendingJobExecutions

GetPendingJobExecutions commandMQTT (11)HTTPS (11)CLI (11)
GetPendingJobExecutions command

Gets the list of all jobs for a thing that are not in a terminal status.

MQTT (11)

To invoke this API, publish a message on $aws/things/thingName/jobs/get.

Request payload:

{ "clientToken": "string" }
clientToken

Optional. A client token used to correlate requests and responses. Enter an arbitrary value here and it will be reflected in the response.

To receive the response, subscribe to:

  • $aws/things/thingName/jobs/get/accepted ...and...

  • $aws/things/thingName/jobs/get/rejected ...or...

  • $aws/things/thingName/jobs/get/# ...for both...

Response payload:

{ "inProgressJobs" : [ JobExecutionSummary ... ], "queuedJobs" : [ JobExecutionSummary ... ], "timestamp" : 1489096425069, "clientToken" : "client-001" }
inPrograssJobs

A list of JobExecutionSummary objects with status IN_PROGRESS.

queuedJobs

A list of JobExecutionSummary objects with status QUEUED.

clientToken

A client token used to correlate requests and responses.

timestamp

The time, in milliseconds since the epoch, when the message was sent.

HTTPS (11)

Request:

GET /things/thingName/jobs
thingName

The name of the thing associated with the device.

Response:

{ "inProgressJobs" : [ JobExecutionSummary ... ], "queuedJobs" : [ JobExecutionSummary ... ] }
inPrograssJobs

A list of JobExecutionSummary objects.

queuedJobs

A list of JobExecutionSummary objects.

CLI (11)

Synopsis:

aws iot-jobs-data get-pending-job-executions \ --thing-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "thingName": "string" }

cli-input-json fields:

Name

Type

Description

thingName

string

length max:128 min:1

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

The name of the thing that is executing the job.

Output:

{ "inProgressJobs": [ { "jobId": "string", "queuedAt": "long", "startedAt": "long", "lastUpdatedAt": "long", "versionNumber": "long", "executionNumber": "long" } ], "queuedJobs": [ { "jobId": "string", "queuedAt": "long", "startedAt": "long", "lastUpdatedAt": "long", "versionNumber": "long", "executionNumber": "long" } ] }

cli output fields:

Name

Type

Description

inProgressJobs

list

member: JobExecutionSummary

java class: java.util.List

A list of JobExecutionSummary objects with status IN_PROGRESS.

JobExecutionSummary

JobExecutionSummary

jobId

string

length max:64 min:1

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

The unique identifier you assigned to this job when it was created.

queuedAt

long

The time, in milliseconds since the epoch, when the job execution was enqueued.

startedAt

long

java class: java.lang.Long

The time, in milliseconds since the epoch, when the job execution started.

lastUpdatedAt

long

The time, in milliseconds since the epoch, when the job execution was last updated.

versionNumber

long

The version of the job execution. Job execution versions are incremented each time AWS IoT Jobs receives an update from a device.

executionNumber

long

java class: java.lang.Long

A number that identifies a particular job execution on a particular device.

queuedJobs

list

member: JobExecutionSummary

java class: java.util.List

A list of JobExecutionSummary objects with status QUEUED.

JobExecutionSummary

JobExecutionSummary

jobId

string

length max:64 min:1

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

The unique identifier you assigned to this job when it was created.

queuedAt

long

The time, in milliseconds since the epoch, when the job execution was enqueued.

startedAt

long

java class: java.lang.Long

The time, in milliseconds since the epoch, when the job execution started.

lastUpdatedAt

long

The time, in milliseconds since the epoch, when the job execution was last updated.

versionNumber

long

The version of the job execution. Job execution versions are incremented each time AWS IoT Jobs receives an update from a device.

executionNumber

long

java class: java.lang.Long

A number that identifies a particular job execution on a particular device.

StartNextPendingJobExecution

StartNextPendingJobExecution commandMQTT (12)HTTPS (12)CLI (12)
StartNextPendingJobExecution command

Gets and starts the next pending (status IN_PROGRESS or QUEUED) job execution for a thing.

  • Any job executions with status IN_PROGRESS are returned first.

  • Job executions are returned in the order in which they were created.

  • If the next pending job execution is QUEUED, its state is changed to IN_PROGRESS and the job execution's status details are set as specified.

  • If the next pending job execution is already IN_PROGRESS, its status details are not changed.

  • If no job executions are pending, the response does not include the execution field.

MQTT (12)

To invoke this API, publish a message on: $aws/things/thingName/jobs/start-next.

Request payload:

{ "statusDetails": { "string": "job-execution-state" ... }, "clientToken": "string" }
statusDetails

A collection of name/value pairs that describe the status of the job execution. If not specified, the statusDetails are unchanged.

clientToken

A client token used to correlate requests and responses. Enter an arbitrary value here and it will be reflected in the response.

To receive the response, subscribe to:

  • $aws/things/thingName/jobs/start-next/accepted ...and...

  • $aws/things/thingName/jobs/start-next/rejected ...or...

  • $aws/things/thingName/jobs/start-next/# ...for both...

Response payload:

{ "execution" : JobExecutionData, "timestamp" : timestamp, "clientToken" : "string" }
execution

A JobExecution object. For example:

{ "execution" : { "jobId" : "022", "thingName" : "MyThing", "jobDocument" : "< contents of job document >", "status" : "IN_PROGRESS", "queuedAt" : 1489096123309, "lastUpdatedAt" : 1489096123309, "versionNumber" : 1, "executionNumber" : 1234567890 }, "clientToken" : "client-1", "timestamp" : 1489088524284, }
timestamp

The time, in milliseconds since the epoch, when the message was sent to the device.

clientToken

A client token used to correlate requests and responses.

HTTPS (12)

Request:

PUT /things/thingName/jobs/$next { "statusDetails": { "string": "string" ... } }
thingName

The name of the thing associated with the device.

statusDetails

A collection of name/value pairs that describe the status of the job execution. If not specified, the statusDetails are unchanged.

Response:

{ "execution" : JobExecution }
execution

A JobExecution object. For example:

{ "execution" : { "jobId" : "022", "thingName" : "MyThing", "jobDocument" : "< contents of job document >", "status" : "IN_PROGRESS", "queuedAt" : 1489096123309, "lastUpdatedAt" : 1489096123309, "versionNumber" : 1, "executionNumber" : 1234567890 }, "clientToken" : "client-1", "timestamp" : 1489088524284, }
CLI (12)

Synopsis:

aws iot-jobs-data start-next-pending-job-execution \ --thing-name <value> \ [--status-details <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "thingName": "string", "statusDetails": { "string": "string" } }

cli-input-json fields:

Name

Type

Description

thingName

string

length max:128 min:1

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

The name of the thing associated with the device.

statusDetails

map

key: DetailsKey

value: DetailsValue

A collection of name/value pairs that describe the status of the job execution. If not specified, the statusDetails are unchanged.

DetailsKey

string

length max:128 min:1

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

DetailsValue

string

length max:1024 min:1

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

Output:

{ "execution": { "jobId": "string", "thingName": "string", "status": "string", "statusDetails": { "string": "string" }, "queuedAt": "long", "startedAt": "long", "lastUpdatedAt": "long", "versionNumber": "long", "executionNumber": "long", "jobDocument": "string" } }

cli output fields:

Name

Type

Description

execution

JobExecution

A JobExecution object.

jobId

string

length max:64 min:1

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

The unique identifier you assigned to this job when it was created.

thingName

string

length max:128 min:1

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

The name of the thing that is executing the job.

status

string

enum: QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | REJECTED | REMOVED | CANCELED

java class: com.amazonaws.iot.laser.common.JobExecutionStatus

The status of the job execution. Can be one of: "QUEUED", "IN_PROGRESS", "FAILED", "SUCCESS", "CANCELED", "REJECTED", or "REMOVED".

statusDetails

map

key: DetailsKey

value: DetailsValue

A collection of name/value pairs that describe the status of the job execution.

DetailsKey

string

length max:128 min:1

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

DetailsValue

string

length max:1024 min:1

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

queuedAt

long

The time, in milliseconds since the epoch, when the job execution was enqueued.

startedAt

long

java class: java.lang.Long

The time, in milliseconds since the epoch, when the job execution was started.

lastUpdatedAt

long

The time, in milliseconds since the epoch, when the job execution was last updated.

versionNumber

long

The version of the job execution. Job execution versions are incremented each time they are updated by a device.

executionNumber

long

java class: java.lang.Long

A number that identifies a particular job execution on a particular device. It can be used later in commands that return or update job execution information.

jobDocument

string

length max:32768

The content of the job document.

DescribeJobExecution

DescribeJobExecution commandMQTT (13)HTTPS (13)CLI (13)
DescribeJobExecution command

Gets detailed information about a job execution.

You can set the jobId to $next to return the next pending (status IN_PROGRESS or QUEUED) job execution for a thing.

MQTT (13)

To invoke this API, publish a message on $aws/things/thingName/jobs/jobId/get.

Request payload:

{ "executionNumber": "long", "includeJobDocument": "boolean", "clientToken": "string" }
thingName

The name of the thing associated with the device.

jobId

The unique identifier assigned to this job when it was created.

Or use $next to return the next pending (status IN_PROGRESS or QUEUED) job execution for a thing. In this case, any job executions with status IN_PROGRESS are returned first. Job executions are returned in the order in which they were created.

executionNumber

Optional. A number that identifies a particular job execution on a particular device. If not specified, the latest job execution is returned.

includeJobDocument

Optional. When set to true, the response contains the job document. The default is true.

clientToken

A client token used to correlate requests and responses. Enter an arbitrary value here and it will be reflected in the response.

To receive the response, subscribe to:

  • $aws/things/thingName/jobs/jobId/get/accepted ...and...

  • $aws/things/thingName/jobs/jobId/get/rejected ...or...

  • $aws/things/thingName/jobs/jobId/get/# ...for both...

Response payload:

{ "execution" : JobExecutionData, "timestamp": "timestamp", "clientToken": "string" }
execution

A JobExecution object.

timestamp

The time, in milliseconds since the epoch, when the message was sent.

clientToken

A client token used to correlate requests and responses.

HTTPS (13)

The job's execution status must be QUEUED or IN_PROGRESS.

Request:

GET /things/thingName/jobs/jobId?executionNumber=executionNumber&includeJobDocument=includeJobDocument
thingName

The name of the thing associated with the device.

jobId

The unique identifier assigned to this job when it was created.

Or use $next to return the next pending (status IN_PROGRESS or QUEUED) job execution for a thing. In this case, any job executions with status IN_PROGRESS are returned first. Job executions are returned in the order in which they were created.

includeJobDocument

Optional. When set to true, the response contains the job document. The default is false.

executionNumber

Optional. A number that identifies a particular job execution on a particular device. If not specified, the latest job execution is returned.

Response:

{ "execution" : JobExecution, }
execution

A JobExecution object.

CLI (13)

The job's execution status must be QUEUED or IN_PROGRESS.

Synopsis:

aws iot-jobs-data describe-job-execution \ --job-id <value> \ --thing-name <value> \ [--include-job-document | --no-include-job-document] \ [--execution-number <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "jobId": "string", "thingName": "string", "includeJobDocument": "boolean", "executionNumber": "long" }

cli-input-json fields:

Name

Type

Description

jobId

string

pattern: [a-zA-Z0-9_-]+|^$next

The unique identifier assigned to this job when it was created, or $next to return the next pending (status IN_PROGRESS or QUEUED) job execution for a thing. In this case, any job executions with status IN_PROGRESS are returned first. Job executions are returned in the order in which they were created.

thingName

string

length max:128 min:1

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

The thing name associated with the device the job execution is running on.

includeJobDocument

boolean

java class: java.lang.Boolean

Optional. When set to true, the response contains the job document. The default is false.

executionNumber

long

java class: java.lang.Long

Optional. A number that identifies a particular job execution on a particular device. If not specified, the latest job execution is returned.

Output:

{ "execution": { "jobId": "string", "thingName": "string", "status": "string", "statusDetails": { "string": "string" }, "queuedAt": "long", "startedAt": "long", "lastUpdatedAt": "long", "versionNumber": "long", "executionNumber": "long", "jobDocument": "string" } }

cli output fields:

Name

Type

Description

execution

JobExecution

Contains data about a job execution.

jobId

string

length max:64 min:1

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

The unique identifier you assigned to this job when it was created.

thingName

string

length max:128 min:1

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

The name of the thing that is executing the job.

status

string

enum: QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | REJECTED | REMOVED | CANCELED

java class: com.amazonaws.iot.laser.common.JobExecutionStatus

The status of the job execution. Can be one of: "QUEUED", "IN_PROGRESS", "FAILED", "SUCCESS", "CANCELED", "REJECTED", or "REMOVED".

statusDetails

map

key: DetailsKey

value: DetailsValue

A collection of name/value pairs that describe the status of the job execution.

DetailsKey

string

length max:128 min:1

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

DetailsValue

string

length max:1024 min:1

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

queuedAt

long

The time, in milliseconds since the epoch, when the job execution was enqueued.

startedAt

long

java class: java.lang.Long

The time, in milliseconds since the epoch, when the job execution was started.

lastUpdatedAt

long

The time, in milliseconds since the epoch, when the job execution was last updated.

versionNumber

long

The version of the job execution. Job execution versions are incremented each time they are updated by a device.

executionNumber

long

java class: java.lang.Long

A number that identifies a particular job execution on a particular device. It can be used later in commands that return or update job execution information.

jobDocument

string

length max:32768

The content of the job document.

UpdateJobExecution

UpdateJobExecution commandMQTT (14)HTTPS (14)CLI (14)
UpdateJobExecution command

Updates the status of a job execution.

MQTT (14)

To invoke this API, publish a message on $aws/things/thingName/jobs/jobId/update.

Request payload:

{ "status": "job-execution-state", "statusDetails": { "string": "string" ... }, "expectedVersion": "number", "executionNumber": "long", "includeJobExecutionState": "boolean", "includeJobDocument": "boolean", "clientToken": "string" }
status

The new status for the job execution (IN_PROGRESS, FAILED, SUCCEEDED, or REJECTED). This must be specified on every update.

statusDetails

A collection of name/value pairs that describe the status of the job execution. If not specified, the statusDetails are unchanged.

expectedVersion

The expected current version of the job execution. Each time you update the job execution, its version is incremented. If the version of the job execution stored in Jobs does not match, the update is rejected with a VersionMismatch error, and an ErrorResponse that contains the current job execution status data is returned. (This makes it unnecessary to perform a separate DescribeJobExecution request in order to obtain the job execution status data.)

executionNumber

Optional. A number that identifies a particular job execution on a particular device. If not specified, the latest job execution is used.

includeJobExecutionState

Optional. When included and set to true, the response contains the JobExecutionState field. The default is false.

includeJobDocument

Optional. When included and set to true, the response contains the JobDocument. The default is false.

clientToken

A client token used to correlate requests and responses. Enter an arbitrary value here and it will be reflected in the response.

To receive the response, subscribe to:

  • $aws/things/thingName/jobs/jobId/update/accepted ...and...

  • $aws/things/thingName/jobs/jobId/update/rejected ...or...

  • $aws/things/thingName/jobs/jobId/update/# ...for both...

Response payload:

{ "executionState": JobExecutionState, "jobDocument": "string", "timestamp": timestamp, "clientToken": "string" }
executionState

A JobExecutionState object.

jobDocument

A job document object.

timestamp

The time, in milliseconds since the epoch, when the message was sent.

clientToken

A client token used to correlate requests and responses.

HTTPS (14)

Request:

POST /things/thingName/jobs/jobId { "status": "job-execution-state", "statusDetails": { "string": "string" ... }, "expectedVersion": "number", "includeJobExecutionState": "boolean", "includeJobDocument": "boolean", "executionNumber": "long" }
thingName

The name of the thing associated with the device.

jobId

The unique identifier assigned to this job when it was created.

status

The new status for the job execution (IN_PROGRESS, FAILED, SUCCEEDED, or REJECTED). This must be specified on every update.

statusDetails

Optional. A collection of name/value pairs that describe the status of the job execution. If not specified, the statusDetails are unchanged.

expectedVersion

Optional. The expected current version of the job execution. Each time you update the job execution, its version is incremented. If the version of the job execution stored in Jobs does not match, the update is rejected with a VersionMismatch error, and an ErrorResponse that contains the current job execution status data is returned. (This makes it unnecessary to perform a separate DescribeJobExecution request in order to obtain the job execution status data.)

includeJobExecutionState

Optional. When included and set to true, the response contains the JobExecutionState data. The default is false.

includeJobDocument

Optional. When set to true, the response contains the job document. The default is false.

executionNumber

Optional. A number that identifies a particular job execution on a particular device.

Response:

{ "executionState": JobExecutionState, "jobDocument": "string" }
executionState

A JobExecutionState object.

jobDocument

The contents of the job document.

CLI (14)

Synopsis:

aws iot-jobs-data update-job-execution \ --job-id <value> \ --thing-name <value> \ --status <value> \ [--status-details <value>] \ [--expected-version <value>] \ [--include-job-execution-state | --no-include-job-execution-state] \ [--include-job-document | --no-include-job-document] \ [--execution-number <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "jobId": "string", "thingName": "string", "status": "string", "statusDetails": { "string": "string" }, "expectedVersion": "long", "includeJobExecutionState": "boolean", "includeJobDocument": "boolean", "executionNumber": "long" }

cli-input-json fields:

Name

Type

Description

jobId

string

length max:64 min:1

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

The unique identifier assigned to this job when it was created.

thingName

string

length max:128 min:1

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

The name of the thing associated with the device.

status

string

enum: QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | REJECTED | REMOVED | CANCELED

java class: com.amazonaws.iot.laser.common.JobExecutionStatus

The new status for the job execution (IN_PROGRESS, FAILED, SUCCESS, or REJECTED). This must be specified on every update.

statusDetails

map

key: DetailsKey

value: DetailsValue

Optional. A collection of name/value pairs that describe the status of the job execution. If not specified, the statusDetails are unchanged.

DetailsKey

string

length max:128 min:1

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

DetailsValue

string

length max:1024 min:1

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

expectedVersion

long

java class: java.lang.Long

Optional. The expected current version of the job execution. Each time you update the job execution, its version is incremented. If the version of the job execution stored in Jobs does not match, the update is rejected with a VersionMismatch error, and an ErrorResponse that contains the current job execution status data is returned. (This makes it unnecessary to perform a separate DescribeJobExecution request in order to obtain the job execution status data.)

includeJobExecutionState

boolean

java class: java.lang.Boolean

Optional. When included and set to true, the response contains the JobExecutionState data. The default is false.

includeJobDocument

boolean

java class: java.lang.Boolean

Optional. When set to true, the response contains the job document. The default is false.

executionNumber

long

java class: java.lang.Long

Optional. A number that identifies a particular job execution on a particular device.

Output:

{ "executionState": { "status": "string", "statusDetails": { "string": "string" }, "versionNumber": "long" }, "jobDocument": "string" }

cli output fields:

Name

Type

Description

executionState

JobExecutionState

A JobExecutionState object.

status

string

enum: QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | REJECTED | REMOVED | CANCELED

java class: com.amazonaws.iot.laser.common.JobExecutionStatus

The status of the job execution. Can be one of: "QUEUED", "IN_PROGRESS", "FAILED", "SUCCESS", "CANCELED", "REJECTED", or "REMOVED".

statusDetails

map

key: DetailsKey

value: DetailsValue

A collection of name/value pairs that describe the status of the job execution.

DetailsKey

string

length max:128 min:1

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

DetailsValue

string

length max:1024 min:1

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

versionNumber

long

The version of the job execution. Job execution versions are incremented each time they are updated by a device.

jobDocument

string

length max:32768

The contents of the Job Documents.

JobExecutionsChanged

JobExecutionsChanged messageMQTT (15)HTTPS (15)CLI (15)
JobExecutionsChanged message

Sent whenever a job execution is added to or removed from the list of pending job executions for a thing.

MQTT (15)

Topic: $aws/things/thingName/jobs/notify

Message payload:

{ "jobs" : { "JobExecutionState": [ JobExecutionSummary ... ] }, "timestamp": timestamp, }
HTTPS (15)

Not available.

CLI (15)

Not available.

NextJobExecutionChanged

NextJobExecutionChanged messageMQTT (16)HTTPS (16)CLI (16)
NextJobExecutionChanged message

Sent whenever there is a change to which job execution is next on the list of pending job executions for a thing, as defined for DescribeJobExecution with jobId $next. This message is not sent when the next job's execution details change, only when the next job that would be returned by DescribeJobExecution with jobId $next has changed. Consider job executions J1 and J2 with state QUEUED. J1 is next on the list of pending job executions. If the state of J2 is changed to IN_PROGRESS while the state of J1 remains unchanged, then this notification is sent and contains details of J2.

MQTT (16)

Topic: $aws/things/thingName/jobs/notify-next

Message payload:

{ "execution" : JobExecutionData, "timestamp": timestamp, }
HTTPS (16)

Not available.

CLI (16)

Not available.