job_executions

Creates, updates, deletes, gets or lists a job_executions resource.

Overview

Name	job_executions
Type	Resource
Id	aws.iot.job_executions

Fields

The following fields are returned by SELECT queries:

describe_job_execution

Name	Datatype	Description
approximate_seconds_before_timed_out	integer (int64)	The estimated number of seconds that remain before the job execution status will be changed to TIMED_OUT. The timeout interval can be anywhere between 1 minute and 7 days (1 to 10080 minutes). The actual job execution timeout can occur up to 60 seconds later than the estimated duration. This value will not be included if the job execution has reached a terminal status.
execution_number	integer (int64)	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.
force_canceled	boolean	Will be true if the job execution was canceled with the optional force parameter set to true.
job_id	string	The unique identifier you assigned to the job when it was created. (pattern: <code>[a-zA-Z0-9_-]+</code>)
last_updated_at	string (date-time)	The time, in seconds since the epoch, when the job execution was last updated.
queued_at	string (date-time)	The time, in seconds since the epoch, when the job execution was queued.
started_at	string (date-time)	The time, in seconds since the epoch, when the job execution started.
status	string	The status of the job execution (IN_PROGRESS, QUEUED, FAILED, SUCCEEDED, TIMED_OUT, CANCELED, or REJECTED). (QUEUED, IN_PROGRESS, SUCCEEDED, FAILED, TIMED_OUT, REJECTED, REMOVED, CANCELED)
status_details	object	A collection of name/value pairs that describe the status of the job execution.
thing_arn	string	The ARN of the thing on which the job execution is running.
version_number	integer (int64)	The version of the job execution. Job execution versions are incremented each time they are updated by a device.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_job_execution	select	job_id, thing_name, region	executionNumber	Describes a job execution. Requires permission to access the DescribeJobExecution action.
delete_job_execution	delete	job_id, thing_name, execution_number, region	force, namespaceId	Deletes a job execution. Requires permission to access the DeleteJobExecution action.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
execution_number	integer (int64)	The ID of the job execution to be deleted. The executionNumber refers to the execution of a particular job on a particular device. Note that once a job execution is deleted, the executionNumber may be reused by IoT, so be sure you get and use the correct value here.
job_id	string	The ID of the job whose execution on a particular device will be deleted.
region	string	AWS region (default: us-east-1)
thing_name	string	The name of the thing whose job execution will be deleted.
executionNumber	integer (int64)	A string (consisting of the digits "0" through "9" which is used to specify a particular job execution on a particular device.
force	boolean	(Optional) When true, you can delete a job execution which is "IN_PROGRESS". Otherwise, you can only delete a job execution which is in a terminal state ("SUCCEEDED", "FAILED", "REJECTED", "REMOVED" or "CANCELED") or an exception will occur. The default is false. Deleting a job execution which is "IN_PROGRESS", will cause the device to be unable to access job information or update the job execution status. Use caution and ensure that the device is able to recover to a valid state.
namespaceId	string	The namespace used to indicate that a job is a customer-managed job. When you specify a value for this parameter, Amazon Web Services IoT Core sends jobs notifications to MQTT topics that contain the value in the following format. $aws/things/THING_NAME/jobs/JOB_ID/notify-namespace-NAMESPACE_ID/ The namespaceId feature is only supported by IoT Greengrass at this time. For more information, see Setting up IoT Greengrass core devices.

SELECT examples

describe_job_execution

Describes a job execution. Requires permission to access the DescribeJobExecution action.

SELECT
approximate_seconds_before_timed_out,
execution_number,
force_canceled,
job_id,
last_updated_at,
queued_at,
started_at,
status,
status_details,
thing_arn,
version_number
FROM aws.iot.job_executions
WHERE job_id = '{{ job_id }}' -- required
AND thing_name = '{{ thing_name }}' -- required
AND region = '{{ region }}' -- required
AND executionNumber = '{{ executionNumber }}'
;

DELETE examples

delete_job_execution

Deletes a job execution. Requires permission to access the DeleteJobExecution action.

DELETE FROM aws.iot.job_executions
WHERE job_id = '{{ job_id }}' --required
AND thing_name = '{{ thing_name }}' --required
AND execution_number = '{{ execution_number }}' --required
AND region = '{{ region }}' --required
AND force = '{{ force }}'
AND namespaceId = '{{ namespaceId }}'
;