云服务器 ECS：RunCommand - 创建并执行云助手命令

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

命令执行的资源组 ID，当指定该参数时：

• InstanceId 对应的 ECS 实例必须属于该资源组。

• 支持通过指定该参数筛选出对应的命令执行结果（通过调用 DescribeInvocations 或 DescribeInvocationResults ）。

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

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

运维命令的语言类型。取值范围：

• RunBatScript：适用于 Windows 实例的 Bat 命令。
• RunPowerShellScript：适用于 Windows 实例的 PowerShell 命令。
• RunShellScript：适用于 Linux 实例的 Shell 命令。

命令内容。命令内容可以是明文内容或 Base64 编码后的内容。您需要注意：

• 若保存命令，命令内容在 Base64 编码后的大小不能超过 18 KB；若不保存命令，命令内容在 Base64 编码后的大小不能超过 24 KB。您可通过KeepCommand设置是否保留命令。

• 如果您的命令内容是 Base64 编码后的内容，则必须设置ContentEncoding=Base64。

• 指定参数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。通过调用本接口执行命令时，如需指定{{ACS::CommandId}}作为内置环境参数，需确保云助手 Agent 不低于以下版本：
    • Linux：2.2.3.309
    • Windows：2.1.3.309

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

默认值：

• Linux 系统实例默认在管理员（root 用户）的 home 目录下，即/root。
• Windows 系统实例默认在云助手 Agent 进程所在目录，例如C:\Windows\System32。

执行命令的超时时间，单位：秒。

当因为进程原因、缺失模块、缺失云助手 Agent 等原因无法运行命令时，会出现超时现象。超时后，会强制终止命令进程。

默认值：60。

命令中是否包含自定义参数。

默认值：false。

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

• Once：立即执行命令。
• Period：定时执行命令。当该参数取值为Period时，必须同时指定Frequency参数。
• NextRebootOnly：当实例下一次启动时，自动执行命令。
• EveryReboot：实例每一次启动都将自动执行命令。

默认值：

• 当不指定Frequency参数时，默认值为Once。
• 当指定Frequency参数时，无论是否已设置了该参数值，都将按照Period处理。

注意事项：

• 您可以调用 StopInvocation 停止待执行的命令或定时执行的命令。
• 当该参数取值Period或者EveryReboot时，您可以调用 DescribeInvocationResults ，然后指定IncludeHistory=true查看命令定时执行的历史记录。

定时执行命令的执行时间。目前支持三种定时执行方式：固定时间间隔执行（基于 Rate 表达式）、仅在指定时间执行一次、基于时钟定时执行（基于 Cron 表达式）。

• 固定时间间隔执行：基于 Rate 表达式，按照设置的时间间隔执行命令。时间间隔支持按秒（s） 、分钟（m） 、小时（h）和天（d）来选择，适用于在固定时间间隔执行任务的场景。格式为rate(<执行间隔数值><执行间隔单位>)，如 5 分钟执行一次，格式为rate(5m)。使用固定时间间隔执行有以下限制：

  • 设置的时间间隔不大于 7 天、不小于 60 秒，且需大于定时任务的超时时间。
  • 执行间隔只基于固定频率，与任务实际执行需要的时间无关。例如设置每 5 分钟执行一次命令，任务需要 2 分钟执行完成，则在任务完成 3 分钟后继续执行下一轮。
  • 创建任务时不会立即执行。例如设置每 5 分钟执行一次命令，创建任务时不会立即执行一次命令，而是在任务创建完成后的 5 分钟后开始执行。

• 仅在指定时间执行一次：按照设置的时区和执行时间点执行一次命令。格式为at(yyyy-MM-dd HH:mm:ss <时区>)，即at(年-月-日 时:分:秒 <时区>)。如果不指定时区，默认为 UTC 时区。时区支持以下三种形式：

  • 时区全称： 如Asia/Shanghai（中国/上海时间）、America/Los_Angeles（美国/洛杉矶时间）等。
  • 时区相对于格林威治时间的偏移量： 如GMT+8:00（东八区）、GMT-7:00（西七区）等。使用 GMT 格式时，小时位不支持添加前导零。
  • 时区缩写： 仅支持 UTC（协调世界时间）。

  如果指定在中国/上海时间 2022 年 06 月 06 日 13 时 15 分 30 秒执行一次，格式为：at(2022-06-06 13:15:30 Asia/Shanghai)；如果指定在西七区 2022 年 06 月 06 日 13 时 15 分 30 秒执行一次，格式为：at(2022-06-06 13:15:30 GMT-7:00)。

• 基于时钟定时执行（基于 Cron 表达式）：基于 Cron 表达式，按照设置的定时任务执行命令。格式为<秒> <分钟> <小时> <日期> <月份> <星期> <年份（可选）> <时区>，即<Cron 表达式> <时区>。在指定的时区下，根据 Cron 表达式推算定时任务执行时间并执行。若不指定时区，默认为执行定时任务实例的系统内部时区。关于 Cron 表达式的更多信息，请参见 Cron 表达式。时区支持以下三种形式：

  • 时区全称： 如Asia/Shanghai（中国/上海时间）、America/Los_Angeles（美国/洛杉矶时间）等。

  • 时区相对于格林威治时间的偏移量： 如GMT+8:00（东八区）、GMT-7:00（西七区）等。使用 GMT 格式时，小时位不支持添加前导零。

  • 时区缩写： 仅支持 UTC（协调世界时间）。 例如，在中国/上海时间，2022 年每天上午 10:15 执行一次命令，格式为0 15 10 ? * * 2022 Asia/Shanghai；在东八区时间，2022 年每天上午 10:00 到 11:30 每隔半小时执行，格式为0 0/30 10-11 * * ? 2022 GMT+8:00；在 UTC 时间，从 2022 年开始，每隔两年的 10 月每天下午 14:00 到下午 14:55 时间段内每隔 5 分钟执行，格式为0 0/5 14 * 10 ? 2022/2 UTC。

  说明 设置的最小时间间隔需大于或等于定时任务的超时时间，且不小于 10 秒。

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

自定义参数的个数范围为 0~10，且您需要注意：

• 键不允许为空字符串，最多支持 64 个字符。
• 值允许为空字符串。
• 自定义参数与原始命令内容在 Base64 编码后，若保存命令，命令内容在 Base64 编码后的大小不能超过 18 KB；若不保存命令，命令内容在 Base64 编码后的大小不能超过 24 KB。您可通过KeepCommand设置是否保留命令。
• 设置的自定义参数名集合必须为创建命令时定义的参数集的子集。对于未传入的参数，您可以使用空字符串代替。

默认值为空，表示取消设置该参数从而禁用自定义参数。

执行完该命令后，是否保留下来。取值范围：

• true：保留。可以通过 InvokeCommand 再次执行。会占用云助手命令的保有量配额。
• false：不保留。执行完成后自动删除，不占用云助手命令的保有量配额。

默认值：false。

命令内容（CommandContent）的编码方式。取值范围（不区分大小写）：

• PlainText：不编码，采用明文传输。
• Base64：Base64 编码。

默认值：PlainText，乱填或错填该取值会当作 PlainText 处理。

在 ECS 实例中执行命令的用户名称。长度不得超过 255 个字符。

• Linux 系统的 ECS 实例，默认以 root 用户执行命令。
• Windows 系统的 ECS 实例，默认以 System 用户执行命令。

您也可以指定实例中已存在的其他用户执行命令，以普通用户执行云助手命令更加安全。更多信息，请参见设置普通用户执行云助手命令。

在 Windows 实例中执行命令的用户的密码名称。长度不得超过 255 个字符。

当您希望以非默认用户（System）在 Windows 实例中执行命令时，需要同时传入Username和该参数。为降低密码泄露的风险，需要将密码明文托管在系统运维管理的参数仓库中，此处仅传入密码的名称。更多信息，请参见加密参数以及设置普通用户执行云助手命令。

ECS 实例 ID。N 表示您可以同时设置多个实例 ID，N 的取值范围：1~100。

若指定了多台实例后，其中某台实例不满足执行条件时，您都需要重新选择。

您也可以在配额中心申请提升配额（配额名称为命令执行支持实例上限数）。

标签列表。

容器 ID。仅支持 64 位 16 进制字符串，允许存在docker://、containerd://或者cri-o://前缀来明确指定的容器运行时。

注意事项：

• 如果指定了该参数，云助手将在实例的指定容器内执行脚本。
• 如果指定了该参数，仅支持在云助手 Agent 版本不低于 2.2.3.344 的 Linux 实例内运行。
• 如果指定了该参数，已指定的Username参数和WorkingDir参数将不会生效。仅支持通过容器默认用户在容器的默认工作目录下执行命令。详细信息，请参见使用云助手在容器内执行命令。
• 如果指定了该参数，在 Linux 容器中只支持执行 Shell 脚本，不支持在脚本开头使用类似#!/usr/bin/python命令的形式指定脚本内容的解释器。详细信息，请参见使用云助手在容器内执行命令。

容器名称。

注意事项：

• 如果指定了该参数，云助手将在实例的指定容器内执行脚本。
• 如果指定了该参数，仅支持在云助手 Agent 版本不低于 2.2.3.344 的 Linux 实例内运行。
• 如果指定了该参数，已指定的Username参数和WorkingDir参数将不会生效。仅支持通过容器默认用户在容器的默认工作目录下执行命令。详细信息，请参见使用云助手在容器内执行命令。
• 如果指定了该参数，在 Linux 容器中只支持执行 Shell 脚本，不支持在脚本开头使用类似#!/usr/bin/python命令的形式指定脚本内容的解释器。详细信息，请参见使用云助手在容器内执行命令。

保证请求幂等性。从您的客户端生成一个参数值，确保不同请求间该参数值唯一。ClientToken 只支持 ASCII 字符，且不能超过 64 个字符。更多信息，请参见如何保证幂等性。

用于筛选实例的标签列表。可以在不指定 InstanceId 的情况下，向具有相同标签的实例批量执行命令。

停止任务（手动停止或执行超时打断）时的模式。可能值：

• Process：停止当前脚本进程。
• ProcessTree：停止当前进程树（脚本进程以及它创建的所有子进程的集合）。

脚本执行的引导程序。长度不能超过 1 KB。