云服务器 ECS：InvokeCommand - 执行云助手命令

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

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

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

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

命令 ID。您可以通过接口 DescribeCommands 查询所有可用的 CommandId。

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

• 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 秒。

启用自定义参数功能时，执行命令时传入的自定义参数的键值对。自定义参数的个数范围为 0~10。

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

您可以取消设置该参数从而禁用自定义参数。

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

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

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

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

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

需要执行命令的实例列表，最多能指定 100 台实例 ID。N 的取值范围为 1~100。

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

容器 ID。仅支持 64 位 16 进制字符串。支持使用docker://、containerd://或者cri-o://前缀来表示指定的容器运行时。

注意事项：

• 如果指定了该参数，云助手将在实例的指定容器内执行脚本。

• 如果指定了该参数，仅支持在云助手 Agent 版本不低于 2.2.3.344 的 Linux 实例内运行。

  • 查看云助手 Agent 版本的具体操作，请参见安装云助手 Agent 。
  • 升级云助手 Agent 版本的具体操作，请参见升级或禁止升级云助手 Agent。

• 如果指定了该参数，本接口中已指定的Username参数和 CreateCommand 中指定的WorkingDir参数将不会生效。仅支持通过容器默认用户在容器的默认工作目录下执行命令。更多信息，请参见使用云助手在容器内执行命令。

• 如果指定了该参数，在 Linux 容器中只支持执行 Shell 脚本，不支持在脚本开头使用类似#!/usr/bin/python命令的形式指定脚本内容的解释器。更多信息，请参见使用云助手在容器内执行命令。

容器名称。

注意事项：

• 如果指定了该参数，云助手将在实例的指定容器内执行脚本。

• 如果指定了该参数，仅支持在云助手 Agent 版本不低于 2.2.3.344 的 Linux 实例内运行。

  • 查看云助手 Agent 版本的具体操作，请参见安装云助手 Agent 。
  • 升级云助手 Agent 版本的具体操作，请参见升级或禁止升级云助手 Agent。

• 如果指定了该参数，本接口中已指定的Username参数和 CreateCommand 中指定的WorkingDir参数将不会生效。仅支持通过容器默认用户在容器的默认工作目录下执行命令。更多信息，请参见使用云助手在容器内执行命令。

• 如果指定了该参数，在 Linux 容器中只支持执行 Shell 脚本，不支持在脚本开头使用类似#!/usr/bin/python命令的形式指定脚本内容的解释器。更多信息，请参见使用云助手在容器内执行命令。

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

• 该值不能小于 10 秒。

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

• 若不设置该值，会采用创建命令时指定的超时时间。

• 该值只会作为该次命令执行的超时时间，不会改变命令本身的超时时间。

标签列表。

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

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

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

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

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