Creates a Cloud Assistant command.
Description
- You can create commands of the following types:
- RunBatScript: batch commands, applicable to Windows instances
- RunPowerShellScript: PowerShell commands, applicable to Windows instances
- RunShellScript: shell commands, applicable to Linux instances
- You can specify the TimeOut parameter to set the maximum timeout period for command
executions on Elastic Compute Service (ECS) instances. When a command execution times
out, the Cloud Assistant client forcefully terminates the execution by canceling the
process ID (PID) of the command. For more information, see Install the Cloud Assistant client.
- One-time execution: After an execution times out, the state of the execution (InvokeRecordStatus) on specific instances becomes Failed.
- Recurring execution:
- The timeout period takes effect on each execution.
- After an execution times out, the state of the execution (InvokeRecordStatus) becomes Failed.
- The timeout of each execution does not affect the next execution.
- Within each region, you can retain a maximum of 100 Cloud Assistant commands. You can also submit a ticket to increase the command quota.
- You can use the WorkingDir parameter to specify the working directory of a Cloud Assistant
command. For Linux instances, the default working directory of a command is the home
directory of the root user, which is
/root
. For Windows instances, the default working directory of a command is the directory where the Cloud Assistant client process resides, such as C:\Windows\System32. - You can enable the custom parameter feature for a Cloud Assistant command by setting
EnableParameter to true when you create the command. When you set the CommandContent
parameter, you can define custom parameters in the {{parameter}} format. Then, when
the InvokeCommand operation is called, the key-value pairs of custom parameters can be passed in. For
example, if a command content is
echo {{name}}
, the Parameters parameter can be used to pass in the<name, Jack>
key-value pair when the InvokeCommand operation is called. The name key of the custom parameter is automatically replaced by the paired Jack value to generate a new command. As a result, theecho Jack
command is actually run.
Debugging
Request parameters
Parameter | Type | Required | Example | Description |
---|---|---|---|---|
Action | String | Yes | CreateCommand |
The operation that you want to perform. Set the value to CreateCommand. |
RegionId | String | Yes | cn-hangzhou |
The region ID of the command. You can call the DescribeRegions operation to query the most recent region list. |
Name | String | Yes | testName |
The name of the command. The name supports all character sets and can be up to 128 characters in length. |
Description | String | No | testDescription |
The description of the command. The description supports all character sets and can be up to 512 characters in length. |
Type | String | Yes | RunShellScript |
The command type. Valid values:
|
CommandContent | String | Yes | ZWNobyAxMjM= |
The Base64-encoded content of the command.
|
WorkingDir | String | No | /root/ |
The working directory of the command on the instance. Default value:
|
Timeout | Long | No | 60 |
The maximum timeout period for the command execution on the instance. Unit: seconds. When a command cannot be run, the command execution times out. When the execution times out, the command process is forcefully terminated by canceling the PID of the command. Default value: 60. |
EnableParameter | Boolean | No | false |
Specifies whether to use custom parameters in the command. Default value: false. |
Response parameters
Parameter | Type | Example | Description |
---|---|---|---|
CommandId | String | c-7d2a745b412b4601b2d47f6a768d**** |
The ID of the command. |
RequestId | String | 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E |
The ID of the request. |
Examples
Sample requests
https://ecs.aliyuncs.com/?Action=CreateCommand
&CommandContent=ZWNobyB7e25hbWV9fSA=
&Name=testName
&RegionId=cn-hangzhou
&Type=RunShellScript
&Description=testDescription
&WorkingDir=/root/
&Timeout=60
&EnableParameter=true
&<Common request parameters>
Sample success responses
XML
format
HTTP/1.1 200 OK
Content-Type:application/xml
<CreateCommandResponse>
<RequestId>E69EF3CC-94CD-42E7-8926-F133B86387C0</RequestId>
<CommandId>c-7d2a745b412b4601b2d47f6a768d****</CommandId>
</CreateCommandResponse>
JSON
format
HTTP/1.1 200 OK
Content-Type:application/json
{
"RequestId" : "E69EF3CC-94CD-42E7-8926-F133B86387C0",
"CommandId" : "c-7d2a745b412b4601b2d47f6a768d****"
}
Error codes
HTTP status code | Error code | Error message | Description |
---|---|---|---|
400 | RegionId.ApiNotSupported | The api is not supported in this region. | The error message returned because the API operation cannot be called in the specified region. Check whether the RegionId parameter is valid. |
403 | InvalidCmdType.NotFound | The specified command type does not exist. | The error message returned because the specified Type parameter does not exist. |
403 | CmdContent.ExceedLimit | The length of the command content exceeds the upper limit. | The error message returned because the length of the command content exceeds the upper limit. |
403 | CmdName.ExceedLimit | The length of the command name exceeds the upper limit. | The error message returned because the command name exceeds 128 characters in length. |
403 | CmdDesc.ExceedLimit | The length of the command description exceeds the upper limit. | The error message returned because the command description exceeds 512 characters in length. |
403 | CmdCount.ExceedQuota | The total number of commands in the current region exceeds the quota. | The error message returned because the maximum number of Cloud Assistant commands in the current region has been reached. |
403 | CmdParam.EmptyKey | You must specify the parameter names. | The error message returned because some required parameters are not specified. |
403 | CmdParam.InvalidParamName | Invalid parameter name. The name can contain only lowercase letters (a to z), uppercase letters (A to Z), numbers (0 to 9), hyphens (-), and underscores (_). | The error message returned because the custom parameter name is invalid. A custom parameter name can contain only letters, digits, underscores (_), and hyphens (-). |
403 | CmdParamCount.ExceedLimit | The maximum number of custom parameters is exceeded | The error message returned because the number of specified custom parameters exceeds the upper limit. |
403 | CmdParamName.ExceedLimit | The maximum length of a parameter name is exceeded. | The error message returned because the maximum length of the custom parameter name has been reached. |
403 | Operation.Forbidden | The operation is not permitted. | The error message returned because the operation is not supported. |
500 | InternalError.Dispatch | An error occurred when you dispatched the request. | The error message returned because an error occurred when the request was being sent. Try again later. |
For a list of error codes, visit the API Error Center.