Jobs device MQTT API operations - 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 MQTT API operations

You can issue jobs device commands by publishing MQTT messages to the Reserved topics used for Jobs commands.

Your device-side client must be subscribed to the response message topics of these commands. If you use the Amazon 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 to receive any events on the cloud side. Job progress messages that are processed through the message broker and can be used by Amazon IoT rules are published as Jobs events. 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 Amazon 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.

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.

Response payload:

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

Where inProgressJobs and queuedJobs return a list of JobExecutionSummary objects that have status of IN_PROGRESS or QUEUED.

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

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.

Response payload:

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

Where execution is 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,
}

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.

Response payload:

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

Where execution is a JobExecution object.

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 Amazon IoT Jobs service doesn't match, the update is rejected with a VersionMismatch error. An ErrorResponse 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.

Response payload:

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

A JobExecutionState object.

jobDocument

A job document 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:

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": [ JobExecutionSummary ... ]
         },
    "timestamp": timestamp
}

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 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" : JobExecution,
"timestamp": timestamp,
}