You can call this operation to create a Cloud Assistant script of the shell, PowerShell, or batch type , and run the script on one or more ECS instances.

Description

Different from CreateCommand and InvokeCommand, RunCommand can create and run a script within a single request.

When you call this operation, take note of the following:

  • The target instance must be a VPC-type instance.
  • The target instance must be in the Running state.
  • The target instance has been installed with the Cloud Assistant client (InstallCloudAssistant).
  • Before you run a PowerShell script, make sure that the target Windows instance has been installed with the PowerShell module.
  • The period of recurring tasks is set based on UTC and the system time of the instance. The time or time zone of the ECS instance must meet your business needs. For more information about time zones, see Set the time zone and NTP service for Linux instances or Set the NTP service for Windows instances.
  • You can specify the TimeOut parameter to set the maximum timeout period for a script execution task on ECS instances. After a script execution task times out, the Cloud Assistant client forces the process to stop.
    • After a single script execution task times out, the execution state (InvokeRecordStatus) of the script becomes Failed.
    • The timeout period of recurring tasks is valid for the record of each task. The timeout of the previous task does not affect the next task. After an execution task times out, the execution state of the script (InvokeRecordStatus) becomes Failed.
  • Scripts may fail to be executed because of the status exceptions of target instances, network exceptions, or the exceptions of the Cloud Assistant client. If an execution task fails, no execution information is generated.
  • EnableParameter=true: This setting enables the function of customizing parameters. When setting CommandContent, you can specify custom parameters in the {{$(parameter)}} format and pass in these parameters in key-value pairs when running the script.
  • In a region, you can retain a maximum of 100 to 10,000 Cloud Assistant scripts and run a maximum of 2,000 to 200,000 Cloud Assistant scripts every day based on your ECS usage. You can call the DescribeAccountAttribute operation to query quotas. If needed, you can submit ticket to modify the maximum number of Cloud Assistant scripts that you can retain and the maximum number of calls every day.

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
RegionId String Yes cn-hangzhou

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

InstanceId.N RepeatList Yes i-bp185dy2o3o6n******

The IDs of the ECS instances. Valid values of N: 1 to 50.

If multiple instances are specified and one of them does not meet the execution conditions, you must re-specify the IDs of all the instances.

Name String Yes Test

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

Type String Yes RunShellScript

The language type of the O&M script. Valid values:

  • RunBatScript: batch scripts for Windows instances
  • RunPowerShellScript: PowerShell scripts for Windows instances
  • RunShellScript: shell scripts for Linux instances
CommandContent String Yes ZWNobyAxMjM=

The plaintext content or the Base64-encoded content of the script. The Base64-encoded script content cannot exceed 16 KB.

You can enable the custom parameter function by setting EnableParameter=true in the script content:

  • Define custom parameters in the {{}} format. Within {{}}, the spaces and line breaks before and after the name of the parameter 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 key cannot exceed 64 bytes.
Action String No RunCommand

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

ContentEncoding String No Base64

The encoding mode of script content (CommandContent). Valid values (case insensitive):

  • PlainText: The script content is not encoded, and transmitted in plaintext.
  • Base64: base64-encoded.

Default value: PlainText. If the specified value of this parameter is invalid, PlainText is used by default.

Description String No RunCommand-Test

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

Timeout Long No 3600

The timeout period for script execution. Unit: seconds. A timeout error occurs when a script cannot be run because the process slows down, a specific module or the Cloud Assistant client does not exist. When the script times out, the script process is forcibly terminated.

Default value: 3600.

WorkingDir String No /home/

The running directory of the script in the ECS instance.

Default value:

  • Linux instances: under the home directory of the administrator (root user): /root.
  • Windows instances: under the directory where the process of the Cloud Assistant client is located, such as C:\ProgramData\aliyun\assist\$(version).
Timed Boolean No true

Specifies whether to periodically run the script. Valid values:

  • true: runs the script on a regular basis based on the value set for the Frequency parameter. The result of the previous execution task does not affect the next execution task.
  • false: runs once only.

Default value: false

Frequency String No 0 */20 * * * *

The execution period of recurring tasks. If the Timed parameter is set to True, you must specify the Frequency parameter. The interval between two recurring tasks cannot be less than 10 seconds.

The parameter value follows the cron expression. For more information, see Configure scheduled commands.

EnableParameter Boolean No false

Specifies whether the script contains custom parameters.

Default value: false

Parameters Json No {"name":"Jack", "accessKey":"LTAIdyv******aRY"}

The key-value pairs of custom parameters passed in when the script contains custom parameters. For example, if the script content is echo {{name}}, the Parameters parameter can be used to pass in the {"name":"Jack"} key-value pair. The variable name of the custom parameter is automatically replaced to generate a new script. Therefore, echo Jack is actually run.

Number of custom parameters: 0 to 10.

  • The key cannot be an empty string. It can be up to 64 characters in length.
  • The value can be an empty string.
  • After the custom parameters and the original script content are Base64 encoded, the total size cannot exceed 16 KB.
  • The set of custom parameter names must be a subset of the parameter set that is defined when you created the script. You can use an empty string to represent the parameters that are not passed in.

Default value: null, indicating that this parameter is canceled and customer parameters are disabled.

KeepCommand Boolean No false

Specifies whether to retain the script after it is run. Valid values:

  • true: The script is retained. You can call the InvokeCommand operation to run the script again, call the DescribeCommands operation to query the script, and call the DeleteCommands operation to delete the script. The retained script takes up the quota of Cloud Assistant scripts.
  • false: The script is not retained. It is automatically deleted after running, without taking up the quota of Cloud Assistant scripts.

Default value: false

Response parameters

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

The ID of the script.

InvokeId String t-7d2a745b412b4601b2d47f6a768d3***

The ID of script running.

RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.

Examples

Sample requests

http(s)://ecs.aliyuncs.com/? Action=RunCommand
&CommandContent='echo hello'
&InstanceId.1=i-bp185dy2o3o6n******
&Name=RunCommandTest
&RegionId=cn-hangzhou
&Type=RunShellScript
&<Common request parameters>

Sample success responses

XML format

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

JSON format

{
	"RequestId":"E69EF3CC-94CD-42E7-8926-F133B86387C0",
	"InvokeId":"t-7d2a745b412b4601b2d47f6a768d3***",
	"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 unknown error has occurred.
403 InvalidCmdType.NotFound The specified command type does not exist. The error message returned because the specified script type does not exist.
403 CmdName.ExceedLimit The length of the command name exceeds the upper limit. The error message returned because the maximum length of script name has been reached. Use a shorter script name.
403 CmdDesc.ExceedLimit The length of the command description exceeds the upper limit. The error message returned because the script description exceeds the maximum length. Use a shorter script description.
403 CmdCount.ExceedQuota The total number of commands in the current region exceeds the quota. The error message returned because the number of Cloud Assistant scripts in the current region exceeds the upper limit.
404 InvalidInstance.NotFound The specified instance does not exist. The error message returned because the specified instance does not exist.
403 MissingParam.Frequency The frequency must be specified when you create a timed task. The error message returned because no execution frequency is set for the recurring tasks.

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