调用CreateCommand新建一条云助手命令。

接口说明

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

调试

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

请求参数

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

系统规定参数。取值:CreateCommand

RegionId String cn-hangzhou

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

Name String testName

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

Description String testDescription

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

Type String RunShellScript

命令的类型。取值范围:

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

命令Base64编码后的内容。

  • 该参数的值必须使用Base64编码后传输,且脚本内容的大小在Base64编码之后不能超过18 KB。
  • 命令内容支持使用自定义参数形式,具体通过指定参数EnableParameter=true启用自定义参数功能:
    • 自定义参数用{{}}包含的方式定义,在{{}}内参数名前后的空格以及换行符会被忽略。
    • 自定义参数个数不能超过20个。
    • 自定义参数名允许a-zA-Z0-9-_的组合,不支持其余字符,参数名不区分大小写。
    • 单个参数名不能超过64字节。
  • 您可以指定内置环境参数作为自定义参数,执行命令时无需手动对参数赋值,云助手将为您自动替换为环境中对应的值。支持指定以下内置环境参数:
    • {{ACS::RegionId}}:地域ID。
    • {{ACS::AccountId}}:阿里云主账号UID。
    • {{ACS::InstanceId}}:实例ID。命令下发到多个实例时,如需指定{{ACS::InstanceId}}作为内置环境参数,需确保云助手客户端不低于以下版本:
      • Linux:2.2.3.309
      • Windows:2.1.3.309
    • {{ACS::InvokeId}}:命令执行ID。如需指定{{ACS::InvokeId}}作为内置环境参数,需确保云助手客户端不低于以下版本:
      • Linux:2.2.3.309
      • Windows:2.1.3.309
    • {{ACS::CommandId}} :命令ID。通过调用RunCommand接口执行命令时,如需指定{{ACS::CommandId}}作为内置环境参数,需确保云助手客户端不低于以下版本:
      • Linux:2.2.3.309
      • Windows:2.1.3.309
WorkingDir String /root/

您创建的命令在ECS实例中运行的目录。

默认值:

  • Linux实例:管理员root用户的home目录下,具体为/root目录。
  • Windows实例:云助手客户端进程所在目录,例如C:\Windows\System32
Timeout Long 60

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

默认值:60。

EnableParameter Boolean false

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

默认值:false。

ContentEncoding String PlainText

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

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

默认值:Base64。

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

返回数据

名称 类型 示例值 描述
CommandId String c-7d2a745b412b4601b2d47f6a768d****

命令ID。

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

请求ID。

示例

请求示例

http(s)://ecs.aliyuncs.com/?Action=CreateCommand
&CommandContent=ZWNobyB7e25hbWV9fSA=
&Name=testName
&RegionId=cn-hangzhou
&Type=RunShellScript
&Description=testDescription
&WorkingDir=/root/
&Timeout=60
&EnableParameter=true
&ContentEncoding=Base64
&公共请求参数

正常返回示例

XML格式

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

<CreateCommandResponse>
    <CommandId>c-7d2a745b412b4601b2d47f6a768d****</CommandId>
    <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3****</RequestId>
</CreateCommandResponse>

JSON格式

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

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

错误码

HttpCode 错误码 错误信息 描述
400 RegionId.ApiNotSupported The api is not supported in this region. 指定地域下不支持调用 API。请检查 RegionId 参数取值是否正确。
403 InvalidCmdType.NotFound The specified command type does not exist. 指定的命令类型不存在。
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 CmdParam.EmptyKey You must specify the parameter names. 请检查您的参数是否完整,是否有参数名未填写的情况。
403 CmdParam.InvalidParamName Invalid 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-_ 的组合。
403 CmdParamName.ExceedLimit The maximum length of a parameter name is exceeded. 您的自定义参数的参数名长度超过限制。
403 Operation.Forbidden The operation is not permitted. 该操作是不被允许的。
500 InternalError.Dispatch An error occurred when you dispatched the request. 发送请求时发生错误,请稍后重试。

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