调用InvokeCommand为一台或多台ECS实例触发一条云助手命令。

接口说明

  • 在一个阿里云地域下,您每天能调用5000次InvokeCommand接口。提交工单可以申请调整调用次数配额。
  • 对目标ECS实例有如下限制。选择了多台ECS实例后,若其中某台实例不满足执行条件,您需要重新调用接口。
    • 网络类型是专有网络VPC
    • 状态必须为运行中(Running)。
    • 已预先安装云助手客户端
    • 执行类型为PowerShell的命令时,实例必须已经配置了PowerShell模块。
  • 单次执行(Timed=false),只执行一次命令。
  • 周期执行(Timed=true):
    • 根据参数Frequency指定的时间频率定时执行,上次的执行结果不对下一次执行产生任何影响。
    • 当您基于Cron表达式执行周期任务且指定了时区,时钟定时执行时间设置基准为您指定的时区;当您没有指定时区时,时钟定时执行时间设置基准为ECS实例内的系统时区,且执行时间以实例的系统时间为准。请确保ECS实例的时间或者时区与您预期的时间一致。更多关于时区的详情,Linux实例请参见设置Linux实例时区和NTP服务,Windows实例请参见设置Windows实例NTP服务

      云助手客户端版本需要不低于以下对应的版本才能支持周期任务的新特性(固定时间间隔执行、仅在指定时间执行一次、基于Cron表达式定时执行时指定年份或时区)。如果结果返回ClientNeedUpgrade错误码,请参见升级或禁止升级云助手客户端,将客户端更新至最新版本。

      • Linux:2.2.3.282。
      • Windows:2.1.3.282。
  • 命令的执行可能会因为目标实例的状态异常、网络异常或云助手客户端异常而出现无法执行的情况,无法执行时不会生成执行信息。
  • 当您创建命令时启用了自定义参数功能,需要在执行命令时传入自定义参数(Parameters)。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称 类型 是否必选 示例值 描述
Action String InvokeCommand

系统规定参数。取值:InvokeCommand

RegionId String cn-hangzhou

地域ID。您可以调用DescribeRegions查看最新的阿里云地域列表。

CommandId String c-e996287206324975b5fbe1d****

命令ID。您可以通过接口DescribeCommands查询所有可用的CommandId。

说明 对于公共命令,可以通过命令名称执行。更多信息,请参见查看和执行云助手公共命令
RepeatMode String Once

设置命令执行的方式。取值范围:

  • Once:立即执行命令。
  • Period:定时执行命令。当该参数取值为Period时,必须同时指定Timed=true参数值以及Frequency参数。
  • NextRebootOnly:当实例下一次启动时,自动执行命令。
  • EveryReboot:实例每一次启动都将自动执行命令。

默认值:

  • 当不指定Timed=true参数值以及Frequency参数时,默认值为Once
  • 当指定Timed=true参数值以及Frequency参数时,无论是否已设置了该参数值,都将按照Period处理。

注意事项:

  • 当该参数取值PeriodNextRebootOnly或者EveryReboot时,您可以调用StopInvocation停止待执行的命令或周期执行的命令。
  • 当该参数取值Period或者EveryReboot时,您可以调用DescribeInvocationResults,然后指定IncludeHistory=true查看命令周期执行的历史记录。
Timed Boolean true

命令是否为周期执行。取值范围:

  • true:根据参数Frequency设置的时间频率定时执行。上次的执行结果不对下一次执行产生任何影响。
  • false:只执行一次。

默认值:false。

Frequency String 0 */20 * * * ?

周期执行命令的执行周期。当参数Timed的值为true时,该参数为必选参数。目前支持三种定时执行方式:固定时间间隔执行(基于Rate表达式)、仅在指定时间执行一次、基于时钟定时执行(基于Cron表达式)。

  • 固定时间间隔执行:基于Rate表达式,按照设置的时间间隔执行命令。时间间隔支持按秒(s) 、分钟(m) 、小时(h)和天(d)来选择,适用于在固定时间间隔执行任务的场景。格式为rate(<执行间隔数值><执行间隔单位>),如5分钟执行一次,格式为rate(5m)。使用固定时间间隔执行有以下限制:
    • 设置的时间间隔不大于7天、不小于60秒,且需大于周期任务的超时时间。
    • 执行间隔只基于固定频率,与任务实际执行需要的时间无关。例如设置每5分钟执行一次命令,任务需要2分钟执行完成,则在任务完成3分钟后继续执行下一轮。
    • 创建任务时不会立即执行。例如设置每5分钟执行一次命令,创建任务时不会立即执行一次命令,而是在任务创建完成后的5分钟后开始执行。
  • 仅在指定时间执行一次:按照设置的时区和执行时间点执行一次命令。格式为at(yyyy-MM-dd HH:mm:ss <时区>),即at(年-月-日 时:分:秒 <时区>)。如果不指定时区,默认为UTC时区。时区支持以下三种形式:
    • 时区全称: 如Asia/Shanghai(中国/上海时间)、America/Los_Angeles(美国/洛杉矶时间)等。
    • 时区相对于格林威治时间的偏移量: 如GMT+8:00(东八区)、GMT-7:00(西七区)等。使用GMT格式时,小时位不支持添加前导零。
    • 时区缩写: 仅支持UTC(协调世界时间)。

      如果指定在中国/上海时间2022年06月06日13时15分30秒执行一次,格式为:at(2022-06-06 13:15:30 Asia/Shanghai);如果指定在西七区2022年06月06日13时15分30秒执行一次,格式为:at(2022-06-06 13:15:30 GMT-7:00)

  • 基于时钟定时执行(基于Cron表达式):基于Cron表达式,按照设置的定时任务执行命令。格式为<秒> <分钟> <小时> <日期> <月份> <星期> <年份(可选)> <时区>,即<Cron表达式> <时区>。在指定的时区下,根据Cron表达式推算周期任务执行时间并执行。若不指定时区,默认为执行周期任务实例的系统内部时区。关于Cron表达式的更多信息,请参见Cron表达式。时区支持以下三种形式:
    • 时区全称: 如Asia/Shanghai(中国/上海时间)、America/Los_Angeles(美国/洛杉矶时间)等。
    • 时区相对于格林威治时间的偏移量: 如GMT+8:00(东八区)、GMT-7:00(西七区)等。使用GMT格式时,小时位不支持添加前导零。
    • 时区缩写: 仅支持UTC(协调世界时间)。

      例如,在中国/上海时间,2022年每天上午10:15执行一次命令,格式为0 15 10 ? * * 2022 Asia/Shanghai;在东八区时间,2022年每天上午10:00到11:30每隔半小时执行,格式为0 0/30 10-11 * * ? 2022 GMT+8:00;在UTC时间,从2022年开始,每隔两年的10月每天下午14:00到下午14:55时间段内每隔5分钟执行,格式为0 0/5 14 * 10 ? 2022/2 UTC
      说明 设置的最小时间间隔需大于或等于周期任务的超时时间,且不小于10秒。
Parameters Map {"name":"Jack", "accessKey":"LTAIdyv******aRY"}

启用自定义参数功能时,执行命令时传入的自定义参数的键值对。自定义参数的个数范围为0~10。

  • Map的键不允许为空字符串,最多支持64个字符。
  • Map的值允许为空字符串。
  • 自定义参数与原始命令内容在Base64编码后,综合长度不能超过16 KB。
  • 设置的自定义参数名集合必须为创建命令时定义的参数集的子集。对于未传入的参数,您可以使用空字符串代替。

您可以取消设置该参数从而禁用自定义参数。

Username String root

在ECS实例中执行命令的用户名称。

  • Linux系统的ECS实例,默认以root用户执行命令。
  • Windows系统的ECS实例,默认以System用户执行命令。

您也可以指定实例中已存在的其他用户执行命令,以普通用户执行云助手命令更加安全。更多信息,请参见设置普通用户执行云助手命令

WindowsPasswordName String axtSecretPassword

在Windows实例中执行命令的用户的密码名称。

当您希望以非默认用户(System)在Windows实例中执行命令时,需要同时传入Username和该参数。为降低密码泄露的风险,需要将密码明文托管在运维编排服务的参数仓库中,此处仅传入密码的名称。更多信息,请参见加密参数以及设置普通用户执行云助手命令

说明 当您使用Linux实例的root用户或Windows实例的System用户执行命令时,不需要传递该参数。
InstanceId.N String i-bp185dy2o3o6n****

需要执行命令的实例列表,最多能指定50台实例ID。N的取值范围为1~50。

返回数据

名称 类型 示例值 描述
InvokeId String t-7d2a745b412b4601b2d47f6a768d****

命令执行ID。

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

请求ID。

示例

请求示例

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
&公共请求参数

正常返回示例

XML格式

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

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

JSON格式

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

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

错误码

HttpCode 错误码 错误信息 描述
400 RegionId.ApiNotSupported The api is not supported in this region. 指定地域下不支持调用API。请检查RegionId参数取值是否正确。
403 InvalidInstance.NotMatch The specified instance type does not match the command. 指定的实例ID不支持执行指定的命令ID。请检查实例的状态是否符合云助手命令的执行条件。
403 MissingParam.Frequency The frequency must be specified when you create a timed task. 创建定时任务时必须指定频率。
403 InvalidParam.Frequency The specified frequency is invalid. 指定的Frequency参数无效。请检查参数值是否正确。
403 InstanceIds.ExceedLimit The number of instance IDs exceeds the upper limit. 目标实例数量超过上限。
403 Invocation.ExceedQuota The invocation quota in the current region has been reached for today. 在当前地域命令执行次数已到达今天的额度。
403 ParameterCount.ExceedLimit The maximum number of parameters is exceeded. 参数数量超出最大可设置数量。
403 ParameterKey.ExceedLimit The maximum length of a parameter name is exceeded. 指定的参数Key长度超过可设置的最大长度。
403 CmdContent.ExceedLimit The maximum length of a command is exceeded. 您的命令内容过长,请精简您的命令内容。
403 ParameterKey.Duplicate Parameter names cannot be duplicated. 参数名称不能重复,请确认后重试。
403 Parameter.NotMatched The passed-in parameters do not match the parameters defined when you created the command. 传入的自定义参数与创建命令时定义的自定义参数不匹配。
403 Username.ExceedLimit The length of the username exceeds the upper limit. 用户名长度超过上限。
403 Operation.Forbidden The operation is not permitted. 该操作是不被允许的。
404 InvalidRepeatMode.NotFound The specified repeat mode does not exist. 指定的命令执行方式不存在。
404 InvalidInstance.NotFound The specified instance does not exist. 指定的实例不存在。
404 InvalidCmdId.NotFound The specified command ID does not exist. 指定的CommandId参数有误,请检查参数值是否正确。您可以通过接口DescribeCommands查询所有可用的CommandId。
404 Parameter.Disabled Parameters cannot be passed in when the command customization function is disabled. 当您禁用命令自定义参数功能时,请不要传递自定义参数。
500 InternalError.Dispatch An error occurred when you dispatched the request. 发送请求时发生错误,请稍后重试。

访问错误中心查看更多错误码。