Using the command created with the CreateCommand API, start a command
execution on a specific device.
Note
The IAM permissions are derived from the iot:StartCommandExecution
action. For more information on the IAM permissions policy statement, see Start a command execution (AWS CLI) > Sample IAM
policy.
Request Syntax
POST /command-executions HTTP/1.1
Content-type: application/json
{
"clientToken": "string",
"commandArn": "string",
"executionTimeoutSeconds": number,
"parameters": {
"string" : {
"B": boolean,
"BIN": blob,
"D": number,
"I": number,
"L": number,
"S": "string",
"UL": "string"
}
},
"targetArn": "string"
}URI Request Parameters
The request does not use any URI parameters.
Request Body
The request accepts the following data in JSON format.
- clientToken
-
The client token is used to implement idempotency. It ensures that the request completes no more than one time. If you retry a request with the same token and the same parameters, the request will complete successfully. However, if you retry the request using the same token but different parameters, an HTTP 409 conflict occurs. If you omit this value, AWS SDKs will automatically generate a unique client request.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern:
^[\x21-\x7E]+$Required: No
- commandArn
-
The Amazon Resource Number (ARN) of the command. For example,
arn:aws:iot:<region>:<accountid>:command/<commandName>Type: String
Required: Yes
- executionTimeoutSeconds
-
Specifies the amount of time in second the device has to finish the command execution. A timer is started as soon as 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.
Required: No
- parameters
-
A list of parameters that are required by the
StartCommandExecutionAPI when performing the command on a 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_-]+$Required: No
- targetArn
-
The Amazon Resource Number (ARN) of the device where the command execution is occurring.
Type: String
Length Constraints: Maximum length of 2048.
Required: Yes
Response Syntax
HTTP/1.1 200
Content-type: application/json
{
"executionId": "string"
}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.
- executionId
-
A unique identifier for the command execution.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern:
[a-zA-Z0-9_-]+
Errors
- ConflictException
-
A conflict has occurred when performing the API request.
HTTP Status Code: 409
- InternalServerException
-
An internal server error occurred when performing the API request.
HTTP Status Code: 500
- ResourceNotFoundException
-
The specified resource does not exist.
HTTP Status Code: 404
- ServiceQuotaExceededException
-
The service quota has been exceeded for this request.
HTTP Status Code: 402
- ThrottlingException
-
The rate exceeds the limit.
HTTP Status Code: 400
- ValidationException
-
A validation error occurred when performing the API request.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
