调用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:InvokeCommand | update | *Command acs:ecs:{#regionId}:{#accountId}:command/{#commandId} *Instance acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId} |
| 无 |
请求参数
名称 | 类型 | 必填 | 描述 | 示例值 |
---|---|---|---|---|
RegionId | string | 是 | 地域 ID。您可以调用 DescribeRegions 查看最新的阿里云地域列表。 | cn-hangzhou |
ResourceGroupId | string | 否 | 命令执行的资源组 ID,当指定该参数时:
| rg-bp67acfmxazb4p**** |
CommandId | string | 是 | 命令 ID。您可以通过接口 DescribeCommands 查询所有可用的 CommandId。 说明
对于公共命令,可以通过命令名称执行。更多信息,请参见查看和执行云助手公共命令。
| c-e996287206324975b5fbe1d**** |
RepeatMode | string | 否 | 设置命令执行的方式。取值范围:
默认值:
注意事项:
| Once |
Timed | boolean | 否 | 说明
该参数已废弃,传入该参数不会生效。
| true |
Frequency | string | 否 | 定时执行命令的执行时间。目前支持三种定时执行方式:固定时间间隔执行(基于 Rate 表达式)、仅在指定时间执行一次、基于时钟定时执行(基于 Cron 表达式)。
| 0 */20 * * * ? |
Parameters | object | 否 | 启用自定义参数功能时,执行命令时传入的自定义参数的键值对。自定义参数的个数范围为 0~10。
您可以取消设置该参数从而禁用自定义参数。 | {"name":"Jack", "accessKey":"LTAIdyv******aRY"} |
Username | string | 否 | 在 ECS 实例中执行命令的用户名称。长度不得超过 255 个字符。
您也可以指定实例中已存在的其他用户执行命令,以普通用户执行云助手命令更加安全。更多信息,请参见设置普通用户执行云助手命令。 | test |
WindowsPasswordName | string | 否 | 在 Windows 实例中执行命令的用户的密码名称。长度不得超过 255 个字符。 当您希望以非默认用户(System)在 Windows 实例中执行命令时,需要同时传入 说明
当您使用 Linux 实例的 root 用户或 Windows 实例的 System 用户执行命令时,不需要传递该参数。
| axtSecretPassword |
InstanceId | array | 否 | 需要执行命令的实例列表,最多能指定 100 台实例 ID。N 的取值范围为 1~100。 您也可以在配额中心申请提升配额(配额名称为命令执行支持实例上限数)。 | |
string | 否 | 需要执行命令的实例 ID。 | i-bp185dy2o3o6n**** | |
ContainerId | string | 否 | 容器 ID。仅支持 64 位 16 进制字符串。支持使用 注意事项:
| ab141ddfbacfe02d9dbc25966ed971536124527097398d419a6746873fea**** |
ContainerName | string | 否 | 容器名称。 注意事项:
| test-container |
Timeout | long | 否 | 执行命令的超时时间,单位:秒。
| 60 |
Tag | array<object> | 否 | 标签列表。 | |
object | 否 | 标签列表。 | ||
Key | string | 否 | 命令执行的标签键。N 的取值范围为 1~20。一旦传入该值,则不允许为空字符串。 使用一个标签过滤资源,查询到该标签下的资源数量不能超过 1000 个。使用多个标签过滤资源,查询到同时绑定了多个标签的资源数量不能超过 1000 个。如果资源数量超过 1000 个,您需要使用 ListTagResources 接口进行查询。 最多支持 64 个字符,不能以 | TestKey |
Value | string | 否 | 命令执行的标签值。N 的取值范围为 1~20。该值可以为空字符串。 最多支持 128 个字符,不能包含 | TestValue |
ClientToken | string | 否 | 保证请求幂等性。从您的客户端生成一个参数值,确保不同请求间该参数值唯一。ClientToken 只支持 ASCII 字符,且不能超过 64 个字符。更多详情,请参见如何保证幂等性。 | 123e4567-e89b-12d3-a456-42665544**** |
ResourceTag | array<object> | 否 | 用于筛选实例的标签列表。可以在不指定 InstanceId 的情况下,向具有相同标签的实例批量执行命令。 | |
object | 否 | 用于筛选实例的标签。可以在不指定 InstanceId 的情况下,向具有相同标签的实例批量执行命令。 | ||
Key | string | 否 | 用于筛选实例的标签键。 注意事项:
| TestKey |
Value | string | 否 | 用于筛选实例的标签值。 注意事项:
| TestValue |
TerminationMode | string | 否 | 停止任务(手动停止或执行超时打断)时的模式。可能值:
| ProcessTree |
Launcher | string | 否 | 脚本执行的引导程序。长度不能超过 1 KB。 | python3 -u {{ACS::ScriptFileName|Ext(".py")}} |
返回参数
示例
正常返回示例
JSON
格式
{
"InvokeId": "t-7d2a745b412b4601b2d47f6a768d****",
"RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3****"
}
错误码
HTTP status code | 错误码 | 错误信息 | 描述 |
---|---|---|---|
400 | RegionId.ApiNotSupported | The api is not supported in this region. | 指定地域下不支持调用 API。请检查 RegionId 参数取值是否正确。 |
400 | MissingParam.InstanceId | The parameter instanceId is missing or empty. | 实例ID为空。 |
400 | InvalidContainerId.Malformed | The specified parameter ContainerId is not valid. | 指定的容器ID不合法。 |
400 | InvalidContainerName.Malformed | The specified parameter ContainerName is not valid. | 指定的容器名称不合法。 |
400 | InvalidClientToken.Malformed | The specified parameter clientToken is not valid. | 指定的幂等参数不合法。 |
400 | InvalidInstance.NotMatch | The specified instance type does not match the command. | 指定的实例ID不支持执行指定的命令ID。请检查实例的状态是否符合云助手命令的执行条件。 |
400 | MissingParam.Frequency | The frequency must be specified when you create a timed task. | 创建定时任务时必须指定频率。 |
400 | InvalidParam.Frequency | The specified frequency is invalid. | 指定的 Frequency 参数无效。请检查参数值是否正确。 |
400 | Parameter.MissingValue | The parameter value of this command is required. | 该命令的参数值是必填的。 |
400 | Parameter.Disabled | Parameters cannot be passed in when the command customization function is disabled. | 当您禁用命令自定义参数功能时,请不要传递自定义参数。 |
400 | InvalidParameter.Parameters | The specified parameter Parameters is not valid. | 指定的参数Parameters不合法。 |
400 | NumberExceed.ResourceTags | The maximum number of ResourceTags is exceeded. | - |
400 | MissingParameter.ResourceTagKey | You must specify ResourceTag.N.Key. | - |
400 | InvalidResourceTagKey.Malformed | The specified ResourceTag key is not valid. | - |
400 | InvalidResourceTagValue.Malformed | The specified ResourceTag value is not valid. | - |
400 | Duplicate.ResourceTagKey | The ResourceTag contains duplicate keys. | - |
400 | InvalidResourceTag.InstanceNotFound | InstanceIds are not found by the specified ResourceTag. | - |
400 | InvalidResourceTag.ConflictWithInstanceIds | The specified param ResourceTag conflicts with InstanceId. | - |
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 | ParameterType.NotSupported | The type of parameter value is not supported. | 不支持自定义参数值的类型。 |
403 | Username.ExceedLimit | The length of the username exceeds the upper limit. | 用户名长度超过上限。 |
403 | WindowsPasswordName.ExceedLimit | The length of the WindowsPasswordName exceeds the upper limit. | 指定的WindowsPasswordName参数长度超过上限。 |
403 | WindowsPasswordName.Missed | WindowsPasswordName must be specified when you create a Windows task. | 请求参数“命令类型(WindowsPasswordName)”的值未提供。 |
403 | ParameterStore.NotSupported | Parameter Store is not supported in this region. | - |
403 | TemporaryAccessKey.Error | The temporary accessKey is invalid. | - |
403 | ParameterStore.InvalidParameters | The parameter is invalid in Parameter Store. | 未找到命令内容中的{{oos:?}}所指定的参数。 |
403 | ParameterStore.NoPermission | You have no access to Parameter Store. | - |
403 | Operation.Forbidden | The operation is not permitted. | 该操作是不被允许的。 |
403 | IdempotentParameterMismatch | The specified parameter has changed while using an already used clientToken. | 指定的客户令牌已经被使用。 |
403 | IdempotentProcessing | The previous idempotent request(s) is still processing. | 先前的幂等请求仍在处理中,请稍后重试。 |
403 | InvalidLauncher.LengthLimitExceeded | The length of the parameter Launcher exceeds the limit of 1 KB characters. | 参数Launcher的长度超过了 1 KB个字符的限制。 |
403 | InvalidParameterCharset.Parameters | The parameter Parameters contains illegal charset. | 命令参数包含非法字符集。 |
404 | InvalidRepeatMode.NotFound | The specified repeat mode does not exist. | 指定的命令执行方式不存在。 |
404 | InvalidRegionId.NotFound | The RegionId provided does not exist in our records. | 提供的RegionId不存在 |
404 | InvalidInstance.NotFound | The specified instance does not exist. | 指定的实例不存在。 |
404 | InvalidCmdId.NotFound | The specified command ID does not exist. | 指定的 CommandId 参数有误,请检查参数值是否正确。您可以通过接口 DescribeCommands 查询所有可用的 CommandId。 |
404 | InvalidResourceGroup.NotFound | The ResourceGroup provided does not exist in our records. | 资源组并不在记录中。 |
404 | InvalidTerminationMode.NotFound | The specified parameter TerminationMode does not exist. | 指定的参数TerminationMode不存在。 |
500 | InternalError.Dispatch | An error occurred when you dispatched the request. | 发送请求时发生错误,请稍后重试。 |
访问错误中心查看更多错误码。
变更历史
变更时间 | 变更内容概要 | 操作 |
---|---|---|
2024-10-28 | OpenAPI 错误码发生变更 | 查看变更详情 |
2024-08-01 | OpenAPI 错误码发生变更、OpenAPI 入参发生变更 | 查看变更详情 |
2024-05-14 | OpenAPI 错误码发生变更、OpenAPI 入参发生变更 | 查看变更详情 |
2024-04-12 | OpenAPI 错误码发生变更 | 查看变更详情 |
2024-01-23 | OpenAPI 错误码发生变更、OpenAPI 入参发生变更 | 查看变更详情 |
2023-05-12 | OpenAPI 错误码发生变更 | 查看变更详情 |
2023-04-25 | OpenAPI 错误码发生变更 | 查看变更详情 |
2022-10-27 | OpenAPI 错误码发生变更、OpenAPI 入参发生变更 | 查看变更详情 |
2022-01-06 | OpenAPI 错误码发生变更 | 查看变更详情 |
2022-01-06 | OpenAPI 错误码发生变更 | 查看变更详情 |