Jobs device HTTP API - Amazon IoT Core
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Jobs device HTTP API

Devices can communicate with Amazon IoT Jobs using HTTP Signature Version 4 on port 443. This is the method used by the Amazon SDKs and CLI. For more information about those tools, see Amazon CLI Command Reference:iot-jobs-data or Amazon SDKs and Tools.

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.

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

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

cli-input-json format:

{
"thingName": "string"
}

For more information, see get-pending-job-executions.

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

CLI syntax

Synopsis:

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

cli-input-json format:

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

For more information, see start-next-pending-job-execution.

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

CLI syntax

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
}

For more information, see describe-job-execution.

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

CLI syntax

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>] \
[--step-timeout-in-minutes <value>] \
[--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 update-job-execution.