文档

CreateCommand - 新建一条云助手命令

更新时间:

调用CreateCommand接口,并指定Name、Type、CommandContent等参数,新建一条Shell、PowerShell或者Bat脚本类型的云助手命令。

接口说明

  • 您可以创建以下类型的命令:
    • Windows 实例适用的 Bat 脚本(RunBatScript)。
    • Windows 实例适用的 PowerShell 脚本(RunPowerShellScript)。
    • Linux 实例适用的 Shell 脚本(RunShellScript)。
  • 您可以通过指定参数 Timeout 为命令设置在 ECS 实例中执行时最大的超时时间,命令执行超时后,云助手 Agent会强制终止命令进程,即取消命令的 PID。
    • 对于单次执行,超时后,该命令针对指定的 ECS 实例的执行状态( InvokeRecordStatus )变为执行失败(Failed)。
    • 对于定时执行:
      • 定时执行的超时时间对每一次执行记录均有效。
      • 某次执行超时后,该次执行记录的状态( InvokeRecordStatus )变为执行失败(Failed)。
      • 上次执行超时与否不影响下一次执行。
  • 在一个地域下,您最多可以保有 500~50,000 条云助手命令,您也可以申请提升配额,关于如何查询及提升配额,请参见配额管理
  • 您可以通过指定参数 WorkingDir 为命令指定执行路径。对于 Linux 实例,默认在管理员 root 用户的 home 目录下,具体为/root目录。对于 Windows 实例,默认在云助手 Agent 进程所在目录,例如:C:\Windows\System32
  • 您可以通过指定参数 EnableParameter=true 启用自定义参数功能。在设置 CommandContent 时可以通过{{parameter}}的形式表示自定义参数,并在运行命令( InvokeCommand )时,传入自定义参数键值对。例如,您在创建命令时,创建了echo {{name}}命令,在 InvokeCommand 时,通过 Parameters 参数传入键值对<name, Jack>。则自定义参数将自动替换命令,您会得到一条新的命令,并在实例中执行echo Jack

调试

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

授权信息

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

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

请求参数

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

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

cn-hangzhou
Namestring

命令名称,支持全字符集。长度不得超过 128 个字符。

testName
Descriptionstring

命令描述,支持全字符集。长度不得超过 512 个字符。

testDescription
Typestring

命令的类型。取值范围:

  • RunBatScript:创建一个在 Windows 实例中运行的 Bat 脚本。
  • RunPowerShellScript:创建一个在 Windows 实例中运行的 PowerShell 脚本。
  • RunShellScript:创建一个在 Linux 实例中运行的 Shell 脚本。
RunShellScript
CommandContentstring

命令 Base64 编码后的内容。

  • 该参数的值必须使用 Base64 编码后传输,且脚本内容的大小在 Base64 编码之后不能超过 18 KB。

  • 命令内容支持使用自定义参数形式,具体通过指定参数EnableParameter=true启用自定义参数功能:

    • 自定义参数用{{}}包含的方式定义,在{{}}内参数名前后的空格以及换行符会被忽略。
    • 自定义参数个数不能超过 20 个。
    • 自定义参数名允许 a-zA-Z0-9-_的组合,不支持 acs::前缀指定非内置环境参数,不支持其余字符,参数名不区分大小写。
    • 单个参数名不能超过 64 字节。
  • 您可以指定内置环境参数作为自定义参数,执行命令时无需手动对参数赋值,云助手将为您自动替换为环境中对应的值。支持指定以下内置环境参数:

    • {{ACS::RegionId}}:地域 ID。

    • {{ACS::AccountId}}:阿里云主账号 UID。

    • {{ACS::InstanceId}}:实例 ID。命令下发到多个实例时,如需指定{{ACS::InstanceId}}作为内置环境参数,需确保云助手 Agent 不低于以下版本:

      • Linux:2.2.3.309
      • Windows:2.1.3.309
    • {{ACS::InstanceName}}:实例名称。命令下发到多个实例时,如需指定{{ACS::InstanceName}}作为内置环境参数,需确保云助手 Agent 不低于以下版本:

      • Linux:2.2.3.344
      • Windows:2.1.3.344
    • {{ACS::InvokeId}}:命令执行 ID。如需指定{{ACS::InvokeId}}作为内置环境参数,需确保云助手 Agent 不低于以下版本:

      • Linux:2.2.3.309
      • Windows:2.1.3.309
    • {{ACS::CommandId}} :命令 ID。通过调用 RunCommand 接口执行命令时,如需指定{{ACS::CommandId}}作为内置环境参数,需确保云助手 Agent 不低于以下版本:

      • Linux:2.2.3.309
      • Windows:2.1.3.309
ZWNobyAxMjM=
WorkingDirstring

您创建的命令在 ECS 实例中运行的目录。长度不得超过 200 个字符。

默认值:

  • Linux 实例:管理员 root 用户的 home 目录下,具体为/root目录。
  • Windows 实例:云助手 Agent 进程所在目录,例如C:\Windows\System32
说明 设置为其他目录时,请确保实例中存在该目录。
/home/user
Timeoutlong

您创建的命令在 ECS 实例中执行时最大的超时时间,单位为秒。当因为某种原因无法运行您创建的命令时,会出现超时现象。超时后,会强制终止命令进程,即取消命令的 PID。

默认值:60。

60
EnableParameterboolean

创建的命令是否使用自定义参数。

默认值:false。

false
ContentEncodingstring

命令内容(CommandContent)的编码方式。取值范围:

  • PlainText:不编码,采用明文传输。

  • Base64:Base64 编码。

默认值:Base64。

说明 错填该取值会当作 Base64 处理。
PlainText
ResourceGroupIdstring

命令所属的资源组 ID。

rg-123******
Tagarray<object>

标签列表。

object

标签列表。

Keystring

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

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

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

TestKey
Valuestring

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

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

TestValue

返回参数

名称类型描述示例值
object
CommandIdstring

命令 ID。

c-7d2a745b412b4601b2d47f6a768d****
RequestIdstring

请求 ID。

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

示例

正常返回示例

JSON格式

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

错误码

HTTP status code错误码错误信息描述
400RegionId.ApiNotSupportedThe api is not supported in this region.指定地域下不支持调用 API。请检查 RegionId 参数取值是否正确。
400CmdParam.EmptyKeyYou must specify the parameter names.请检查您的参数是否完整,是否有参数名未填写的情况。
400CmdParam.InvalidParamNameInvalid parameter name. The name can contain only lowercase letters (a to z), uppercase letters (A to Z), numbers (0 to 9), hyphens (-), and underscores (_).自定义参数的参数名无效,只允许 a-zA-Z0-9-_ 的组合。
400CmdContent.DecodeErrorThe CommandContent can not be base64 decoded.命令内容无法通过Base64解码。
400InvalidParameter.WorkingDirThe specified parameter WorkingDir is not valid.指定的参数WorkingDir不合法。
403CmdContent.ExceedLimitThe length of the command content exceeds the upper limit.命令内容长度超过上限。
403CmdName.ExceedLimitThe length of the command name exceeds the upper limit.命令名称长度超过上限。
403CmdDesc.ExceedLimitThe length of the command description exceeds the upper limit.命令描述长度超过上限。
403CmdCount.ExceedQuotaThe total number of commands in the current region exceeds the quota.当前地域下的云助手命令数量已超出限制。
403CmdParamCount.ExceedLimitThe maximum number of custom parameters is exceeded.参数数量超出最大可设置数量。
403CmdParamName.ExceedLimitThe maximum length of a parameter name is exceeded.您的自定义参数的参数名长度超过限制。
403Operation.ForbiddenThe operation is not permitted.该操作是不被允许的。
403InvalidStatus.ResourceGroupYou cannot perform an operation on a resource group that is being created or deleted.资源组正在创建或删除时不允许操作。
403InvalidParameterCharacter.CommandNameThe command Name contains illegal characters.命令名称包含非法字符。
403InvalidParameterCharacter.CommandDescriptionThe command Description contains illegal characters.命令描述包含非法字符。
403InvalidParameterCharacter.CommandWorkingDirThe command WorkingDir contains illegal characters.命令执行路径包含非法字符。
404InvalidCmdType.NotFoundThe specified command type does not exist.指定的命令类型不存在。
404InvalidRegionId.NotFoundThe RegionId provided does not exist in our records.提供的RegionId不存在
404InvalidResourceGroup.NotFoundThe ResourceGroup provided does not exist in our records.资源组并不在记录中。
500InternalError.DispatchAn error occurred when you dispatched the request.发送请求时发生错误,请稍后重试。

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

变更历史

变更时间变更内容概要操作
2024-05-11OpenAPI 错误码发生变更查看变更详情
2023-10-24OpenAPI 错误码发生变更、OpenAPI 入参发生变更查看变更详情
2023-05-12OpenAPI 错误码发生变更查看变更详情
2022-02-25OpenAPI 错误码发生变更查看变更详情