# AWS IoT jobs API operations
AWS IoT Jobs API can be used for either of the following categories:
+ Administrative tasks such as management and control of jobs. This is the *control plane*.
+ Devices carrying out those jobs. This is the *data plane*, which permits you to send and receive data.
Job management and control uses an HTTPS protocol API. Devices can use either an MQTT or an HTTPS protocol API. The control plane 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 data plane HTTPS and MQTT API permit long polling. These API operations are designed for large amounts of traffic that can scale to millions of devices.
Each AWS IoT Jobs HTTPS API has a corresponding command that permits you to call the API from the AWS Command Line Interface (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 ...
```
If an error occurs during an operation, you get an error response that contains information about the error.
## ErrorResponse
Contains information about an error that occurred during an AWS IoT Jobs service operation.
The following example shows the syntax of this operation:
```
{
"code": "ErrorCode",
"message": "string",
"clientToken": "string",
"timestamp": timestamp,
"executionState": JobExecutionState
}
```
The following is a description of this `ErrorResponse`:
`code`
ErrorCode can be set to:
InvalidTopic
The request was sent to a topic in the AWS IoT Jobs namespace that doesn't map to any API operation.
InvalidJson
The contents of the request couldn't be interpreted as valid UTF-8-encoded JSON.
InvalidRequest
The contents of the request were not valid. 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 not valid because of the job execution's current state. For example, an attempt to change a request in state SUCCEEDED to state IN\$1PROGRESS. In this case, the body of the error message also contains the `executionState` field.
ResourceNotFound
The `JobExecution` specified by the request topic doesn't exist.
VersionMismatch
The expected version specified in the request doesn't match the version of the job execution in the AWS IoT Jobs service. In this case, the body of the error message also contains the `executionState` field.
InternalError
There was an internal error during the processing of 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 seconds since the epoch.
`executionState`
A [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionState.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionState.html) 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.
**Topics**
+ [Jobs management and control API and data types](jobs-management-control-api.md)
+ [Jobs device MQTT and HTTPS API operations and data types](jobs-mqtt-https-api.md)
# Jobs management and control API and data types
**Topics**
+ [Job management and control data types](#jobs-control-plane-data-types)
+ [Job management and control API operations](#jobs-http-api)
To determine the *endpoint-url* parameter for your CLI commands, run this command.
```
aws iot describe-endpoint --endpoint-type=iot:Jobs
```
This command returns the following output.
```
{
"endpointAddress": "account-specific-prefix.jobs.iot.aws-region.amazonaws.com"
}
```
**Note**
The Jobs endpoint doesn't support ALPN `x-amzn-http-ca`.
If you're using dual-stack endpoints (IPv6 and IPv6), use the `iot:Data-ATS` endpoint. The `iot:Jobs` endpoint supports only IPv4.
## Job management and control data types
The following data types are used by management and control applications to communicate with AWS IoT Jobs.
### Job
The `Job` object contains details about a job. The following example shows the syntax:
```
{
"jobArn": "string",
"jobId": "string",
"status": "IN_PROGRESS|CANCELED|SUCCEEDED",
"forceCanceled": boolean,
"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,
"numberOfTimedOutThings": long
},
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": integer,
"incrementFactor": integer,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": integer, // Set one or the other
"numberOfSucceededThings": integer // of these two values.
},
"maximumPerMinute": integer
}
},
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": integer,
"thresholdPercentage": integer
}
]
},
"SchedulingConfig": {
"startTime": string
"endTime": string
"timeZone": string
"endTimeBehavior": string
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": long
}
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_Job.html](https://docs.aws.amazon.com/iot/latest/apireference/API_Job.html) or [https://docs.aws.amazon.com/cli/latest/reference/iot/job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job.html).
### JobSummary
The `JobSummary` object contains a job summary. The following example shows the syntax:
```
{
"jobArn": "string",
"jobId": "string",
"status": "IN_PROGRESS|CANCELED|SUCCEEDED|SCHEDULED",
"targetSelection": "CONTINUOUS|SNAPSHOT",
"thingGroupId": "string",
"createdAt": timestamp,
"lastUpdatedAt": timestamp,
"completedAt": timestamp
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_JobSummary.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobSummary.html) or [https://docs.aws.amazon.com/cli/latest/reference/iot/job-summary.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job-summary.html).
### JobExecution
The `JobExecution` object represents the execution of a job on a device. The following example shows the syntax:
**Note**
When you use the control plane API operations, the `JobExecution` data type doesn't contain a `JobDocument` field. To obtain this information, you can use the [https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/get-job-document.html](https://docs.aws.amazon.com/cli/latest/reference/get-job-document.html) CLI command.
```
{
"approximateSecondsBeforeTimedOut": 50,
"executionNumber": 1234567890,
"forceCanceled": true|false,
"jobId": "string",
"lastUpdatedAt": timestamp,
"queuedAt": timestamp,
"startedAt": timestamp,
"status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED",
"forceCanceled": boolean,
"statusDetails": {
"detailsMap": {
"string": "string" ...
},
"status": "string"
},
"thingArn": "string",
"versionNumber": 123
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html) or [https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution.html).
### JobExecutionSummary
The `JobExecutionSummary` object contains job execution summary information. The following example shows the syntax:
```
{
"executionNumber": 1234567890,
"queuedAt": timestamp,
"lastUpdatedAt": timestamp,
"startedAt": timestamp,
"status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED"
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html) or [https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary.html).
### JobExecutionSummaryForJob
The `JobExecutionSummaryForJob` object contains a summary of information about job executions for a specific job. The following example shows the syntax:
```
{
"executionSummaries": [
{
"thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyThing",
"jobExecutionSummary": {
"status": "IN_PROGRESS",
"lastUpdatedAt": 1549395301.389,
"queuedAt": 1541526002.609,
"executionNumber": 1
}
},
...
]
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummaryForJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummaryForJob.html) or [https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary-for-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary-for-job.html).
### JobExecutionSummaryForThing
The `JobExecutionSummaryForThing` object contains a summary of information about a job execution on a specific thing. FThe following example shows the syntax:
```
{
"executionSummaries": [
{
"jobExecutionSummary": {
"status": "IN_PROGRESS",
"lastUpdatedAt": 1549395301.389,
"queuedAt": 1541526002.609,
"executionNumber": 1
},
"jobId": "MyThingJob"
},
...
]
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummaryForThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummaryForThing.html) or [https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary-for-thing.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary-for-thing.html).
## Job management and control API operations
Use the following API operations or CLI commands:
### AssociateTargetsWithJob
Associates a group with a continuous job. 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 request ]
```
POST /jobs/jobId/targets
{
"targets": [ "string" ],
"comment": "string"
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_AssociateTargetsWithJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_AssociateTargetsWithJob.html).
------
#### [ CLI syntax ]
```
aws iot associate-targets-with-job \
--targets \
--job-id \
[--comment ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"targets": [
"string"
],
"jobId": "string",
"comment": "string"
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/associate-targets-with-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/associate-targets-with-job.html).
------
### CancelJob
Cancels a job.
------
#### [ HTTPS request ]
```
PUT /jobs/jobId/cancel
{
"force": boolean,
"comment": "string",
"reasonCode": "string"
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJob.html).
------
#### [ CLI syntax ]
```
aws iot cancel-job \
--job-id \
[--force ] \
[--comment ] \
[--reasonCode ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"force": boolean,
"comment": "string"
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/cancel-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/cancel-job.html).
------
### CancelJobExecution
Cancels a job execution on a device.
------
#### [ HTTPS request ]
```
PUT /things/thingName/jobs/jobId/cancel
{
"force": boolean,
"expectedVersion": "string",
"statusDetails": {
"string": "string"
...
}
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJobExecution.html).
------
#### [ CLI syntax ]
```
aws iot cancel-job-execution \
--job-id \
--thing-name \
[--force | --no-force] \
[--expected-version ] \
[--status-details ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"thingName": "string",
"force": boolean,
"expectedVersion": long,
"statusDetails": {
"string": "string"
}
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/cancel-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot/cancel-job-execution.html).
------
### CreateJob
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 launched on newly added things. This can occur even after the things in the group at the time the job was created have completed the job.
A job can have an optional [TimeoutConfig](https://docs.aws.amazon.com//iot/latest/apireference/API_TimeoutConfig.html), which sets the value of the in-progress timer. The in-progress timer can't be updated and applies to all executions of 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 in 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 in your AWS account.
------
#### [ HTTPS request ]
```
PUT /jobs/jobId
{
"targets": [ "string" ],
"document": "string",
"documentSource": "string",
"description": "string",
"jobTemplateArn": "string",
"presignedUrlConfigData": {
"roleArn": "string",
"expiresInSec": "integer"
},
"targetSelection": "CONTINUOUS|SNAPSHOT",
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": integer,
"incrementFactor": integer,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": integer, // Set one or the other
"numberOfSucceededThings": integer // of these two values.
},
"maximumPerMinute": integer
}
},
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": integer,
"thresholdPercentage": integer
}
]
},
"SchedulingConfig": {
"startTime": string
"endTime": string
"timeZone": string
"endTimeBehavior": string
}
"timeoutConfig": {
"inProgressTimeoutInMinutes": long
}
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html).
------
#### [ CLI syntax ]
```
aws iot create-job \
--job-id \
--targets \
[--document-source ] \
[--document ] \
[--description ] \
[--job-template-arn ] \
[--presigned-url-config ] \
[--target-selection ] \
[--job-executions-rollout-config ] \
[--abort-config ] \
[--timeout-config ] \
[--document-parameters ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"targets": [ "string" ],
"documentSource": "string",
"document": "string",
"description": "string",
"jobTemplateArn": "string",
"presignedUrlConfig": {
"roleArn": "string",
"expiresInSec": long
},
"targetSelection": "string",
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": integer,
"incrementFactor": integer,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": integer, // Set one or the other
"numberOfSucceededThings": integer // of these two values.
},
"maximumPerMinute": integer
}
},
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": integer,
"thresholdPercentage": integer
}
]
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": long
},
"documentParameters": {
"string": "string"
}
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/create-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/create-job.html).
------
### DeleteJob
Deletes a job and its related job executions.
Deleting a job can take time, depending on the number of job executions created for the job and various other factors. While the job is being deleted, the status of the job is shown as "DELETION\$1IN\$1PROGRESS". Attempting to delete or cancel a job whose status is already "DELETION\$1IN\$1PROGRESS" results in an error.
------
#### [ HTTPS request ]
```
DELETE /jobs/jobId?force=force
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJob.html).
------
#### [ CLI syntax ]
```
aws iot delete-job \
--job-id \
[--force | --no-force] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"force": boolean
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/delete-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-job.html).
------
### DeleteJobExecution
Deletes a job execution.
------
#### [ HTTPS request ]
```
DELETE /things/thingName/jobs/jobId/executionNumber/executionNumber?force=force
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJobExecution.html).
------
#### [ CLI syntax ]
```
aws iot delete-job-execution \
--job-id \
--thing-name \
--execution-number \
[--force | --no-force] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"thingName": "string",
"executionNumber": long,
"force": boolean
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/delete-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-job-execution.html).
------
### DescribeJob
Gets the details of the job execution.
------
#### [ HTTPS request ]
```
GET /jobs/jobId
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJob.html).
------
#### [ CLI syntax ]
```
aws iot describe-job \
--job-id \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string"
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/describe-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-job.html).
------
### DescribeJobExecution
Gets details of a job execution. The job's execution status must be `SUCCEEDED` or `FAILED`.
------
#### [ HTTPS request ]
```
GET /things/thingName/jobs/jobId?executionNumber=executionNumber
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html).
------
#### [ CLI syntax ]
```
aws iot describe-job-execution \
--job-id \
--thing-name \
[--execution-number ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"thingName": "string",
"executionNumber": long
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/describe-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-job-execution.html).
------
### GetJobDocument
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 the AWS IoT Jobs service receives a request over MQTT.
------
#### [ HTTPS request ]
```
GET /jobs/jobId/job-document
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html).
------
#### [ CLI syntax ]
```
aws iot get-job-document \
--job-id \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string"
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/get-job-document.html](https://docs.aws.amazon.com/cli/latest/reference/iot/get-job-document.html).
------
### ListJobExecutionsForJob
Gets a list of job executions for a job.
------
#### [ HTTPS request ]
```
GET /jobs/jobId/things?status=status&maxResults=maxResults&nextToken=nextToken
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForJob.html).
------
#### [ CLI syntax ]
```
aws iot list-job-executions-for-job \
--job-id \
[--status ] \
[--max-results ] \
[--next-token ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"status": "string",
"maxResults": "integer",
"nextToken": "string"
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/list-job-executions-for-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-job-executions-for-job.html).
------
### ListJobExecutionsForThing
Gets a list of job executions for a thing.
------
#### [ HTTPS request ]
```
GET /things/thingName/jobs?status=status&maxResults=maxResults&nextToken=nextToken
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForThing.html).
------
#### [ CLI syntax ]
```
aws iot list-job-executions-for-thing \
--thing-name \
[--status ] \
[--max-results ] \
[--next-token ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"thingName": "string",
"status": "string",
"maxResults": "integer",
"nextToken": "string"
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/list-job-executions-for-thing.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-job-executions-for-thing.html).
------
### ListJobs
Gets a list of jobs in your AWS account.
------
#### [ HTTPS request ]
```
GET /jobs?status=status&targetSelection=targetSelection&thingGroupName=thingGroupName&thingGroupId=thingGroupId&maxResults=maxResults&nextToken=nextToken
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobs.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobs.html).
------
#### [ CLI syntax ]
```
aws iot list-jobs \
[--status ] \
[--target-selection ] \
[--max-results ] \
[--next-token ] \
[--thing-group-name ] \
[--thing-group-id ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"status": "string",
"targetSelection": "string",
"maxResults": "integer",
"nextToken": "string",
"thingGroupName": "string",
"thingGroupId": "string"
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/list-jobs.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-jobs.html).
------
### UpdateJob
Updates supported fields of the specified job. Updated values for `timeoutConfig` take effect for only newly in-progress launches. Currently, in-progress launches continue to launch with the previous timeout configuration.
------
#### [ HTTPS request ]
```
PATCH /jobs/jobId
{
"description": "string",
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": number,
"incrementFactor": number,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": number,
"numberOfSucceededThings": number
},
"maximumPerMinute": number
},
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": number,
"thresholdPercentage": number
}
]
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateJob.html).
------
#### [ CLI syntax ]
```
aws iot update-job \
--job-id \
[--description ] \
[--presigned-url-config ] \
[--job-executions-rollout-config ] \
[--abort-config ] \
[--timeout-config ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"description": "string",
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": number,
"incrementFactor": number,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": number,
"numberOfSucceededThings": number
}
},
"maximumPerMinute": number
},
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": number,
"thresholdPercentage": number
}
]
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/update-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/update-job.html).
------
# Jobs device MQTT and HTTPS API operations and data types
The following commands are available over the MQTT and HTTPS protocols. Use these API operations on the data plane for devices executing the jobs.
## Jobs device MQTT and HTTPS data types
The following data types are used to communicate with the AWS IoT Jobs service over the MQTT and HTTPS protocols.
### JobExecution
The `JobExecution` object represents the execution of a job on a device. The following example shows the syntax:
**Note**
When you use the MQTT and HTTP data plane API operations, the `JobExecution` data type contains a `JobDocument` field. Your devices can use this information to retrieve the job document from a job execution.
```
{
"jobId" : "string",
"thingName" : "string",
"jobDocument" : "string",
"status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED",
"statusDetails": {
"string": "string"
},
"queuedAt" : "timestamp",
"startedAt" : "timestamp",
"lastUpdatedAt" : "timestamp",
"versionNumber" : "number",
"executionNumber": long
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecution.html) or [https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution.html).
### JobExecutionState
The `JobExecutionState` contains information about the state of a job execution. The following example shows the syntax:
```
{
"status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED",
"statusDetails": {
"string": "string"
...
}
"versionNumber": "number"
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionState.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionState.html) or [https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution-state.html](https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution-state.html).
### JobExecutionSummary
Contains a subset of information about a job execution. The following example shows the syntax:
```
{
"jobId": "string",
"queuedAt": timestamp,
"startedAt": timestamp,
"lastUpdatedAt": timestamp,
"versionNumber": "number",
"executionNumber": long
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionSummary.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionSummary.html) or [https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution-summary.html](https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution-summary.html).
**Topics**
+ [Jobs device MQTT and HTTPS data types](#jobs-data-plane-data-types)
+ [Jobs device MQTT API operations](jobs-mqtt-api.md)
+ [Jobs device HTTP API](jobs-http-device-api.md)
# Jobs device MQTT API operations
You can issue jobs device commands by publishing MQTT messages to the [Reserved topics used for Jobs commands](reserved-topics.md#reserved-topics-job).
Your device-side client must be subscribed to the response message topics of these commands. If you use the AWS IoT Device Client, your device will automatically subscribe to the response topics. This means that the message broker will publish response message topics to the client that published the command message, whether or not your client has subscribed to the response message topics. These response messages don't pass through the message broker and can't be subscribed to by other clients or rules.
When subscribing to the job and `jobExecution` event topics for your fleet-monitoring solution, first enable [job and job execution events](iot-events.md) to receive any events on the cloud side. Job progress messages that are processed through the message broker and can be used by AWS IoT rules are published as [Jobs events](events-jobs.md). Because the message broker publishes response messages, even without an explicit subscription to them, your client must be configured to receive and identify the messages it receives. Your client must also confirm that the *thingName* in the incoming message topic applies to the client's thing name before the client acts on the message.
**Note**
Messages that AWS IoT sends in response to MQTT Jobs API command messages are charged to your account, whether or not you subscribed to them explicitly.
The following shows the MQTT API operations and their request and response syntax. All MQTT API operations have the following parameters:
clientToken
An optional client token used to correlate requests and responses. Enter an arbitrary value here and it's reflected in the response.
`timestamp`
The time in seconds since the epoch, when the message was sent.
## GetPendingJobExecutions
Gets the list of all jobs that are not in a terminal state, for a specified thing.
To invoke this API, publish a message on `$aws/things/thingName/jobs/get`.
Request payload:
```
{ "clientToken": "string" }
```
The message broker will publish `$aws/things/thingName/jobs/get/accepted` and `$aws/things/thingName/jobs/get/rejected` even without a specific subscription to them. However, for your client to receive the messages, it must be listening for them. For more information, see [the note about Jobs API messages](#jobs-mqtt-note).
Response payload:
```
{
"inProgressJobs" : [ JobExecutionSummary ... ],
"queuedJobs" : [ JobExecutionSummary ... ],
"timestamp" : 1489096425069,
"clientToken" : "client-001"
}
```
Where `inProgressJobs` and `queuedJobs` return a list of [JobExecutionSummary](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-summary) objects that have status of `IN_PROGRESS` or `QUEUED`.
## StartNextPendingJobExecution
Gets and starts the next pending job execution for a thing (status `IN_PROGRESS` or `QUEUED`).
+ Any job executions with status `IN_PROGRESS` are returned first.
+ Job executions are returned in the order in which they were queued. When a thing is added or removed from the target group for your job, confirm the rollout order of any new job executions compared to existing job executions.
+ If the next pending job execution is `QUEUED`, its state changes 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 aren't changed.
+ If no job executions are pending, the response doesn't include the `execution` field.
+ Optionally, you can create a step timer by setting a value for the `stepTimeoutInMinutes` property. If you don't update the value of this property by running `UpdateJobExecution`, the job execution times out when the step timer expires.
To invoke this API, publish a message on `$aws/things/thingName/jobs/start-next`.
Request payload:
```
{
"statusDetails": {
"string": "job-execution-state"
...
},
"stepTimeoutInMinutes": long,
"clientToken": "string"
}
```
`statusDetails`
A collection of name-value pairs that describe the status of the job execution. If not specified, the `statusDetails` are unchanged.
`stepTimeOutInMinutes`
Specifies the amount of time this device has to finish execution of this job. If the job execution status isn't set to a terminal state before this timer expires, or before the timer is reset, (by calling `UpdateJobExecution`, setting the status to `IN_PROGRESS` and specifying a new timeout value in field `stepTimeoutInMinutes`) the job execution status is set to `TIMED_OUT`. Setting this timeout has no effect on that job execution timeout that might have been specified when the job was created (`CreateJob` using the `timeoutConfig` field).
Valid values for this parameter range from 1 to 10080 (1 minute to 7 days). A value of -1 is also valid and will cancel the current step timer (created by an earlier use of UpdateJobExecutionRequest).
The message broker will publish `$aws/things/thingName/jobs/start-next/accepted` and `$aws/things/thingName/jobs/start-next/rejected` even without a specific subscription to them. However, for your client to receive the messages, it must be listening for them. For more information, see [the note about Jobs API messages](#jobs-mqtt-note).
Response payload:
```
{
"execution" : JobExecutionData,
"timestamp" : timestamp,
"clientToken" : "string"
}
```
Where `execution` is a [JobExecution](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-data) 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,
}
```
## DescribeJobExecution
Gets detailed information about a job execution.
You can set the `jobId` to `$next` to return the next pending job execution for a thing (with a status of `IN_PROGRESS` or `QUEUED`).
To invoke this API, publish a message on `$aws/things/thingName/jobs/jobId/get`.
Request payload:
```
{
"jobId" : "022",
"thingName" : "MyThing",
"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 job execution for a thing (with a status of `IN_PROGRESS` or `QUEUED`). 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 job execution on a device. If not specified, the latest job execution is returned.
`includeJobDocument`
(Optional) Unless set to `false`, the response contains the job document. The default is `true`.
The message broker will publish `$aws/things/thingName/jobs/jobId/get/accepted` and `$aws/things/thingName/jobs/jobId/get/rejected` even without a specific subscription to them. However, for your client to receive the messages, it must be listening for them. For more information, see [the note about Jobs API messages](#jobs-mqtt-note).
Response payload:
```
{
"execution" : JobExecutionData,
"timestamp": "timestamp",
"clientToken": "string"
}
```
Where `execution` is a [JobExecution](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-data) object.
## UpdateJobExecution
Updates the status of a job execution. You can optionally create a step timer by setting a value for the `stepTimeoutInMinutes` property. If you don't update the value of this property by running `UpdateJobExecution` again, the job execution times out when the step timer expires.
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,
"stepTimeoutInMinutes": long,
"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 the AWS IoT Jobs service doesn't match, the update is rejected with a `VersionMismatch` error. An [ErrorResponse](jobs-api.md#jobs-mqtt-error-response) that contains the current job execution status data is also returned. (This makes it unnecessary to perform a separate `DescribeJobExecution` request to obtain the job execution status data.)
`executionNumber`
(Optional) A number that identifies a job execution on a 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`.
`stepTimeoutInMinutes`
Specifies the amount of time this device has to finish execution of this job. If the job execution status is not set to a terminal state before this timer expires, or before the timer is reset, the job execution status is set to `TIMED_OUT`. Setting or resetting this timeout has no effect on the job execution timeout that might have been specified when the job was created.
The message broker will publish `$aws/things/thingName/jobs/jobId/update/accepted` and `$aws/things/thingName/jobs/jobId/update/rejected` even without a specific subscription to them. However, for your client to receive the messages, it must be listening for them. For more information, see [the note about Jobs API messages](#jobs-mqtt-note).
Response payload:
```
{
"executionState": JobExecutionState,
"jobDocument": "string",
"timestamp": timestamp,
"clientToken": "string"
}
```
`executionState`
A [JobExecutionState](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-state) object.
`jobDocument`
A [job document](key-concepts-jobs.md) object.
In MQTT responses, the `jobDocument` field is a JSON object. In HTTP responses, it's a string representation of the JSON object.
`timestamp`
The time in seconds since the epoch, when the message was sent.
`clientToken`
A client token used to correlate requests and responses.
When you use the MQTT protocol, you can also perform the following updates:
## JobExecutionsChanged
Sent whenever a job execution is added to or removed from the list of pending job executions for a thing.
Use the topic:
`$aws/things/thingName/jobs/notify`
Message payload:
```
{
"jobs" : {
"JobExecutionState": [ [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html) ... ]
},
"timestamp": timestamp
}
```
## NextJobExecutionChanged
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 [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html) 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 a status of `QUEUED`. J1 is next on the list of pending job executions. If the status of J2 is changed to `IN_PROGRESS` while the state of J1 remains unchanged, then this notification is sent and contains details of J2.
Use the topic:
`$aws/things/thingName/jobs/notify-next`
Message payload:
```
{
"execution" : [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html),
"timestamp": timestamp,
}
```
# Jobs device HTTP API
Devices can communicate with AWS IoT Jobs using HTTP Signature Version 4 on port 443. This is the method used by the AWS SDKs and CLI. For more information about those tools, see [AWS CLI Command Reference:iot-jobs-data](https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/index.html) or [AWS SDKs and Tools](http://aws.amazon.com/tools/#sdk).
The following commands are available for devices executing the jobs. For information about using API operations with the MQTT protocol, see [Jobs device MQTT API operations](jobs-mqtt-api.md).
## GetPendingJobExecutions
Gets the list of all jobs that aren't in a terminal state, for a specified thing.
------
#### [ HTTPS request ]
```
GET /things/thingName/jobs
```
Response:
```
{
"inProgressJobs" : [ JobExecutionSummary ... ],
"queuedJobs" : [ JobExecutionSummary ... ]
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html).
------
#### [ CLI syntax ]
```
aws iot-jobs-data get-pending-job-executions \
--thing-name \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"thingName": "string"
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/get-pending-job-executions.html](https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/get-pending-job-executions.html).
------
## StartNextPendingJobExecution
Gets and starts the next pending job execution for a thing (with a status of `IN_PROGRESS` or `QUEUED`).
+ 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 status changes 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 don't change.
+ If no job executions are pending, the response doesn't include the `execution` field.
+ Optionally, you can create a step timer by setting a value for the `stepTimeoutInMinutes` property. If you don't update the value of this property by running `UpdateJobExecution`, the job execution times out when the step timer expires.
------
#### [ HTTPS request ]
The following example shows the request syntax:
```
PUT /things/thingName/jobs/$next
{
"statusDetails": {
"string": "string"
...
},
"stepTimeoutInMinutes": long
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_StartNextPendingJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_StartNextPendingJobExecution.html).
------
#### [ CLI syntax ]
**Synopsis:**
```
aws iot-jobs-data start-next-pending-job-execution \
--thing-name \
{--step-timeout-in-minutes ] \
[--status-details ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"thingName": "string",
"statusDetails": {
"string": "string"
},
"stepTimeoutInMinutes": long
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/start-next-pending-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/start-next-pending-job-execution.html).
------
## DescribeJobExecution
Gets detailed information about a job execution.
You can set the `jobId` to `$next` to return the next pending job execution for a thing. The job's execution status must be `QUEUED` or `IN_PROGRESS`.
------
#### [ HTTPS request ]
Request:
```
GET /things/thingName/jobs/jobId?executionNumber=executionNumber&includeJobDocument=includeJobDocument
```
Response:
```
{
"execution" : JobExecution,
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html).
------
#### [ CLI syntax ]
**Synopsis:**
```
aws iot-jobs-data describe-job-execution \
--job-id \
--thing-name \
[--include-job-document | --no-include-job-document] \
[--execution-number ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"thingName": "string",
"includeJobDocument": boolean,
"executionNumber": long
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot-data/describe-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot-data/describe-job-execution.html).
------
## UpdateJobExecution
Updates the status of a job execution. Optionally, you can create a step timer by setting a value for the `stepTimeoutInMinutes` property. If you don't update the value of this property by running `UpdateJobExecution` again, the job execution times out when the step timer expires.
------
#### [ HTTPS request ]
Request:
```
POST /things/thingName/jobs/jobId
{
"status": "job-execution-state",
"statusDetails": {
"string": "string"
...
},
"expectedVersion": "number",
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"stepTimeoutInMinutes": long,
"executionNumber": long
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html).
------
#### [ CLI syntax ]
**Synopsis:**
```
aws iot-jobs-data update-job-execution \
--job-id \
--thing-name \
--status \
[--status-details ] \
[--expected-version ] \
[--include-job-execution-state | --no-include-job-execution-state] \
[--include-job-document | --no-include-job-document] \
[--execution-number ] \
[--cli-input-json ] \
[--step-timeout-in-minutes ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"thingName": "string",
"status": "string",
"statusDetails": {
"string": "string"
},
"stepTimeoutInMinutes": number,
"expectedVersion": long,
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"executionNumber": long
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot-data/update-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot-data/update-job-execution.html).
------