RunCommand_Elastic Compute Service_Documentation

Operation Description

This operation is an asynchronous operation. After a request is sent, a response that contains a command ID and a command task ID is immediately returned. You can call the DescribeInvocations or DescribeInvocationResults operation with the command ID or task ID to query the execution results of the command.

Precautions

The instances on which you want to create and run a Cloud Assistant command must be in the Running (Running) state. You can call the DescribeInstances operation to query the status of instances.
Cloud Assistant Agent must be pre-installed on the instances on which you want to create and run a Cloud Assistant command. You can call the InstallCloudAssistant operation to install Cloud Assistant Agent on instances and the DescribeCloudAssistantStatus operation to query whether Cloud Assistant Agent is installed on instances.

**

Note By default, Cloud Assistant Agent is pre-installed on instances created from public images on or after December 1, 2017.
Before you run a PowerShell command on a Windows instance, make sure that the PowerShell module is installed on the instance.

Considerations

You can retain up to 500 to 50,000 Cloud Assistant commands in each region. You can also request a quota increase. For information about how to view quotas and request a quota increase, see Manage quotas.
To ensure that scheduled tasks can run as expected, make sure that the Cloud Assistant Agent version is not earlier than the following versions. A scheduled task can run a command at a specific interval, only once at a specific time, or at designated times based on a cron expression in a specific year or time zone. If the ClientNeedUpgrade error code is returned, you must update Cloud Assistant Agent to the latest version. For more information, see Upgrade or disable upgrades of Cloud Assistant Agent.
```
- Linux: 2.2.3.282
- Windows: 2.1.3.282
```
When you use a cron expression to specify a schedule, you can specify a time zone based on your business requirements. If you do not specify a time zone, the schedule is determined by the system time of the instances. Make sure that the time or time zone of the instances meets your business requirements. For information about time zones, see Configure the NTP service for ECS instances that run CentOS 6 or Configure the NTP service for Windows instances.

Suggestions

Timeout settings: You can set Timeout to specify the timeout period for command executions on instances. If an execution times out, Cloud Assistant Agent forcefully terminates the command process.
- When the one-time execution of the command times out, the execution status ( InvokeRecordStatus ) of the command becomes Failed.
- For a scheduled task, the timeout period takes effect on every execution of the command. When a command execution times out, the subsequent executions of the command are not affected. When a scheduled execution of the command times out, the execution status ( InvokeRecordStatus ) of the command becomes Failed.
Execution failure: Command executions may fail due to instance status exceptions, network exceptions, or exceptions on Cloud Assistant Agent. If a command execution fails, no execution information is generated. For more information, see Check execution results and troubleshoot common issues.
Custom parameters: If you set EnableParameter to true, the custom parameter feature is enabled. When you specify CommandContent, you can define custom parameters in the {{parameter}} format. Then, the key-value pairs of the custom parameters are passed in when you run the command.

Quotas Info

The current API request rate is 1000/60(s).View More quotas information, please go to Quota Management View

Authorization Information

The following table shows the authorization information corresponding to this API, which can be used in the Action policy element to grant a RAM user or RAM role the permissions to call the API. Please use RAM to set up these permissions and refer to RAM documentation for more instructions.

Description:View Details...

Actions	Access level	Resource type	Condition key	Associated operation

ecs:RunCommand	Update	Instance acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}	ecs:CommandRunAs	None

Request Parameters

Field Name	Field Details
RegionIdstring	The region ID of the command. You can call the DescribeRegions operation to query the most recent region list. Example:cn-hangzhouReference Value Source: DescribeRegions
ResourceGroupIdstring	The ID of the resource group to which to assign the command executions. When you set this parameter, take note of the following items:View Details... Example:rg-bp67acfmxazb4p****Reference Value Source: DescribeSecurityGroups
Namestring	The name of the command. The name supports all character sets and can be up to 128 characters in length. Example:testName
Descriptionstring	The description of the command. The description supports all character sets and can be up to 512 characters in length. Example:testDescription
Typestring	The type of the command. Valid values:View Details... Example:RunShellScript
CommandContentstring	The content of the command. The command content can be plaintext or Base64-encoded. Take note of the following items:View Details... Example:ZWNobyAxMjM=
WorkingDirstring	The working directory of the command on the instance. The value can be up to 200 characters in length.View Details... Example:/home/user
Timeoutinteger<int64>	The timeout period for the command execution. Unit: seconds.View Details... Notice The field type is Long, and the precision may be lost during serialization/deserialization. Please note that the value must not be greater than 9007199254740991. Example:3600
EnableParameterboolean	Specifies whether to include custom parameters in the command.View Details... Example:false
RepeatModestring	Specifies how to run the command. Valid values:View Details... Example:Once
Timedboolean	Note This parameter is no longer used and does not take effect. Example:true
Frequencystring	The schedule on which to run the command. You can configure a command to run at a fixed interval based on a rate expression, run only once at a specified time, or run at designated times based on a cron expression.View Details... Example:0 /20 * * ?
Parametersobject	The key-value pairs of custom parameters to pass in when the command can include custom parameters. For example, the command content is `echo {{name}}`. You can use `Parameters` to pass in the `{"name":"Jack"}` key-value pair. The `name` key of the custom parameter is automatically replaced by the paired Jack value to generate a new command. As a result, the `echo Jack` command is run.View Details... Example:{"name":"Jack", "accessKey":"LTAIdyvdIqaRY****"}
KeepCommandboolean	Specifies whether to retain the command after the command is run. Valid values:View Details... Example:false
ContentEncodingstring	The encoding mode of command content (`CommandContent`). The valid values are case-insensitive. Valid values:View Details... Example:Base64
Usernamestring	The username to use to run the command on the ECS instances. The username cannot exceed 255 characters in length.View Details... Example:test
WindowsPasswordNamestring	The name of the password to use to run the command on a Windows instance. The name cannot exceed 255 characters in length.View Details... Example:axtSecretPassword
InstanceIdarray<string>	The IDs of instances on which to create and run the command. Specify at least one instance ID. You can specify up to 100 instance IDs.View Details... Example:i-bp185dy2o3o6neg****Count of Children <= 501
Tagarray<object>	The tags to add to the command task. You can leave this parameter empty or specify up to 20 tags. Count of Children <= 21
ContainerIdstring	The container ID. Only 64-bit hexadecimal strings are supported. `docker://`, `containerd://`, or `cri-o://` can be used as the prefix of the container ID to specify the container runtime.View Details... Example:ab141ddfbacfe02d9dbc25966ed971536124527097398d419a6746873fea****
ContainerNamestring	The container name.View Details... Example:test-container
ClientTokenstring	The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but you must make sure that the token is unique among different requests. The token can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence. Example:123e4567-e89b-12d3-a456-426655440000
ResourceTagarray<object>	The tags of the instance. You can leave this parameter empty or specify up to 20 tags. If you do not specify InstanceId, the command is run on instances that have the specified tags. Count of Children <= 11
TerminationModestring	Specifies how to stop the command task when a command execution is manually stopped or times out. Valid values:View Details... Example:ProcessTree
Launcherstring	The launcher for script execution. The value cannot exceed 1 KB in length. Example:python3 -u {{ACS::ScriptFileName\|Ext(".py")}}

Response Parameters

Field Name	Field Details
RequestIdstring	The request ID. Example:473469C7-AA6F-4DC5-B3DB-A3DC0DE3****
CommandIdstring	The command ID. Example:c-7d2a745b412b4601b2d47f6a768d****
InvokeIdstring	The command task ID. Example:t-7d2a745b412b4601b2d47f6a768d****

Sample Response

Change History

Examples

All Examples