Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

GetCommandExecution

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

Request Syntax


GET /command-executions/executionId?includeResult=includeResult&targetArn=targetArn HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

executionId

The unique identifier for the command execution. This information is returned as a response of the StartCommandExecution API request.

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: [a-zA-Z0-9_-]+

Required: Yes

includeResult

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.

targetArn

The Amazon Resource Number (ARN) of the device on which the command execution is being performed.

Length Constraints: Maximum length of 2048.

Required: Yes

Request Body

The request does not have a request body.

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "commandArn": "string",
   "completedAt": number,
   "createdAt": number,
   "executionId": "string",
   "executionTimeoutSeconds": number,
   "lastUpdatedAt": number,
   "parameters": { 
      "string" : { 
         "B": boolean,
         "BIN": blob,
         "D": number,
         "I": number,
         "L": number,
         "S": "string",
         "UL": "string"
      }
   },
   "result": { 
      "string" : { 
         "B": boolean,
         "BIN": blob,
         "S": "string"
      }
   },
   "startedAt": number,
   "status": "string",
   "statusReason": { 
      "reasonCode": "string",
      "reasonDescription": "string"
   },
   "targetArn": "string",
   "timeToLive": number
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

commandArn

The Amazon Resource Number (ARN) of the command. For example, arn:aws:iot:<region>:<accountid>:command/<commandId>

Type: String

completedAt

The timestamp, when the command execution was completed.

Type: Timestamp

createdAt

The timestamp, when the command execution was created.

Type: Timestamp

executionId

The unique identifier of the command execution.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: [a-zA-Z0-9_-]+

executionTimeoutSeconds

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.

Type: Long

Valid Range: Minimum value of 1.

lastUpdatedAt

The timestamp, when the command execution was last updated.

Type: Timestamp

parameters

The list of parameters that the StartCommandExecution API used when performing the command on the device.

Type: String to CommandParameterValue object map

Map Entries: Maximum number of items.

Key Length Constraints: Minimum length of 1. Maximum length of 192.

Key Pattern: ^[.$a-zA-Z0-9_-]+$

result

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.

Note

If you use the AWS-IoT-FleetWise namespace, then this field is not applicable in the API response.

Type: String to CommandExecutionResult object map

Map Entries: Maximum number of items.

Key Length Constraints: Minimum length of 1. Maximum length of 32.

Key Pattern: [a-zA-Z0-9_-]+

startedAt

The timestamp, when the command execution was started.

Type: Timestamp

status

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.

Type: String

statusReason

Your devices can use this parameter to provide additional context about the status of a command execution using a reason code and description.

Type: StatusReason object

targetArn

The Amazon Resource Number (ARN) of the device on which the command execution is being performed.

Type: String

Length Constraints: Maximum length of 2048.

timeToLive

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.

Type: Timestamp

Errors

InternalServerException

Internal error from the service that indicates an unexpected error or that the service is unavailable.

HTTP Status Code: 500

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

ValidationException

The request is not valid.

HTTP Status Code: 400