2018/06/01 - AWS IoT - 1 new 3 updated api methods
Changes We are releasing force CancelJob and CancelJobExecution functionalities to customers.
Cancels the execution of a job for a given thing.
See also: AWS API Documentation
Request Syntax
client.cancel_job_execution(
jobId='string',
thingName='string',
force=True|False,
expectedVersion=123,
statusDetails={
'string': 'string'
}
)
string
[REQUIRED]
The ID of the job to be canceled.
string
[REQUIRED]
The name of the thing whose execution of the job will be canceled.
boolean
(Optional) If true the job execution will be canceled if it has status IN_PROGRESS or QUEUED, otherwise the job execution will be canceled only if it has status QUEUED. If you attempt to cancel a job execution that is IN_PROGRESS, and you do not set force to true , then an InvalidStateTransitionException will be thrown. The default is false .
Canceling a job execution which is "IN_PROGRESS", will cause the device to be unable to update the job execution status. Use caution and ensure that the device is able to recover to a valid state.
integer
(Optional) 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 Jobs does not match, the update is rejected with a VersionMismatch error, and an ErrorResponse that contains the current job execution status data is returned. (This makes it unnecessary to perform a separate DescribeJobExecution request in order to obtain the job execution status data.)
dict
A collection of name/value pairs that describe the status of the job execution. If not specified, the statusDetails are unchanged. You can specify at most 10 name/value pairs.
(string) --
(string) --
None
{'force': 'boolean'}
Cancels a job.
See also: AWS API Documentation
Request Syntax
client.cancel_job(
jobId='string',
comment='string',
force=True|False
)
string
[REQUIRED]
The unique identifier you assigned to this job when it was created.
string
An optional comment string describing why the job was canceled.
boolean
(Optional) If true job executions with status "IN_PROGRESS" and "QUEUED" are canceled, otherwise only job executions with status "QUEUED" are canceled. The default is false .
Canceling a job which is "IN_PROGRESS", will cause a device which is executing the job to be unable to update the job execution status. Use caution and ensure that each device executing a job which is canceled is able to recover to a valid state.
dict
Response Syntax
{
'jobArn': 'string',
'jobId': 'string',
'description': 'string'
}
Response Structure
(dict) --
jobArn (string) --
The job ARN.
jobId (string) --
The unique identifier you assigned to this job when it was created.
description (string) --
A short text description of the job.
{'job': {'forceCanceled': 'boolean'}}
Describes a job.
See also: AWS API Documentation
Request Syntax
client.describe_job(
jobId='string'
)
string
[REQUIRED]
The unique identifier you assigned to this job when it was created.
dict
Response Syntax
{
'documentSource': 'string',
'job': {
'jobArn': 'string',
'jobId': 'string',
'targetSelection': 'CONTINUOUS'|'SNAPSHOT',
'status': 'IN_PROGRESS'|'CANCELED'|'COMPLETED'|'DELETION_IN_PROGRESS',
'forceCanceled': True|False,
'comment': 'string',
'targets': [
'string',
],
'description': 'string',
'presignedUrlConfig': {
'roleArn': 'string',
'expiresInSec': 123
},
'jobExecutionsRolloutConfig': {
'maximumPerMinute': 123
},
'createdAt': datetime(2015, 1, 1),
'lastUpdatedAt': datetime(2015, 1, 1),
'completedAt': datetime(2015, 1, 1),
'jobProcessDetails': {
'processingTargets': [
'string',
],
'numberOfCanceledThings': 123,
'numberOfSucceededThings': 123,
'numberOfFailedThings': 123,
'numberOfRejectedThings': 123,
'numberOfQueuedThings': 123,
'numberOfInProgressThings': 123,
'numberOfRemovedThings': 123
},
'documentParameters': {
'string': 'string'
}
}
}
Response Structure
(dict) --
documentSource (string) --
An S3 link to the job document.
job (dict) --
Information about the job.
jobArn (string) --
An ARN identifying the job with format "arn:aws:iot:region:account:job/jobId".
jobId (string) --
The unique identifier you assigned to this job when it was created.
targetSelection (string) --
Specifies whether the job will continue to run (CONTINUOUS), or will be complete after all those things specified as targets have completed the job (SNAPSHOT). If continuous, the job may also be run on a thing when a change is detected in a target. For example, a job will run on a device when the thing representing the device is added to a target group, even after the job was completed by all things originally in the group.
status (string) --
The status of the job, one of IN_PROGRESS , CANCELED , or COMPLETED .
forceCanceled (boolean) --
Will be true if the job was canceled with the optional force parameter set to true .
comment (string) --
If the job was updated, describes the reason for the update.
targets (list) --
A list of IoT things and thing groups to which the job should be sent.
(string) --
description (string) --
A short text description of the job.
presignedUrlConfig (dict) --
Configuration for pre-signed S3 URLs.
roleArn (string) --
The ARN of an IAM role that grants grants permission to download files from the S3 bucket where the job data/updates are stored. The role must also grant permission for IoT to download the files.
expiresInSec (integer) --
How long (in seconds) pre-signed URLs are valid. Valid values are 60 - 3600, the default value is 3600 seconds. Pre-signed URLs are generated when Jobs receives an MQTT request for the job document.
jobExecutionsRolloutConfig (dict) --
Allows you to create a staged rollout of a job.
maximumPerMinute (integer) --
The maximum number of things that will be notified of a pending job, per minute. This parameter allows you to create a staged rollout.
createdAt (datetime) --
The time, in milliseconds since the epoch, when the job was created.
lastUpdatedAt (datetime) --
The time, in milliseconds since the epoch, when the job was last updated.
completedAt (datetime) --
The time, in milliseconds since the epoch, when the job was completed.
jobProcessDetails (dict) --
Details about the job process.
processingTargets (list) --
The target devices to which the job execution is being rolled out. This value will be null after the job execution has finished rolling out to all the target devices.
(string) --
numberOfCanceledThings (integer) --
The number of things that cancelled the job.
numberOfSucceededThings (integer) --
The number of things which successfully completed the job.
numberOfFailedThings (integer) --
The number of things that failed executing the job.
numberOfRejectedThings (integer) --
The number of things that rejected the job.
numberOfQueuedThings (integer) --
The number of things that are awaiting execution of the job.
numberOfInProgressThings (integer) --
The number of things currently executing the job.
numberOfRemovedThings (integer) --
The number of things that are no longer scheduled to execute the job because they have been deleted or have been removed from the group that was a target of the job.
documentParameters (dict) --
The parameters specified for the job document.
(string) --
(string) --
{'execution': {'forceCanceled': 'boolean', 'versionNumber': 'long'}}
Describes a job execution.
See also: AWS API Documentation
Request Syntax
client.describe_job_execution(
jobId='string',
thingName='string',
executionNumber=123
)
string
[REQUIRED]
The unique identifier you assigned to this job when it was created.
string
[REQUIRED]
The name of the thing on which the job execution is running.
integer
A string (consisting of the digits "0" through "9" which is used to specify a particular job execution on a particular device.
dict
Response Syntax
{
'execution': {
'jobId': 'string',
'status': 'QUEUED'|'IN_PROGRESS'|'SUCCEEDED'|'FAILED'|'REJECTED'|'REMOVED'|'CANCELED',
'forceCanceled': True|False,
'statusDetails': {
'detailsMap': {
'string': 'string'
}
},
'thingArn': 'string',
'queuedAt': datetime(2015, 1, 1),
'startedAt': datetime(2015, 1, 1),
'lastUpdatedAt': datetime(2015, 1, 1),
'executionNumber': 123,
'versionNumber': 123
}
}
Response Structure
(dict) --
execution (dict) --
Information about the job execution.
jobId (string) --
The unique identifier you assigned to the job when it was created.
status (string) --
The status of the job execution (IN_PROGRESS, QUEUED, FAILED, SUCCESS, CANCELED, or REJECTED).
forceCanceled (boolean) --
Will be true if the job execution was canceled with the optional force parameter set to true .
statusDetails (dict) --
A collection of name/value pairs that describe the status of the job execution.
detailsMap (dict) --
The job execution status.
(string) --
(string) --
thingArn (string) --
The ARN of the thing on which the job execution is running.
queuedAt (datetime) --
The time, in milliseconds since the epoch, when the job execution was queued.
startedAt (datetime) --
The time, in milliseconds since the epoch, when the job execution started.
lastUpdatedAt (datetime) --
The time, in milliseconds since the epoch, when the job execution was last updated.
executionNumber (integer) --
A string (consisting of the digits "0" through "9") which identifies this particular job execution on this particular device. It can be used in commands which return or update job execution information.
versionNumber (integer) --
The version of the job execution. Job execution versions are incremented each time they are updated by a device.