You can call this operation to create a Cloud Assistant command.

Description

  • You can create commands of the following types:
    • Batch commands for Windows instances: RunBatScript
    • PowerShell commands for Windows instances: RunPowerShellScript
    • Shell commands for Linux instances: RunShellScript
  • You can specify the TimeOut parameter to set the maximum timeout period for command invocations on ECS instances. When a command invocation times out, the Cloud Assistant client will force the command process to stop by canceling the PID (process ID) of the command.
    • For one-time invocation: After an invocation times out, the state of the command invocation (InvokeRecordStatus) on the specified ECS instance becomes Failed.
    • For periodic invocation:
      • The timeout period of periodic invocation is effective for every invocation record.
      • After an invocation times out, the status of the invocation record (InvokeRecordStatus) becomes Failed.
      • The timeout of previous invocation does not affect current invocation.
  • You can create up to 100 cloud Assistant commands in a region. You can also submit a ticket to increase the upper limit.
  • You can use the WorkingDir parameter to specify the execution path of the command. For Linux instances, by default the invocation path of the command is the home directory of the root user, which is /root. For Windows instances, by default the invocation path of the command is the directory where the Cloud Assistant client process resides, such as C:\Windows\System32\.
  • You can enable the custom parameter feature on a Cloud Assistant command by setting EnableParameter=true when you create the command. When you set the CommandContent parameter, you can use the {{parameter}} format to indicate a custom parameter. Then, when you call the InvokeCommand operation, you can enter the key-value pair of the custom parameter. For example, if you create a command named echo {{name}}, when you call the InvokeCommand operation, you must set Parameters to<name, Jack>. The custom parameter will automatically change the command to a new one. Therefore, the echo Jack command is actually executed on the instance.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request Parameters

Parameter Type Required Example Description
Action String Yes CreateCommand

The operation that you want to perform. Set the value to CreateCommand.

CommandContent String Yes ZWNobyAxMjM=

The Base64-encoded content of the command.

  • The parameter value must be Base64-encoded and cannot exceed 16 KB in size after encoding.
  • Command content supports the custom parameter feature. You can enable the custom parameter feature by setting EnableParameter=true.
    • Custom parameters are defined in the {{}} format. Within {{}}, the spaces and line breaks before and after the parameter name are ignored.
    • The number of custom parameters cannot exceed 20.
    • A custom parameter name can contain only letters, digits, underscores (_), and hyphens (-). It is case insensitive.
    • Each custom parameter name cannot exceed 64 bytes.
Name String Yes Test

The name of the command, which supports all character sets. It can be up to 128 characters in length.

RegionId String Yes cn-hangzhou

The region ID of the Cloud Assistant command. You can call the DescribeRegions operation to query the most recent region list.

Type String Yes RunShellScript

The type of the command. Valid values:

  • RunBatScript: creates a batch command for a Windows instance.
  • RunPowerShellScript: creates a PowerShell command for a Windows instance.
  • RunShellScript: creates a Shell command for a Linux instance.
Description String No Test1

The description of the command, which supports all character sets. It can be up to 512 characters in length.

WorkingDir String No /root/

The execution path of the command in the ECS instance.

Default value:

  • Linux instance: the home directory of the root user, which is the /root directory.
  • Windows instance: the directory where the Cloud Assistant client process resides, such as C:\Windows\System32\.
Timeout Long No 60

The timeout period that is specified for the command to invoke on ECS instances. Unit: seconds. When a command that you created cannot be invoked, the command times out. When a command invocation times out, the Cloud Assistant client will force the command process to stop by canceling the PID of the command.

Default value: 60.

EnableParameter Boolean No false

Specifies whether the created command uses custom parameters.

Default value: false.

Response parameters

Parameter Type Example Description
CommandId String c-7d2a745b412b4601b2d47f6a768d3***

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=Test
&RegionId=cn-hangzhou
&Type=RunShellScript
&Description=Test1
&WorkingDir=/root/
&Timeout=60
&EnableParameter=true
&<Common request parameters>

Sample success responses

XML format

<CreateCommandResponse>
      <RequestId>E69EF3CC-94CD-42E7-8926-F133B86387C0</RequestId>
      <CommandId>c-7d2a745b412b4601b2d47f6a768d3***</CommandId>
</CreateCommandResponse>

JSON format

{
    "RequestId": "E69EF3CC-94CD-42E7-8926-F133B86387C0",
    "CommandId": "c-7d2a745b412b4601b2d47f6a768d3***"
}

Error codes

HTTP status code Error code Error message Description
500 InternalError.Dispatch An error occurred when you dispatched the request. The error message returned because an error occurred while the request is sent. Try again later.
403 InvalidCmdType.NotFound The specified command type does not exist. The error message returned because the specified command type does not exist.
403 CmdName.ExceedLimit The length of the command name exceeds the upper limit. The error message returned because the length of the command name exceeds the upper limit.
403 CmdDesc.ExceedLimit The length of the command description exceeds the upper limit. The error message returned because the length of the command description exceeds the upper limit.
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 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.

For a list of error codes, visit the API Error Center.