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 or AWS
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.
