You can call this operation to trigger a Cloud Assistant command on one or more ECS instances.

Description

  • You can call the InvokeCommand operation in a region up to 5,000 times a day. To adjust the maximum number of daily calls, submit a ticket.
  • The target ECS instances have the following limits. After multiple ECS instances are selected, if one of the instances does not meet the invocation conditions, you must call the InvokeCommand operation again.
    • The network type must be VPC. For more information, see Virtual Private Cloud.
    • The target instances must be in the Running (Running) state.
    • The target instances must be preinstalled with the Cloud Assistant client. For more information, see The Cloud Assistant client.
    • Before you invoke PowerShell commands, make sure that the target instances have the PowerShell feature configured.
  • One-time invocations (Timed=false): The Cloud Assistant client invokes commands only once.
  • Periodic invocations (Timed=true):
    • The Cloud Assistant client invokes commands at the frequency specified by the Frequency parameter. The result of previous invocation does not affect the current invocation.
    • The period of periodic invocations is set based on UTC and the system time of the instance. If the system time of your ECS instances are not based on UTC, make sure that you have made adjustments to ensure that your commands are invoked at the correct time. For more information, see Synchronize NTP servers and change the time zone for Linux instances or Synchronize NTP servers for Windows instances.
  • Command invocations may fail because of target instance status exceptions, network exceptions, or Cloud Assistant client exceptions. If an invocation fails, no invocation information is generated.
  • If you enable the custom parameter feature by setting EnableParameter=true when you create a command, you must specify the value of the custom parameter (Parameters) when you invoke 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
CommandId String Yes c-e996287206324975b5fbe1d********

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

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

The ID of instance N where the command need to be invoked. You can specify up to 50 instance IDs in each request. Valid values of N: 1 to 50.

RegionId String Yes cn-hangzhou

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

Action String Yes InvokeCommand

The operation that you want to perform. Set the value to InvokeCommand.
Frequency String No 0 */20 * * * *

The interval at which a periodic task is invoked. The interval between two consecutive calls cannot be less than 10 seconds. When the Timed parameter is set to true, you must specify the Frequency parameter.

The value of this parameter is expressed in cron. For more information, see Configure scheduled commands.

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

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

  • The key of Map cannot be an empty string. It can be up to 64 characters in length.
  • The value of Map can be an empty string.
  • After the custom parameters and the original command 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 command. You can use empty strings to represent the parameters that are not passed in.

You can leave the parameter empty to disable the custom parameter feature.
Timed Boolean No true

Specifies whether to invoke the command on a periodic basis.

Default value: false.

Response parameters

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

The ID of the command invocation.
RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.

Examples

Sample requests


https://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"}
&<Common request parameters>

Sample success responses

XML format 

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

JSON format 

{
	"RequestId":"E69EF3CC-94CD-42E7-8926-F133B86387C0",
	"InvokeId":"t-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.
404 InvalidInstance.NotFound The specified instance does not exist. The error message returned because the specified InstanceId parameter does not exist.
403 MissingParam.Frequency The frequency must be specified when you create a timed task. The error message returned because no frequency is set for the periodic invocation.
404 Parameter.Disabled Parameters cannot be passed in when the command customization function is disabled. The error message returned because you specify custom parameter values when you disable the custom parameter feature.
403 ParameterCount.ExceedLimit The maximum number of parameters is exceeded. The error message returned because the maximum number of custom parameters has been reached.
403 ParameterKey.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 CmdContent.ExceedLimit The maximum length of a command is exceeded. The error message returned because the command length exceeds the upper limit. Simplify your command.
403 ParameterKey.Duplicate Parameter names cannot be duplicated. The error message returned because the parameter name already exists.
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 defined when the command was created.

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