调用RunCommand接口,并指定Type、CommandContent等参数,在一台或多台ECS实例中执行一段Shell、PowerShell或者Bat类型的脚本。
接口说明
不同于通过 CreateCommand 和 InvokeCommand 执行命令,RunCommand 只需一次调用即可完成命令的创建与执行。
调用该接口时,您需要注意:
-
目标实例的状态必须为运行中(
Running
),您可以调用 DescribeInstances 查询。 -
目标实例必须预先安装云助手 Agent。
-
执行 PowerShell 类型的命令时,您需要确保目标 ECS Windows 实例已经配置了 PowerShell 模块。
-
当您基于 Cron 表达式执行定时任务且指定了时区,时钟定时执行时间设置基准为您指定的时区;当您没有指定时区时,时钟定时执行时间设置基准为 ECS 实例内的系统时区,且执行时间以实例的系统时间为准。请确保 ECS 实例的时间或者时区与您预期的时间一致。关于时区的更多信息,请参见设置 Linux 实例时区和 NTP 服务或设置 Windows 实例 NTP 服务。
-
您可以通过指定参数
Timeout
为命令设置在 ECS 实例中执行时最大的超时时间,命令执行超时后,云助手 Agent 会强制终止进程。- 单次执行超时后,命令的执行状态( InvokeRecordStatus )变为执行失败(Failed)。
- 定时执行的超时时间对每一次执行记录均有效,上次执行超时不影响下一次执行。某次执行超时后,执行状态( InvokeRecordStatus )变为执行失败(Failed)。
云助手 Agent 版本需要不低于以下对应的版本才能支持定时任务的新特性(固定时间间隔执行、仅在指定时间执行一次、基于 Cron 表达式定时执行时指定年份或时区)。如果结果返回
ClientNeedUpgrade
错误码,请参见升级或禁止升级云助手 Agent,将客户端更新至最新版本。- Linux:2.2.3.282。 - Windows:2.1.3.282。
-
命令可能会因为目标实例的状态异常、网络异常或云助手 Agent 异常而出现无法执行的情况,无法执行时不会生成执行信息。更多信息,请参见执行失败常见错误及修复建议。
-
EnableParameter=true
时会启用自定义参数功能。在设置CommandContent
时可以通过{{parameter}}
的形式表示自定义参数,并在运行命令时,传入自定义参数键值对。 -
在一个地域下,您最多可以保有 500~50,000 条云助手命令,您也可以申请提升配额,关于如何查询及提升配额,请参见配额管理。
-
建议您先调用 DescribeCloudAssistantStatus 查询实例的云助手状态,当 CloudAssistantStatus 为 true 时再执行命令,尤其对于新购实例。
调试
您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。
授权信息
下表是API对应的授权信息,可以在RAM权限策略语句的Action
元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:
- 操作:是指具体的权限点。
- 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
- 资源类型:是指操作中支持授权的资源类型。具体说明如下:
- 对于必选的资源类型,用背景高亮的方式表示。
- 对于不支持资源级授权的操作,用
全部资源
表示。
- 条件关键字:是指云产品自身定义的条件关键字。
- 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作 | 访问级别 | 资源类型 | 条件关键字 | 关联操作 |
---|---|---|---|---|
ecs:RunCommand | update | *全部资源 * |
| 无 |
请求参数
名称 | 类型 | 必填 | 描述 | 示例值 |
---|---|---|---|---|
RegionId | string | 是 | 地域 ID。您可以调用 DescribeRegions 查看最新的阿里云地域列表。 | cn-hangzhou |
ResourceGroupId | string | 否 | 命令执行的资源组 ID,当指定该参数时:
| rg-bp67acfmxazb4p**** |
Name | string | 否 | 命令名称。支持全字符集,长度不得超过 128 个字符。 | testName |
Description | string | 否 | 命令描述。支持全字符集,长度不得超过 512 个字符。 | testDescription |
Type | string | 是 | 运维命令的语言类型。取值范围:
| RunShellScript |
CommandContent | string | 是 | 命令内容。命令内容可以是明文内容或 Base64 编码后的内容。您需要注意:
| ZWNobyAxMjM= |
WorkingDir | string | 否 | 命令在 ECS 实例中的运行目录。长度不得超过 200 个字符。 默认值:
| /home/user |
Timeout | long | 否 | 执行命令的超时时间,单位:秒。 当因为进程原因、缺失模块、缺失云助手 Agent 等原因无法运行命令时,会出现超时现象。超时后,会强制终止命令进程。 默认值:60。 | 3600 |
EnableParameter | boolean | 否 | 命令中是否包含自定义参数。 默认值:false。 | false |
RepeatMode | string | 否 | 设置命令执行的方式。取值范围:
默认值:
注意事项:
| Once |
Timed | boolean | 否 | 说明
该参数已废弃,传入该参数不会生效。
| true |
Frequency | string | 否 | 定时执行命令的执行时间。目前支持三种定时执行方式:固定时间间隔执行(基于 Rate 表达式)、仅在指定时间执行一次、基于时钟定时执行(基于 Cron 表达式)。
| 0 */20 * * * ? |
Parameters | object | 否 | 命令中包含自定义参数时,执行命令时传入的自定义参数的键值对。例如,命令内容为 自定义参数的个数范围为 0~10,且您需要注意:
默认值为空,表示取消设置该参数从而禁用自定义参数。 | {"name":"Jack", "accessKey":"LTAIdyvdIqaRY****"} |
KeepCommand | boolean | 否 | 执行完该命令后,是否保留下来。取值范围:
默认值:false。 | false |
ContentEncoding | string | 否 | 命令内容(
默认值:PlainText,乱填或错填该取值会当作 PlainText 处理。 | Base64 |
Username | string | 否 | 在 ECS 实例中执行命令的用户名称。长度不得超过 255 个字符。
您也可以指定实例中已存在的其他用户执行命令,以普通用户执行云助手命令更加安全。更多信息,请参见设置普通用户执行云助手命令。 | test |
WindowsPasswordName | string | 否 | 在 Windows 实例中执行命令的用户的密码名称。长度不得超过 255 个字符。 当您希望以非默认用户(System)在 Windows 实例中执行命令时,需要同时传入 说明
当您使用 Linux 实例的 root 用户或 Windows 实例的 System 用户执行命令时,不需要传递该参数。
| axtSecretPassword |
InstanceId | array | 否 | ECS 实例 ID。N 表示您可以同时设置多个实例 ID,N 的取值范围:1~100。 若指定了多台实例后,其中某台实例不满足执行条件时,您都需要重新选择。 您也可以在配额中心申请提升配额(配额名称为命令执行支持实例上限数)。 | |
string | 否 | ECS 实例 ID。N 表示您可以同时设置多个实例 ID,N 的取值范围:1~100。 若指定了多台实例后,其中某台实例不满足执行条件时,您都需要重新选择。 您也可以在配额中心申请提升配额(配额名称为命令执行支持实例上限数)。 | i-bp185dy2o3o6neg**** | |
Tag | array<object> | 否 | 标签列表。 | |
object | 否 | 标签列表。 | ||
Key | string | 否 | 命令执行的标签键。N 的取值范围为 1~20。一旦传入该值,则不允许为空字符串。 使用一个标签过滤资源,查询到该标签下的资源数量不能超过 1000 个。使用多个标签过滤资源,查询到同时绑定了多个标签的资源数量不能超过 1000 个。如果资源数量超过 1000 个,您需要使用 ListTagResources 接口进行查询。 最多支持 64 个字符,不能以 | TestKey |
Value | string | 否 | 命令执行的标签值。N 的取值范围为 1~20。该值可以为空字符串。 最多支持 128 个字符,不能包含 | TestValue |
ContainerId | string | 否 | 容器 ID。仅支持 64 位 16 进制字符串,允许存在 注意事项:
| ab141ddfbacfe02d9dbc25966ed971536124527097398d419a6746873fea**** |
ContainerName | string | 否 | 容器名称。 注意事项:
| test-container |
ClientToken | string | 否 | 保证请求幂等性。从您的客户端生成一个参数值,确保不同请求间该参数值唯一。ClientToken 只支持 ASCII 字符,且不能超过 64 个字符。更多信息,请参见如何保证幂等性。 | 123e4567-e89b-12d3-a456-426655440000 |
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
格式
{
"RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3****",
"CommandId": "c-7d2a745b412b4601b2d47f6a768d****",
"InvokeId": "t-7d2a745b412b4601b2d47f6a768d****"
}
错误码
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 | NumberExceed.Tags | Ensure the number of tag parameters is not greater than 20. | 标签个数超过最大限制。 |
400 | InvalidTagValue.Malformed | The specified Tag.n.Value is not valid. | 指定的标签值参数有误。 |
400 | Duplicate.TagKey | The Tag.N.Key contain duplicate key. | 标签中存在重复的键,请保持键的唯一性。 |
400 | InvalidTagKey.Malformed | The specified Tag.n.Key is not valid. | 指定的标签键参数有误。 |
400 | MissingParameter.TagKey | You must specify Tag.N.Key. | 请指定标签键。 |
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 | CmdParam.EmptyKey | Command parameters can not be empty. | 命令中自定义参数不能为空。 |
400 | CmdParam.InvalidParamName | A command parameter name is invalid. | 命令中自定义参数名称不合法。 |
400 | CmdContent.DecodeError | The CommandContent can not be base64 decoded. | 命令内容无法通过Base64解码。 |
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 | ParameterKey.Duplicate | The parameter may not contain duplicate keys. | 参数名称不能重复,请确认后重试。 |
400 | Parameter.NotMatched | The parameters of creation do not match those of invocation. | 传入的自定义参数与创建命令时定义的自定义参数不匹配。 |
400 | WindowsPasswordName.Missed | WindowsPasswordName must be specified when you create a Windows task. | 请求参数“命令类型(WindowsPasswordName)”的值未提供。 |
400 | Parameter.Disabled | Parameters should not be passed when CreateCommand.EnableParameter is false. | 当您禁用命令自定义参数功能时,请不要传递自定义参数。 |
400 | InvalidParameter.WorkingDir | The specified parameter WorkingDir is not valid. | 指定的参数WorkingDir不合法。 |
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 | CmdContent.ExceedLimit | The length of the command content exceeds the upper limit. | 命令内容长度超过上限。 |
403 | CmdName.ExceedLimit | The length of the command name exceeds the upper limit. | 命令名称长度超过上限。 |
403 | CmdDesc.ExceedLimit | The length of the command description exceeds the upper limit. | 命令描述长度超过上限。 |
403 | CmdCount.ExceedQuota | The total number of commands in the current region exceeds the quota. | 当前地域下的云助手命令数量已超出限制。 |
403 | CmdParamCount.ExceedLimit | You've reached the limit on the count of command parameters. | - |
403 | CmdParamName.ExceedLimit | The length of the command parameter name exceeds the limit. | 命令中自定义参数名称长度超过上限。 |
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 number of command parameters exceeds the maximum number that can be set. | 自定义参数的个数超过限制。 |
403 | ParameterKey.ExceedLimit | The length of the specified parameter key exceeds the maximum length that can be set. | 指定的参数Key长度超过可设置的最大长度。 |
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 | 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 | OperationDenied.BidOwnResource | Bid user can not own resource. | - |
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 | InvalidStatus.ResourceGroup | You cannot perform an operation on a resource group that is being created or deleted. | 资源组正在创建或删除时不允许操作。 |
403 | InvalidParameterCharacter.CommandName | The command Name contains illegal characters. | 命令名称包含非法字符。 |
403 | InvalidParameterCharacter.CommandDescription | The command Description contains illegal characters. | 命令描述包含非法字符。 |
403 | InvalidParameterCharacter.CommandWorkingDir | The command WorkingDir contains illegal characters. | 命令执行路径包含非法字符。 |
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 | InvalidCmdType.NotFound | The specified command type does not exist. | 指定的命令类型不存在。 |
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-12-05 | OpenAPI 描述信息更新、OpenAPI 错误码发生变更 | 查看变更详情 |
2024-10-28 | OpenAPI 错误码发生变更 | 查看变更详情 |
2024-08-01 | OpenAPI 错误码发生变更、OpenAPI 入参发生变更 | 查看变更详情 |
2024-05-14 | OpenAPI 错误码发生变更、OpenAPI 入参发生变更 | 查看变更详情 |
2024-05-11 | OpenAPI 错误码发生变更 | 查看变更详情 |
2024-04-12 | OpenAPI 错误码发生变更 | 查看变更详情 |
2024-01-23 | OpenAPI 错误码发生变更、OpenAPI 入参发生变更 | 查看变更详情 |
2023-11-20 | OpenAPI 错误码发生变更 | 查看变更详情 |
2023-05-12 | OpenAPI 错误码发生变更 | 查看变更详情 |
2023-04-25 | OpenAPI 错误码发生变更 | 查看变更详情 |
2023-03-15 | OpenAPI 错误码发生变更 | 查看变更详情 |
2022-01-06 | OpenAPI 错误码发生变更 | 查看变更详情 |
2022-01-06 | OpenAPI 错误码发生变更 | 查看变更详情 |