You need to enable JavaScript to run this app.
导航
云服务器
  • 文档首页
    • /云服务器/云服务器ECS/API参考/批量作业/RunCommand
RunCommand
最近更新时间：2024.06.24 15:56:45首次发布时间：2023.09.04 15:43:18
我的收藏

调用RunCommand接口，创建批量作业并在一台或多台ECS实例中立即执行。

说明

  • 不同于通过CreateCommand接口创建自定义命令和InvokeCommand执行已有命令，RunCommand接口支持在一次调用中完成命令的创建与执行。
  • 可通过ParameterDefinitions.N.xxx参数在命令中配置自定义参数，使用规则如下：
    • 参数 - N：表示自定义参数的序号，取值范围：1～60。
    • 多个自定义参数之间用&分隔。

调试

API Explorer
您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。
去调试

请求参数

名称类型是否必填示例值描述
ActionString是RunCommand要执行的操作，取值：RunCommand。
VersionString是2020-04-01接口的版本，取值：2020-04-01。

Type

String

是

Shell

命令的类型。取值：

  • Shell：表示创建一个在Linux实例中运行的Shell脚本。
  • Python：表示创建一个Python脚本。
  • Bat：表示创建一个Bat脚本。
  • PowerShell：表示创建一个PowerShell脚本。

ContentEncoding

String

否

Base64

命令内容是否经过Base64编码处理。取值：

  • Base64（默认）：经过Base64编码处理。
  • PlainText： 未进行编码处理。

CommandContent

String

是

IyEvYm****aW9uIHN1Y2Nlc3MhIg%3D%3D

命令内容。

说明

  • 请确保编码前的脚本，首行指定了脚本解释器。规则如下：
    • Shell脚本：首行需为#!/bin/bash。
    • Python脚本：首行需为#!/usr/bin/python。
  • 命令内容不能超过16KB。
  • 不支持自定义参数。
WorkingDirString否/home创建的命令在ECS实例中运行的目录。Linux实例默认为/home。

Username

String

否

root

执行命令时的用户名。
默认值：root。

Timeout

Integer

否

60

创建的命令在ECS实例中执行时最大的超时时间，单位为秒。

  • 取值范围：30 ~ 86400。
  • 默认值：60。

说明

超时后，批量作业会强制终止命令进程。

InvocationName

String

是

test

作业名称。需符合如下规则：

  • 不超过64个字符。
  • 只能包含中文、字母、数字、下划线“_”、中划线“-”、且不能以数字，中划线开头。
  • 同地域下作业名称可重复。

InvocationDescription

String

否

description

作业描述，默认为空字符串。

  • 不超过256个字符。

InstanceIds.N

String

是

InstanceIds.1=i-bp185dy2o3o6neg****&InstanceIds.2=i-bp185dy2o3o7neg****

实例ID列表，最多支持100个ID。您可以调用DescribeInstances接口查询获取实例ID。

  • 参数 - N：表示实例的序号。
  • 多个Instance ID之间用&分隔。

说明

若指定了多台实例，但其中存在实例不满足执行条件时（例如：实例处于关机等不可用状态），都需要重新指定。

RepeatMode

String

否

Once

设置命令执行的方式。取值：

  • Once：默认，表示立即执行作业。
  • Rate：周期执行作业，需要通过Frequency参数传入Rate表达式指定执行周期。
  • Fixed：定时执行作业，需要通过LaunchTime参数指定的执行时间。

Frequency

String

否

5m

执行频率。仅RepeatMode=Rate时本参数必填。请按如下格式传入Rate表达式指定执行周期：

  • <执行间隔数值><执行间隔单位>
    • 执行间隔单位：支持分钟（m）、小时（h）和天（d），适用于在固定时间间隔执行作业的场景。
    • 时间间隔数值范围：5～60（分钟），1～24（小时），1～7（天），且间隔需大于作业的超时时间。
  • 执行间隔基于固定频率，与作业实际执行需要的时间无关。
  • 创建作业后基于LaunchTime执行一次，根据间隔设置确定下一次执行时间。

LaunchTime

String

否

2022-11-07T11:49:13Z

执行时间。

  • RepeatMode=Rate时，需按如下格式传入作业首次执行时间：
    • 时间格式：RFC3339，例如：2022-11-07T11:49:13Z。
  • RepeatMode=Fixed时，需按如下格式传入作业开始执行时间：
    • 时间格式：RFC3339，例如：2022-11-07T11:49:13Z。

RecurrenceEndTime

String

否

2022-11-07T11:49:13Z

周期结束时间，RFC3339 格式。

说明

仅RepeatMode为Rate（周期执行作业）时需填写。

EnableParameter

Boolean

否

false

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

  • false：默认，表示不使用自定义参数。
  • true：表示使用自定义参数。

ParameterDefinitions.N.Name

String

否

ParameterDefinitions.1.Name=dir

自定义参数名称，需要在脚本中通过{{Param}}定义 。命名规则：

  • 单个参数名不能超过64字节。
  • 遵循Shell变量命名规则，a-zA-Z0-9-_的组合。首个字符不能以数字开头。中间不能有空格，可以使用下划线。

ParameterDefinitions.N.Type

String

否

ParameterDefinitions.1.Type=String

自定义参数类型。取值：

  • String：表示自定义参数类型为String（字符串）类型。
  • Digit：表示自定义参数类型为Digit（数值）类型。

ParameterDefinitions.N.Required

Boolean

否

ParameterDefinitions.1.Required=true

自定义参数是否必填。取值：

  • true：必填。
  • false：非必填。

说明

必填时，需在Parameters参数中传入自定义参数值。

ParameterDefinitions.N.DefaultValue

String

否

ParameterDefinitions.1.DefaultValue=ecs

自定义参数默认值。

说明

请根据Type参数指定的参数类型，填写相应类型的默认值。

ParameterDefinitions.N.MinLength

Integer

否

ParameterDefinitions.1.MinLength=1

自定义参数值（字符串）的最小长度。

说明

  • MinLength取值范围：1~1000。
  • Type=String时必填，且Required参数为true时默认为1。
  • 本参数值需小于MaxLength。

ParameterDefinitions.N.MaxLength

Integer

否

ParameterDefinitions.1.MaxLength=98

自定义参数值（字符串）的最大长度。

说明

  • MaxLength取值范围：1~1000。
  • Type=String时必填，且Required参数为true时默认为1000。
  • 本参数值需大于MinLength。

ParameterDefinitions.N.MinValue

String

否

ParameterDefinitions.1.MinValue=1

自定义参数值（数值）的最小值。

说明

  • MinValue取值范围：-1000000~1000000。
  • Type=Digit时必填，且Required参数为true时默认为-1000000。
  • 本参数值需小于MaxValue。

ParameterDefinitions.N.MaxValue

String

否

ParameterDefinitions.1.MaxValue=100

自定义参数值（数值）的最大值。

说明

  • MaxValue取值范围：-1000000~1000000。
  • Type=Digit时必填，且Required参数为true时默认为1000000。
  • 本参数值需小于MinValue。

ParameterDefinitions.N.DecimalPrecision

Integer

否

ParameterDefinitions.1.DecimalPrecision=4

自定义参数值（数值）允许的小数点后位数。

说明

  • DecimalPrecision取值范围：0~10。
  • Type=Digit时必填，且Required参数为true时默认为0。

Parameters

String

否

{"username":"root","password":"123456"}

命令中包含自定义参数时，需通过本参数传入自定义参数的键值对。 例如：命令内容为echo {{name}}，则可以通过Parameter参数传入键值对{"name":"Jack"}。自定义参数将自动替换变量值name，得到一条新的命令，实际执行的是echo Jack。
自定义参数规则如下：

  • 自定义参数个数范围为0~60。
  • Key不允许为空字符串，最多支持64个字符。
  • Value允许为空字符串。
  • 自定义参数与原始命令内容在Base64编码后，综合长度不能超过16KB。
  • 设置的自定义参数名集合必须为创建命令时定义的参数集的子集。对于未传入的参数，使用默认值代替。

返回数据

名称类型示例值描述
InvocationIdStringivk-2a745b412b4601b2d47f6a768d****作业ID。

请求示例

GET /?Action=RunCommand&Version=2020-04-01&CommandContent=IyEvYm****aW9uIHN1Y2Nlc3MhIg%3D%3D&Username=root&InvocationName=test&InstanceIds.1=i-bp185dy2o3o6neg****&InstanceIds.2=i-bp185dy2o3o7neg**** HTTP/1.1
Host: open.volcengineapi.com
Region: cn-beijing
Service: ecs

返回示例

{
    "ResponseMetadata": {
        "RequestId": "202106111445100102252431000052****",
        "Action": "RunCommand",
        "Version": "2020-04-01",
        "Service": "ecs",
        "Region": "cn-beijing"
    },
    "Result": {
        "InvocationId": "ivk-2a745b412b4601b2d47f6a768d****"
    }
}

错误码

您可访问公共错误码，获取更多错误码信息。