云服务器
云服务器
文档指南
请输入
- 文档首页
云服务器云服务器ECSAPI参考补丁管理CreatePatchPlan - 创建补丁计划
复制全文
下载 pdfCreatePatchPlan - 创建补丁计划
文档反馈
问问助手调用CreatePatchPlan接口，创建一个补丁计划。
注意事项
补丁安装过程中存在业务中断、CPU飙升、IO飙升等潜在风险，会影响业务正常运行，请务必选择合适的时间执行补丁安装操作，比如业务低峰期。风险包括：
- 内核补丁安装后需重启服务器，将直接中断部署节点的业务服务。
- 补丁安装的文件解压、签名校验、系统文件替换操作，易引发CPU/IO资源争用，导致业务处理性能下降、应用闪退等问题，同时该过程可能大量占用网络带宽，影响跨节点业务通信。
调试
API Explorer
您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。
请求参数
Action string 必选 示例值：CreatePatchPlan
要执行的操作，取值：CreatePatchPlan。
Version string 必选 示例值：2020-04-01
API的版本，取值：2020-04-01。
UseDefaultBaseline boolean 可选 示例值：true
是否使用默认补丁基线。取值：
- true：使用默认补丁基线，补丁计划将按目标实例操作系统对应的默认基线执行扫描或扫描并安装补丁。
说明
取值为 true 时，无需填写 BaselineId。
- false（默认）：不使用默认补丁基线，必须通过 BaselineId 指定自定义补丁基线 ID。
Name string 必选 示例值：UbuntuBaseline
补丁计划名称。取值：
- 必须以字母、汉字开头。
- 只能包含中文、字母、数字、下划线“_”、中划线“-”、英文句号“.”。
- 长度限制为1～64个字符。
Description string 可选 示例值：The description of baseline.
补丁计划描述，取值：
- 必须以字母或中文开头。
- 只能包含中文、字母、数字、下划线“_”、中划线“-”、等号“=”、英文逗号“,”、英文句号“.”、中文逗号“、”中文句号“。”和空格。
- 长度限制在0～256个字符之间。
说明
不填则默认为空。
RepeatMode string 可选 示例值：Once
设置计划执行方式。取值：
- Once（默认）：立即执行
- Recurrence：周期执行
- Scheduled：定时执行
ScheduledPolicy object 可选 示例值：--
定时/周期策略。
说明
仅当任务执行方式为定时/周期时需要配置本参数。
RecurrenceEndTime string 可选 示例值：2025-12-09T20:45Z
周期任务的结束时间。
RecurrenceType string 可选 示例值：Daily
周期任务的重复周期，取值：
- Daily：按天重复执行，例如每2天执行一次。
- Weekly：按周重复执行，每天执行一次。
- Monthly：按月重复执行，例如每月2号至8号，每日执行一次。
- Cron：按指定的Cron表达式重复执行。
LaunchTime string 必选 示例值：2022-04-01T16:00Z
任务的触发时间。
说明
- 如果指定了ScheduledPolicy.RecurrenceType，则为周期任务开始时间。
- 当RepeatMode取值为Once时，本参数无效。
RecurrenceValue string 可选 示例值：1
重复执行周期任务的数值。取值：字符串类型，如 "10"。
OperationType string 必选 示例值：Scan
设置补丁计划执行类型，取值：
- Scan：仅扫描补丁。
- Install：扫描并安装补丁。
AutoCreateSnapshot boolean 可选 示例值：true
是否为系统盘创建快照，取值：
- false（默认）：不创建快照。
- true：自动为系统盘创建快照，且快照默认保存时间为7天。
AutoReboot boolean 可选 示例值：true
选择补丁安装完成后是否自动重启实例，取值：
- false（默认）：无需自动重启实例。
- true：自动重启实例。
说明
仅OperationType参数选择Install时，需要配置。
补丁安装后是否需要重启，取决于其对应的组件类型，一般分两类：
- 需要重启生效：内核相关补丁、核心系统库补丁、守护进程 / 服务类包补丁等。
- 无需重启即可生效：用户态工具、CLI 工具类等。
TargetType string 必选 示例值：ECS
目标实例的筛选类型。取值：
- ECS：ECS实例。
- Tag：按标签筛选目标实例。
- Project：按实例所属项目筛选目标实例。
TargetValue string 必选 示例值：["i-xffsafgewgdf****"]
目标筛选类型对应的值（JSON格式字符串），取值：
- ECS：当TargetType为ECS实例时，该值为ECS实例ID列表。最大数量为200个实例。
- Tag：当TargetType是Tag时，该值为Tag键值对列表，最大数量为10个标签。
- Project：当TargetType是Project时，该值为单个ProjectName。
MaxConcurrency string 可选 示例值：10
指定任务执行过程中，允许同时运行命令的最大实例数量。取值：
- 默认值：50
- 取值范围
- 数量：0～100
- 百分比：0～100%
MaxErrors string 可选 示例值：10
任务执行过程中允许的最大错误实例数量。取值：
- 默认值：0
- 取值范围
- 数量：0～100。
- 百分比：0～100%
说明
当执行失败的实例数量超过该阈值时，系统将停止向剩余未执行的实例下发命令。
ClientToken string 可选 示例值：example
保证请求幂等性。由客户端自动生成一个参数值，确保不同请求间该参数值唯一，避免当调用API超时或服务器内部错误时，客户端多次重试导致重复性操作。取值：
- 仅支持ASCII字符。
- 长度不超过64个字符。
返回参数
PatchPlanId string 示例值：pp-yedfvyt41q5s2jax****
补丁计划ID。
请求示例
POST /?Version=2020-04-01&Action=CreatePatchPlan HTTP/1.1
Host: ecs.cn-beijing.volcengineapi.com
AccessKey: AK*****************
SecretKey: TXpS***************
ServiceName: ecs
Region: cn-beijing
X-Top-Account-Id: 21000*****
Content-Type: application/json
{
"Name": "Weekly-Prod-Patching",
"Description": "Production environment patch on Sunday early morning every week",
"UseDefaultBaseline": false,
"BaselineId": "bl-12345678abcd****",
"OperationType": "Install",
"RepeatMode": "Recurrence",
"ScheduledPolicy": {
"RecurrenceType": "Cron",
"RecurrenceValue": "0 2 * * 0",
"LaunchTime": "2026-01-08T17:45Z",
"RecurrenceEndTime": "2026-03-08T17:45Z"
},
"TargetType": "Tag",
"TargetValue": "[{"Key":"env","Values":["prod"]}]",
"AutoReboot": true,
"AutoCreateSnapshot": true,
"MaxConcurrency": "10",
"MaxErrors": "5%"
}
返回示例
{
"ResponseMetadata": {
"RequestId": "202601221007070707****",
"Action": "CreatePatchPlan",
"Version": "2020-04-01",
"Service": "ecs",
"Region": "cn-beijing"
},
"Result": {
"PatchPlanId": "pp-87654321zy****"
}
}
错误码
状态码 | 错误码 | 错误信息 | 说明 |
400 | InvalidArgument | The specified argument is invalid. | 指定的参数不合法。 |
500 | InternalError | An internal error has occurred. | 内部错误，请重试。如果多次尝试失败，请提交工单。 |
最近更新时间：2026.03.03 16:14:47
这个页面对您有帮助吗？
有用
有用
无用
无用