全部产品
Search
文档中心

云服务器 ECS:ModifyInvocationAttribute - 修改任务的执行信息

更新时间:Nov 29, 2024

修改云助手定时任务的执行信息,包括命令内容、定时执行方式、添加ECS实例或托管实例到任务。

接口说明

  • 支持修改以下执行方式的任务(参见 DescribeInvocations 返回的RepeatMode值):
    • Period:周期执行。
    • NextRebootOnly:当实例下一次启动时,自动执行命令。
    • EveryReboot:实例每一次启动都将自动执行命令。
  • 支持修改以下状态的任务(参见 DescribeInvocations 返回的InvocationStatus值):
    • Pending:系统正在校验或发送命令。存在至少一台实例的命令执行状态为 Pending,则总执行状态为 Pending。
    • Running:命令正在实例上运行。存在至少一台实例的命令执行状态为 Running,则总执行状态为 Running。
    • Scheduled:定时执行的命令已发送,等待运行。存在至少一台实例的命令执行状态为 Scheduled,则总执行状态为 Scheduled。
    • Stopping:正在停止任务。存在至少一台实例的命令执行状态为 Stopping,则总执行状态为 Stopping。
  • 修改定时任务执行信息(包括命令内容、自定义参数、执行频率)前,已执行的 ECS 实例或托管实例的云助手 Agent 版本需要高于以下对应的版本。
    • Linux:2.2.3.541
    • Windows:2.1.3.541
    • 如果调用结果返回InvalidOperation.CloudAssistantVersionUnsupported错误码,请将云助手 Agent 更新至最新版本。
  • 当您执行一个云助手公共命令时,无法修改命令内容CommandContent
  • 当您修改了命令内容CommandContent,且调用 InvokeCommand 或调用 RunCommand 时设置KeepCommandtrue创建任务,将会新增一条命令并长期保留,并占用云助手命令配额;在一个地域下,您最多可以保有 500~50,000 条云助手命令。您也可以申请提升配额,关于如何查询及提升配额,请参见配额管理

调试

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

授权信息

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

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

请求参数

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

地域 ID。

cn-hangzhou
InstanceIdarray

待加入任务的 ECS 实例 ID 或托管实例 ID。

string

待加入任务的 ECS 实例 ID 或托管实例 ID。待加入的实例数量与已执行的实例数量总和不得超过 100。

i-bp1i7gg30r52z2em****
InvokeIdstring

待修改任务的命令执行 ID。

t-hz0jdfwd9f****
CommandContentstring

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

  • 若创建待修改任务时选择了保存命令,命令内容在 Base64 编码后的大小不能超过 18 KB;若选择了不保存命令,命令内容在 Base64 编码后的大小不能超过 24 KB。

  • 如果您的命令内容是 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
ZWNobyAxMjM=
EnableParameterboolean

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

  • 当您启用自定义参数或修改自定义参数Parameters时,该参数需设置为true
  • 当您不修改自定义参数Parameters时,不设置该参数或设置为false
false
Parametersobject

命令中包含自定义参数时,修改执行命令时传入的自定义参数的键值对。

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

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

默认值为空,表示不涉及自定义参数键值对的修改。

{"name":"Jack", "accessKey":"LTAIdyvdIqaRY****"}
Frequencystring

待修改的定时执行频率。仅当RepeatModePeriod时生效。目前支持三种定时执行方式:固定时间间隔执行(基于 Rate 表达式)、仅在指定时间执行一次、基于时钟定时执行(基于 Cron 表达式)。

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

    • 设置的时间间隔不大于 7 天、不小于 60 秒,且需大于创建定时任务时指定的超时时间。
    • 执行间隔只基于固定频率,与任务实际执行需要的时间无关。例如设置每 5 分钟执行一次命令,任务需要 2 分钟执行完成,则在任务完成 3 分钟后继续执行下一轮。
    • 按照任务的创建时间(参见DescribeInvocations返回的 CreationTime ,请注意不是修改时间)及修改后的执行间隔计算下一次执行时间。
  • 仅在指定时间执行一次:按照设置的时区和执行时间点执行一次命令。格式为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 */20 * * * *
ContentEncodingstring

命令内容(CommandContent)的编码方式。取值范围(不区分大小写):

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

默认值:PlainText,填写错误时会当作 PlainText 处理。

PlainText

返回参数

名称类型描述示例值
object
RequestIdstring

请求 ID。

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

命令 ID。

  • 只有CommandContent发生变更,才新增一条命令,返回新增的CommandId
  • CommandContent未变更时,不会新增命令,将返回当前正在执行命令的CommandId
  • 若调用 InvokeCommand ,或调用 RunCommand 时选择了KeepCommandtrue,将会保留新增的命令;否则执行完成或手动停止任务时,将删除任务所有关联的命令。
c-hz01272yr52****

示例

正常返回示例

JSON格式

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

错误码

HTTP status code错误码错误信息描述
400InvalidParameter.FrequencyThe specified parameter Frequency is not valid.指定的参数Frequency不合法。
400InvalidParameters.KeyDuplicateThe key in the parameter Parameters cannot be duplicated.参数Parameters中的键不能重复。
400InvalidParameters.KeyNotMatchThe key in the parameter Parameters do not match those defined when creating the command.参数Parameters中的键与创建命令时定义的不匹配。
400InvalidParameters.KeyMalformedThe key in the parameter Parameters is not valid.参数Parameters中的键不合法。
400InvalidParameters.KeyEmptyThe key in the parameter Parameters cannot be empty.参数Parameters中的键不能为空。
400InvalidCommandContent.DecodeErrorThe specified parameter CommandContent can not be Base64 decoded.参数CommandContent无法通过Base64解码。
403InvalidInstanceId.OSTypeUnsupportedThe OS type of the instance corresponding to the parameter InstanceId does not support the specified command type.参数InstanceId对应实例的操作系统类型不支持指定的命令类型。
403InvalidOperation.RepeatModeUnsupportedThe operation is not supported for current repeat mode of invocation.当前命令执行的方式不支持该操作。
403InvalidOperation.InvokeAlreadyFinishedThe operation is not supported for finished invocation.已执行完成的任务不支持该操作。
403InvalidOperation.CloudAssistantVersionUnsupportedThe operation is not supported for current CloudAssistant version of instance.当前实例的云助手版本不支持该操作。
403InvalidOperation.ModifyPublicCommandUnsupportedModification of the content of Public Command is not supported.不支持修改公共命令的内容。
403InvalidCommandContent.LengthLimitExceeded%s-
403InvalidParameters.CountLimitExceededThe count of the parameter Parameters exceeds the limit of 10.参数Parameters的数量超过了10的限制。
403InvalidParameters.KeyLengthLimitExceededThe length of the key in the parameter Parameters exceeds the limit of 64 characters.参数Parameters中键的长度超过了64个字符的限制。
403InvalidInstanceId.CountLimitExceeded%s-
403CommandLimitExceeded%s-
403InvalidParameters.ValueTypeUnsupportedThe type of the value in the parameter Parameters is not supported.不支持参数Parameters中值的类型。
404InvalidInvokeId.NotFoundThe specified parameter InvokeId does not exist.指定的命令执行ID不存在。
404InvalidInstanceId.NotFoundThe specified parameter InstanceId does not exist.指定的实例ID不存在。
404InvalidRegionId.NotFoundThe specified parameter RegionId does not exist.指定的地域ID不存在。
500InternalErrorAn error occurred when you dispatched the request.发送请求时发生错误,请稍后重试。

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

变更历史

变更时间变更内容概要操作
2024-04-03OpenAPI 错误码发生变更查看变更详情