全部产品
Search
文档中心

云服务器 ECS:InvokeCommand - 为一台或多台ECS实例触发一条云助手命令

更新时间:Dec 06, 2024

调用InvokeCommand接口,并可以指定CommandId、InstanceId、ResourceGroupId等参数,为一台或多台ECS实例触发一条云助手命令。

接口说明

  • 对目标 ECS 实例有如下限制。选择了多台 ECS 实例后,若其中某台实例不满足执行条件,您需要重新调用接口。

    • 状态必须为运行中(Running),您可以调用 DescribeInstances 查询。

    • 已预先安装云助手 Agent

    • 执行类型为 PowerShell 的命令时,实例必须已经配置了 PowerShell 模块。

  • 单次执行:只执行一次命令。

  • 定时执行:

    • 根据参数 Frequency 指定的时间频率定时执行,上次的执行结果不会对下一次执行产生任何影响。
    • 当您基于 Cron 表达式执行定时任务且指定了时区,时钟定时执行时间设置基准为您指定的时区;当您没有指定时区时,时钟定时执行时间设置基准为 ECS 实例内的系统时区,且执行时间以实例的系统时间为准。请确保 ECS 实例的时间或者时区与您预期的时间一致。更多关于时区的详情,请参见管理时间同步服务

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

    • Linux:2.2.3.282。
    • Windows:2.1.3.282。
  • 命令可能会因为目标实例的状态异常、网络异常或云助手 Agent 异常而出现无法执行的情况,无法执行时不会生成执行信息。更多信息,请参见执行失败常见错误及修复建议

  • 当您创建命令时启用了自定义参数功能,需要在执行命令时传入自定义参数(Parameters)。

  • 建议您先调用 DescribeCloudAssistantStatus 查询实例的云助手状态,当 CloudAssistantStatus 为 true 时再执行命令,尤其对于新购实例。

调试

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

授权信息

下表是API对应的授权信息,可以在RAM权限策略语句的Action元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:

  • 操作:是指具体的权限点。
  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:
    • 对于必选的资源类型,用背景高亮的方式表示。
    • 对于不支持资源级授权的操作,用全部资源表示。
  • 条件关键字:是指云产品自身定义的条件关键字。
  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作访问级别资源类型条件关键字关联操作
ecs:InvokeCommandupdate
*Command
acs:ecs:{#regionId}:{#accountId}:command/{#commandId}
*Instance
acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}
  • ecs:CommandRunAs

请求参数

名称类型必填描述示例值
RegionIdstring

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

cn-hangzhou
ResourceGroupIdstring

命令执行的资源组 ID,当指定该参数时:

rg-bp67acfmxazb4p****
CommandIdstring

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

说明 对于公共命令,可以通过命令名称执行。更多信息,请参见查看和执行云助手公共命令
c-e996287206324975b5fbe1d****
RepeatModestring

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

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

默认值:

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

注意事项:

  • 您可以调用 StopInvocation 停止待执行的命令或定时执行的命令。
  • 当该参数取值Period或者EveryReboot时,您可以调用 DescribeInvocationResults ,然后指定IncludeHistory=true查看命令定时执行的历史记录。
Once
Timedboolean
说明 该参数已废弃,传入该参数不会生效。
true
Frequencystring

定时执行命令的执行时间。目前支持三种定时执行方式:固定时间间隔执行(基于 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 秒。
0 */20 * * * ?
Parametersobject

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

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

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

{"name":"Jack", "accessKey":"LTAIdyv******aRY"}
Usernamestring

在 ECS 实例中执行命令的用户名称。长度不得超过 255 个字符。

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

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

test
WindowsPasswordNamestring

在 Windows 实例中执行命令的用户的密码名称。长度不得超过 255 个字符。

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

说明 当您使用 Linux 实例的 root 用户或 Windows 实例的 System 用户执行命令时,不需要传递该参数。
axtSecretPassword
InstanceIdarray

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

您也可以在配额中心申请提升配额(配额名称为命令执行支持实例上限数)。

string

需要执行命令的实例 ID。

i-bp185dy2o3o6n****
ContainerIdstring

容器 ID。仅支持 64 位 16 进制字符串。支持使用docker://containerd://或者cri-o://前缀来表示指定的容器运行时。

注意事项:

  • 如果指定了该参数,云助手将在实例的指定容器内执行脚本。

  • 如果指定了该参数,仅支持在云助手 Agent 版本不低于 2.2.3.344 的 Linux 实例内运行。

  • 如果指定了该参数,本接口中已指定的Username参数和 CreateCommand 中指定的WorkingDir参数将不会生效。仅支持通过容器默认用户在容器的默认工作目录下执行命令。更多信息,请参见使用云助手在容器内执行命令

  • 如果指定了该参数,在 Linux 容器中只支持执行 Shell 脚本,不支持在脚本开头使用类似#!/usr/bin/python命令的形式指定脚本内容的解释器。更多信息,请参见使用云助手在容器内执行命令

ab141ddfbacfe02d9dbc25966ed971536124527097398d419a6746873fea****
ContainerNamestring

容器名称。

注意事项:

  • 如果指定了该参数,云助手将在实例的指定容器内执行脚本。

  • 如果指定了该参数,仅支持在云助手 Agent 版本不低于 2.2.3.344 的 Linux 实例内运行。

  • 如果指定了该参数,本接口中已指定的Username参数和 CreateCommand 中指定的WorkingDir参数将不会生效。仅支持通过容器默认用户在容器的默认工作目录下执行命令。更多信息,请参见使用云助手在容器内执行命令

  • 如果指定了该参数,在 Linux 容器中只支持执行 Shell 脚本,不支持在脚本开头使用类似#!/usr/bin/python命令的形式指定脚本内容的解释器。更多信息,请参见使用云助手在容器内执行命令

test-container
Timeoutlong

执行命令的超时时间,单位:秒。

  • 该值不能小于 10 秒。

  • 当因为进程原因、缺失模块、缺失云助手 Agent 等原因无法运行命令时,会出现超时现象。超时后,会强制终止命令进程。

  • 若不设置该值,会采用创建命令时指定的超时时间。

  • 该值只会作为该次命令执行的超时时间,不会改变命令本身的超时时间。

60
Tagarray<object>

标签列表。

object

标签列表。

Keystring

命令执行的标签键。N 的取值范围为 1~20。一旦传入该值,则不允许为空字符串。

使用一个标签过滤资源,查询到该标签下的资源数量不能超过 1000 个。使用多个标签过滤资源,查询到同时绑定了多个标签的资源数量不能超过 1000 个。如果资源数量超过 1000 个,您需要使用 ListTagResources 接口进行查询。

最多支持 64 个字符,不能以aliyunacs:开头,不能包含http://https://

TestKey
Valuestring

命令执行的标签值。N 的取值范围为 1~20。该值可以为空字符串。

最多支持 128 个字符,不能包含http://https://

TestValue
ClientTokenstring

保证请求幂等性。从您的客户端生成一个参数值,确保不同请求间该参数值唯一。ClientToken 只支持 ASCII 字符,且不能超过 64 个字符。更多详情,请参见如何保证幂等性

123e4567-e89b-12d3-a456-42665544****
ResourceTagarray<object>

用于筛选实例的标签列表。可以在不指定 InstanceId 的情况下,向具有相同标签的实例批量执行命令。

object

用于筛选实例的标签。可以在不指定 InstanceId 的情况下,向具有相同标签的实例批量执行命令。

Keystring

用于筛选实例的标签键。

注意事项:

  • 与参数 InstanceId 冲突,不能同时指定。

  • N 的取值范围为 1~10。一旦传入该值,则不允许为空字符串。

  • 标签下的实例数量不能超过 InstanceId.N 的数量限制;如果实例数量超出限制,建议通过添加批次标签等方式控制实例数量,例如 batch: b1。

  • 最多支持 64 个字符,不能以 aliyun 或 acs:开头,不能包含 http://或 https://。

TestKey
Valuestring

用于筛选实例的标签值。

注意事项:

  • N 的取值范围为 1~10。
  • 该值可以为空字符串。
  • 最多支持 128 个字符,不能包含 http://或 https://。
TestValue
TerminationModestring

停止任务(手动停止或执行超时打断)时的模式。可能值:

  • Process:停止当前脚本进程。
  • ProcessTree:停止当前进程树(脚本进程以及它创建的所有子进程的集合)。
ProcessTree
Launcherstring

脚本执行的引导程序。长度不能超过 1 KB。

python3 -u {{ACS::ScriptFileName|Ext(".py")}}

返回参数

名称类型描述示例值
object
InvokeIdstring

命令执行 ID。

t-7d2a745b412b4601b2d47f6a768d****
RequestIdstring

请求 ID。

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

示例

正常返回示例

JSON格式

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

错误码

HTTP status code错误码错误信息描述
400RegionId.ApiNotSupportedThe api is not supported in this region.指定地域下不支持调用 API。请检查 RegionId 参数取值是否正确。
400MissingParam.InstanceIdThe parameter instanceId is missing or empty.实例ID为空。
400InvalidContainerId.MalformedThe specified parameter ContainerId is not valid.指定的容器ID不合法。
400InvalidContainerName.MalformedThe specified parameter ContainerName is not valid.指定的容器名称不合法。
400InvalidClientToken.MalformedThe specified parameter clientToken is not valid.指定的幂等参数不合法。
400InvalidInstance.NotMatchThe specified instance type does not match the command.指定的实例ID不支持执行指定的命令ID。请检查实例的状态是否符合云助手命令的执行条件。
400MissingParam.FrequencyThe frequency must be specified when you create a timed task.创建定时任务时必须指定频率。
400InvalidParam.FrequencyThe specified frequency is invalid.指定的 Frequency 参数无效。请检查参数值是否正确。
400Parameter.MissingValueThe parameter value of this command is required.该命令的参数值是必填的。
400Parameter.DisabledParameters cannot be passed in when the command customization function is disabled.当您禁用命令自定义参数功能时,请不要传递自定义参数。
400InvalidParameter.ParametersThe specified parameter Parameters is not valid.指定的参数Parameters不合法。
400NumberExceed.ResourceTagsThe maximum number of ResourceTags is exceeded.-
400MissingParameter.ResourceTagKeyYou must specify ResourceTag.N.Key.-
400InvalidResourceTagKey.MalformedThe specified ResourceTag key is not valid.-
400InvalidResourceTagValue.MalformedThe specified ResourceTag value is not valid.-
400Duplicate.ResourceTagKeyThe ResourceTag contains duplicate keys.-
400InvalidResourceTag.InstanceNotFoundInstanceIds are not found by the specified ResourceTag.-
400InvalidResourceTag.ConflictWithInstanceIdsThe specified param ResourceTag conflicts with InstanceId.-
403InstanceIds.ExceedLimitThe number of instance IDs exceeds the upper limit.目标实例数量超过上限。
403Invocation.ExceedQuotaThe invocation quota in the current region has been reached for today.在当前地域命令执行次数已到达今天的额度。
403ParameterCount.ExceedLimitThe maximum number of parameters is exceeded.参数数量超出最大可设置数量。
403ParameterKey.ExceedLimitThe maximum length of a parameter name is exceeded.指定的参数Key长度超过可设置的最大长度。
403CmdContent.ExceedLimitThe maximum length of a command is exceeded.您的命令内容过长,请精简您的命令内容。
403ParameterKey.DuplicateParameter names cannot be duplicated.参数名称不能重复,请确认后重试。
403Parameter.NotMatchedThe passed-in parameters do not match the parameters defined when you created the command.传入的自定义参数与创建命令时定义的自定义参数不匹配。
403ParameterType.NotSupportedThe type of parameter value is not supported.不支持自定义参数值的类型。
403Username.ExceedLimitThe length of the username exceeds the upper limit.用户名长度超过上限。
403WindowsPasswordName.ExceedLimitThe length of the WindowsPasswordName exceeds the upper limit.指定的WindowsPasswordName参数长度超过上限。
403WindowsPasswordName.MissedWindowsPasswordName must be specified when you create a Windows task.请求参数“命令类型(WindowsPasswordName)”的值未提供。
403ParameterStore.NotSupportedParameter Store is not supported in this region.-
403TemporaryAccessKey.ErrorThe temporary accessKey is invalid.-
403ParameterStore.InvalidParametersThe parameter is invalid in Parameter Store.未找到命令内容中的{{oos:?}}所指定的参数。
403ParameterStore.NoPermissionYou have no access to Parameter Store.-
403Operation.ForbiddenThe operation is not permitted.该操作是不被允许的。
403IdempotentParameterMismatchThe specified parameter has changed while using an already used clientToken.指定的客户令牌已经被使用。
403IdempotentProcessingThe previous idempotent request(s) is still processing.先前的幂等请求仍在处理中,请稍后重试。
403InvalidLauncher.LengthLimitExceededThe length of the parameter Launcher exceeds the limit of 1 KB characters.参数Launcher的长度超过了 1 KB个字符的限制。
403InvalidParameterCharset.ParametersThe parameter Parameters contains illegal charset.命令参数包含非法字符集。
404InvalidRepeatMode.NotFoundThe specified repeat mode does not exist.指定的命令执行方式不存在。
404InvalidRegionId.NotFoundThe RegionId provided does not exist in our records.提供的RegionId不存在
404InvalidInstance.NotFoundThe specified instance does not exist.指定的实例不存在。
404InvalidCmdId.NotFoundThe specified command ID does not exist.指定的 CommandId 参数有误,请检查参数值是否正确。您可以通过接口 DescribeCommands 查询所有可用的 CommandId。
404InvalidResourceGroup.NotFoundThe ResourceGroup provided does not exist in our records.资源组并不在记录中。
404InvalidTerminationMode.NotFoundThe specified parameter TerminationMode does not exist.指定的参数TerminationMode不存在。
500InternalError.DispatchAn error occurred when you dispatched the request.发送请求时发生错误,请稍后重试。

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

变更历史

变更时间变更内容概要操作
2024-12-05OpenAPI 描述信息更新、OpenAPI 错误码发生变更查看变更详情
2024-10-28OpenAPI 错误码发生变更查看变更详情
2024-08-01OpenAPI 错误码发生变更、OpenAPI 入参发生变更查看变更详情
2024-05-14OpenAPI 错误码发生变更、OpenAPI 入参发生变更查看变更详情
2024-04-12OpenAPI 错误码发生变更查看变更详情
2024-01-23OpenAPI 错误码发生变更、OpenAPI 入参发生变更查看变更详情
2023-05-12OpenAPI 错误码发生变更查看变更详情
2023-04-25OpenAPI 错误码发生变更查看变更详情
2022-10-27OpenAPI 错误码发生变更、OpenAPI 入参发生变更查看变更详情
2022-01-06OpenAPI 错误码发生变更查看变更详情
2022-01-06OpenAPI 错误码发生变更查看变更详情