command_executions

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

Overview

Name	command_executions
Type	Resource
Id	aws.iot.command_executions

Fields

The following fields are returned by SELECT queries:

get_command_execution

Name	Datatype	Description
command_arn	string	The Amazon Resource Number (ARN) of the command. For example, arn:aws:iot:<region>:<accountid>:command/<commandId>
completed_at	string (date-time)	The timestamp, when the command execution was completed.
created_at	string (date-time)	The timestamp, when the command execution was created.
execution_id	string	The unique identifier of the command execution. (pattern: <code>[a-zA-Z0-9_-]+</code>)
execution_timeout_seconds	integer (int64)	Specifies the amount of time in seconds that the device can take to finish a command execution. A timer starts when the command execution is created. If the command execution status is not set to another terminal state before the timer expires, it will automatically update to TIMED_OUT.
last_updated_at	string (date-time)	The timestamp, when the command execution was last updated.
parameters	object	The list of parameters that the StartCommandExecution API used when performing the command on the device.
result	object	The result value for the current state of the command execution. The status provides information about the progress of the command execution. The device can use the result field to share additional details about the execution such as a return value of a remote function call. If you use the AWS-IoT-FleetWise namespace, then this field is not applicable in the API response.
started_at	string (date-time)	The timestamp, when the command execution was started.
status	string	The status of the command execution. After your devices receive the command and start performing the operations specified in the command, it can use the UpdateCommandExecution MQTT API to update the status information. (CREATED, IN_PROGRESS, SUCCEEDED, FAILED, REJECTED, TIMED_OUT)
status_reason	object	Your devices can use this parameter to provide additional context about the status of a command execution using a reason code and description.
target_arn	string	The Amazon Resource Number (ARN) of the device on which the command execution is being performed.
time_to_live	string (date-time)	The time to live (TTL) parameter that indicates the duration for which executions will be retained in your account. The default value is six months.

list_command_executions

Name	Datatype	Description
command_arn	string	The Amazon Resource Name (ARN) of the command execution.
completed_at	string (date-time)	The date and time at which the command completed executing on the target device.
created_at	string (date-time)	The date and time at which the command execution was created for the target device.
execution_id	string	The unique identifier of the command execution. (pattern: <code>[a-zA-Z0-9_-]+</code>)
started_at	string (date-time)	The date and time at which the command started executing on the target device.
status	string	The status of the command executions. (CREATED, IN_PROGRESS, SUCCEEDED, FAILED, REJECTED, TIMED_OUT)
target_arn	string	The Amazon Resource Name (ARN) of the target device for which the command is being executed.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_command_execution	select	execution_id, targetArn, region	includeResult	Gets information about the specific command execution on a single device.
list_command_executions	select	region	maxResults, nextToken	List all command executions. You must provide only the startedTimeFilter or the completedTimeFilter information. If you provide both time filters, the API will generate an error. You can use this information to retrieve a list of command executions within a specific timeframe. You must provide only the commandArn or the thingArn information depending on whether you want to list executions for a specific command or an IoT thing. If you provide both fields, the API will generate an error. For more information about considerations for using this API, see List command executions in your account (CLI).
delete_command_execution	delete	execution_id, targetArn, region		Delete a command execution. Only command executions that enter a terminal state can be deleted from your account.

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_id	string	The unique identifier of the command execution that you want to delete from your account.
region	string	AWS region (default: us-east-1)
targetArn	string	The Amazon Resource Number (ARN) of the target device for which you want to delete command executions.
includeResult	boolean	Can be used to specify whether to include the result of the command execution in the GetCommandExecution API response. Your device can use this field to provide additional information about the command execution. You only need to specify this field when using the AWS-IoT namespace.
maxResults	integer	The maximum number of results to return in this operation.
nextToken	string	To retrieve the next set of results, the nextToken value from a previous response; otherwise null to receive the first set of results.

SELECT examples

get_command_execution

Gets information about the specific command execution on a single device.

SELECT
command_arn,
completed_at,
created_at,
execution_id,
execution_timeout_seconds,
last_updated_at,
parameters,
result,
started_at,
status,
status_reason,
target_arn,
time_to_live
FROM aws.iot.command_executions
WHERE execution_id = '{{ execution_id }}' -- required
AND targetArn = '{{ targetArn }}' -- required
AND region = '{{ region }}' -- required
AND includeResult = '{{ includeResult }}'
;

list_command_executions

List all command executions. You must provide only the startedTimeFilter or the completedTimeFilter information. If you provide both time filters, the API will generate an error. You can use this information to retrieve a list of command executions within a specific timeframe. You must provide only the commandArn or the thingArn information depending on whether you want to list executions for a specific command or an IoT thing. If you provide both fields, the API will generate an error. For more information about considerations for using this API, see List command executions in your account (CLI).

SELECT
command_arn,
completed_at,
created_at,
execution_id,
started_at,
status,
target_arn
FROM aws.iot.command_executions
WHERE region = '{{ region }}' -- required
AND maxResults = '{{ maxResults }}'
AND nextToken = '{{ nextToken }}'
;

DELETE examples

delete_command_execution

Delete a command execution. Only command executions that enter a terminal state can be deleted from your account.

DELETE FROM aws.iot.command_executions
WHERE execution_id = '{{ execution_id }}' --required
AND targetArn = '{{ targetArn }}' --required
AND region = '{{ region }}' --required
;