Triggers a Cloud Assistant command on one or more Elastic Compute Service (ECS) instances.

Description

  • ECS instances on which to run the Cloud Assistant command must meet the following requirements. If you specify multiple ECS instances and one of the instances does not meet the requirements for running the command, the call fails. Specify instances that meet the requirements and call the InvokeCommand operation again.
    • The network type is Virtual Private Cloud (VPC). For more information, see What is a VPC?
    • The instances are in the Running (Running) state.
    • The Cloud Assistant client is installed on the instances. For more information, see Install the Cloud Assistant client.
    • Before you run PowerShell commands, make sure that the instances have the PowerShell module configured.
  • If Timed is set to false, the command is run only once.
  • If Timed is set to true, the command is run on a schedule.
    • The schedule is specified by Frequency parameter. The results of each execution of a command do not affect the next execution of the command.
    • If you want to specify a schedule by using a cron expression, you can set a time zone based on your requirements. If you do not set a time zone, the schedule is based on the system time of the instance. Make sure that the time or time zone of the instance meets your business needs. For more information, see Configure the NTP service and time zone for Linux instances or Configure the NTP service for Windows instances.

      To ensure that scheduled tasks can run as expected, make sure that the version of the Cloud Assistant client is not earlier than the following ones. A scheduled task can run a command at a specified interval, only once at a specified time, or at designated times based on a cron expression with a specified year or time zone. If the ClientNeedUpgrade error code is returned, you must upgrade the Cloud Assistant client to the latest version. For more information, see Update or disable updates for the Cloud Assistant client.

      • Linux: 2.2.3.282
      • Windows: 2.1.3.282
  • Command executions may fail due to instance status exceptions, network exceptions, or exceptions on the Cloud Assistant client. If an execution fails, no execution information is generated.
  • If you enable the custom parameter feature by setting EnableParameter to true when you create a command, you must specify custom parameters (Parameters) when you run the command.

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 InvokeCommand

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

RegionId String Yes cn-hangzhou

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

CommandId String Yes c-e996287206324975b5fbe1d****

The ID of the command. You can call the DescribeCommands operation to query all available command IDs.

Note Common Cloud Assistant commands can be run based on their names. For more information, see View and run common Cloud Assistant commands.
RepeatMode String No Once

The execution mode of the command. Valid values:

  • Once: runs the command instantly.
  • Period: runs the command on a schedule. If you set this parameter to Period, you must set Timed to true and specify Frequency.
  • NextRebootOnly: automatically runs the command the next time the instance starts.
  • EveryReboot: automatically runs the command every time the instance starts.

Default value:

  • When Timed is not set to true and Frequency is not specified, the default value of RepeatMode is Once.
  • When Timed is set to true and Frequency is specified, Period is used as the value of RepeatMode regardless of whether RepeatMode is specified.

Take note of the following items:

  • When this parameter is set to Period, NextRebootOnly, or EveryReboot, you can call the StopInvocation operation to stop the pending or scheduled execution of the command.
  • When this parameter is set to Period or EveryReboot, you can call the DescribeInvocationResults operation with IncludeHistory set to true to view the results of historical scheduled executions.
Timed Boolean No true

Specifies whether to run the command on a schedule. Valid values:

  • true: runs the command on the schedule specified by Frequency. The results of each execution do not affect the next execution.
  • false: runs the command only once.

Default value: false.

Frequency String No 0 */20 * * * ?

The schedule on which to run the command. You must specify this parameter when you set Timed to true. You can specify a schedule to run the command at a fixed interval based on a rate expression, only once at a specified time, or at designated times based on a cron expression.

  • To run a command at a fixed interval, use a rate expression to specify the interval. You can specify the interval in seconds, minutes, hours, or days. This option is applicable when tasks need to be executed at a fixed interval. Specify the interval in the following format: rate(<Interval value><Interval unit>). For example, specify rate(5m) to run the command every 5 minutes. Take note of the following limits when you set an interval:
    • The specified interval can be anywhere from 60 seconds to 7 days and must be longer than the timeout period of the scheduled task.
    • The interval is the duration between two consecutive executions. The interval is irrelevant to the amount of time required to run the command once. For example, assume that you set the interval to 5 minutes and that it takes 2 minutes to run the command each time. Each time the command is run, the system waits 3 minutes before it runs the command again.
    • A task is not executed immediately after it is created. For example, assume that you set the interval to 5 minutes for a task. The task begins to be executed 5 minutes after it is created.
  • To run a command only once at a specified time, specify a point in time and a time zone. Specify the time in the following format: at(yyyy-MM-dd HH:mm:ss <Time zone>), which indicates at(Year-Month-Day Hour:Minute:Second <Time zone>). If you do not specify a time zone, the UTC time zone is used by default. The time zone supports the following forms:
    • The time zone name. Examples: Asia/Shanghai and America/Los_Angeles.
    • The time offset from GMT. Example: GMT+8:00 (UTC+8) and GMT-7:00 (UTC-7). If you use the GMT format, do not pad leading zeros to the hour value.
    • The time zone abbreviation: Only UTC is supported.

      To specify a command to run only once at 13:15:30 on June 06, 2022 (Shanghai time), set the time to at(2022-06-06 13:15:30 Asia/Shanghai). To specify a command to run only once at 13:15:30 on June 06, 2022 (UTC-7), set the time to at(2022-06-06 13:15:30 GMT-7:00).

  • To run a command at designated times, specify a cron expression. Specify the time in the following format: <Cron expression> <time zone>, where the cron expression is in the format of <seconds> <minutes> <hours> <day of the month> <month> <day of the week> <year (optional)>. The system calculates the execution times of the command based on the specified cron expression and time zone and runs the command as scheduled. If you do not specify a time zone, the system time zone of the instance on which to run the command is used by default. For more information about cron expressions, see Cron expressions. The time zone supports the following forms:
    • The time zone name. Examples: Asia/Shanghai and America/Los_Angeles.
    • The time offset from GMT. Example: GMT+8:00 (UTC+8) and GMT-7:00 (UTC-7). If you use the GMT format, do not pad leading zeros to the hour value.
    • The time zone abbreviation: Only UTC is supported.

      For example, to specify a command to run at 10:15:00 every day in 2022 (Shanghai time), set the time to 0 15 10 ? * * 2022 Asia/Shanghai. To specify a command to run every half an hour from 10:00:00 to 11:30:00 every day in 2022 (UTC+8), set the time to 0 0/30 10-11 * ? 2022 GMT +8:00. To specify a command to run every 5 minutes from 14:00:00 to 14:55:00 every October every two years since 2022 (UTC), set the time to 0 0/5 14 * 10 ? 2022/2 UTC.
      Note The minimum interval must be 10 seconds or more and cannot be shorter than the timeout period of scheduled executions.
Parameters Map No {"name":"Jack", "accessKey":"LTAIdyv******aRY"}

The key-value pairs of custom parameters to pass in when the custom parameter feature is enabled. Number of custom parameters: 0 to 10.

  • Keys in a Map collection can be up to 64 characters in length and cannot be empty strings.
  • Values in a Map collection can be empty strings.
  • The size of the command (including custom parameters and original command content) after Base64 encoding cannot exceed 16 KB.
  • The custom parameter names specified in the value of Parameters must be included in the custom parameters specified when you created the command. You can use empty strings to represent the parameters that are not passed in.

You can leave this parameter empty to disable the custom parameter feature.

Username String No root

The username to use to run the command on ECS instances.

  • For Linux instances, the root username is used.
  • For Windows instances, the System username is used.

You can also specify other usernames that already exist in the ECS instance to run the command. For security purposes, we recommend that you run Cloud Assistant commands as a regular user. For more information, see Configure a regular user to run Cloud Assistant commands.

WindowsPasswordName String No axtSecretPassword

The name of the password to use to run the command on a Windows instance.

If you want to use a username other than the default System username to run the command on the Windows instance, you must specify both the WindowsPasswordName and Username parameters. The password is hosted in plaintext in the parameter repository of Operation Orchestration Service (OOS) to reduce the risk of password leaks. Only the name of the password is passed in by using the WindowsPasswordName parameter. For more information, see Manage encryption parameters and Run Cloud Assistant commands as a regular user.

Note When you use the root username for Linux instances or the System username for Windows instances to run the command, you do not need to specify the WindowsPasswordName parameter.
InstanceId.N String Yes i-bp185dy2o3o6n****

The ID of instance N on which to run the command. You can specify up to 50 instance IDs in each request. Valid values of N: 1 to 50.

Response parameters

Parameter Type Example Description
InvokeId String t-7d2a745b412b4601b2d47f6a768d****

The ID of the task.

RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3****

The ID of the request.

Examples

Sample requests

http(s)://ecs.aliyuncs.com/?Action=InvokeCommand
&CommandId=c-e996287206324975b5fbe1d****
&InstanceId.1=i-bp185dy2o3o6n****
&RegionId=cn-hangzhou
&Timed=true
&Frequency=0 */20 * * * *
&Parameters={"name":"Jack", "accessKey":"LTAIdyv******aRY"}
&Username=root
&<Common request parameters>

Sample responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<InvokeCommandResponse>
    <InvokeId>t-7d2a745b412b4601b2d47f6a768d****</InvokeId>
    <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3****</RequestId>
</InvokeCommandResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "InvokeId" : "t-7d2a745b412b4601b2d47f6a768d****",
  "RequestId" : "473469C7-AA6F-4DC5-B3DB-A3DC0DE3****"
}

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 InvalidInstance.NotMatch The specified instance type does not match the command. The error message returned because the specified command cannot be run on the specified ECS instance. Check whether the state of the instance meets the conditions for running the command.
403 MissingParam.Frequency The frequency must be specified when you create a timed task. The error message returned because the Frequency parameter is not specified when you set Timed to true.
403 InvalidParam.Frequency The specified frequency is invalid. The error message returned because the specified Frequency parameter is invalid.
403 InstanceIds.ExceedLimit The number of instance IDs exceeds the upper limit. The error message returned because the number of specified instance IDs exceeds the upper limit.
403 Invocation.ExceedQuota The invocation quota in the current region has been reached for today. The error message returned because the daily maximum number of command executions in the specified region is reached.
403 ParameterCount.ExceedLimit The maximum number of parameters is exceeded. The error message returned because the number of specified custom parameters exceeds the upper limit.
403 ParameterKey.ExceedLimit The maximum length of a parameter name is exceeded. The error message returned because the key of a custom parameter exceeds 64 characters in length.
403 CmdContent.ExceedLimit The maximum length of a command is exceeded. The error message returned because the length of the command exceeds the upper limit. Shorten your command.
403 ParameterKey.Duplicate Parameter names cannot be duplicated. The error message returned because a parameter that has the same name already exists. Parameter names must be unique.
403 Parameter.NotMatched The passed-in parameters do not match the parameters defined when you created the command. The error message returned because the custom parameters passed in do not match those specified when the command was created.
403 Username.ExceedLimit The length of the username exceeds the upper limit. The error message returned because the length of the username exceeds the upper limit.
403 Operation.Forbidden The operation is not permitted. The error message returned because the operation is not supported.
403 Parameter.MissingValue The parameter value of this command is required. The error message returned because the required parameter is not specified.
404 InvalidRepeatMode.NotFound The specified repeat mode does not exist. The error message returned because the specified RepeatMode parameter does not exist.
404 InvalidInstance.NotFound The specified instance does not exist. The error message returned because the specified ECS instance does not exist.
404 InvalidCmdId.NotFound The specified command ID does not exist. The error message returned because the specified CommandId parameter is invalid. You can call the DescribeCommands operation to query all available command IDs.
404 Parameter.Disabled Parameters cannot be passed in when the command customization function is disabled. The error message returned because Parameters is specified when the custom parameter feature is disabled.
500 InternalError.Dispatch An error occurred when you dispatched the request. The error message returned because an error occurred while the request was being sent. Try again later.

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