Jobs management and control API and data types
The following commands are available for Job management and control in the CLI and over the HTTPS protocol.
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 z-amzn-http-ca.
Job management and control data types
The following data types are used by management and control applications to communicate with AWS IoT Jobs.
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 } }
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 JobSummary or job-summary.
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 GetJobDocument API operation or the get-job-document 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 JobExecution or job-execution.
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 JobExecutionSummary or job-execution-summary.
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 JobExecutionSummaryForJob or job-execution-summary-for-job.
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 JobExecutionSummaryForThing or job-execution-summary-for-thing.
Job management and control API operations
Use the following API operations or CLI commands:
Associates a group with a continuous job. The following criteria must be met:
-
The job must have been created with the
targetSelectionfield set toCONTINUOUS. -
The job status must currently be
IN_PROGRESS. -
The total number of targets associated with a job must not exceed 100.
Cancels a job.
Cancels a job execution on a device.
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, 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
targetsargument must be a list of valid thing or thing group ARNs. All things and thing groups must be in your AWS account. -
The
documentSourceargument 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
documentSourceargument 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
jobIdmust be unique in your AWS account.
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_IN_PROGRESS". Attempting to delete or cancel a job whose status is already "DELETION_IN_PROGRESS" results in an error.
Deletes a job execution.
Gets the details of the job execution.
Gets details of a job execution. The job's execution status
must be SUCCEEDED or FAILED.
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.
Gets a list of job executions for a job.
Gets a list of job executions for a thing.
Gets a list of jobs in your AWS account.
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.
