AWS CLI 实操：使用 update-service-level-objective 更新 Application Signals 的 SLO 目标

AWS CLI 实操：使用 update-service-level-objective 更新 Application Signals 的 SLO 目标

【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli

本文以 aws-cli 仓库中的官方示例 update-service-level-objective.rst 为主体，讲解如何用 AWS CLI 对 Amazon CloudWatch Application Signals 中已有的服务级别目标（Service Level Objective，SLO）做局部更新：如何用--cli-input-json file://update-slo.json提交只含id与goal的最小更新请求，如何理解“省略即保留”的 PATCH 语义、输入输出 JSON 中各字段的含义与取值约束，并结合仓库内的服务模型定义（awscli/botocore/data/application-signals/2024-04-15/service-2.json）与 CLI 参数实现源码，说明该命令在底层如何被解析与发送。

命令形态：用--cli-input-json提交 JSON 文件

官方示例给出的完整调用方式如下（摘自 awscli/examples/application-signals/update-service-level-objective.rst）：

aws application-signals update-service-level-objective \ --cli-input-json file://update-slo.json

其中update-slo.json的内容为：

{ "id": "arn:aws:application-signals:us-east-1:123456789101:slo/SLOName", "goal": { "Interval": { "RollingInterval": { "DurationUnit": "DAY", "Duration": 7 } }, "AttainmentGoal": 90.0, "WarningThreshold": 50.0 } }

要点说明：

• --cli-input-json是 AWS CLI 为所有操作通用注入的参数，它接受一个 JSON 字符串作为整个命令的输入，格式与--generate-cli-skeleton生成的骨架一致。当命令行同时显式传入了其他参数时，命令行参数会覆盖 JSON 中的同名值。其实现见 cliinputjson.py。
• file://前缀表示从本地文件读取参数值，而不是把 JSON 直接写在命令行里。前缀到本地/远程存储的映射由 paramfile.py 中的LOCAL_PREFIX_MAP与get_paramfile完成，file://即读取当前文件系统上的update-slo.json。
• 这个 JSON 只包含两个字段：id（标识要更新的 SLO，支持 ARN 或 SLO 名称）和goal（SLO 目标结构）。之所以这样写，是因为该操作遵循“省略即保留”语义——不传的参数会保持原值，因此这里只需要提交真正要变更的部分。

输入字段详解与 API 模型依据

从源码结构看，该操作的完整输入结构定义在 service-2.json 的UpdateServiceLevelObjectiveInput形状中，可更新字段共 6 个：

Goal结构在示例 JSON 中体现为三要素：

• Interval.RollingInterval：滚动评估窗口，由DurationUnit（时间单位，示例为DAY）与Duration（时长数值，示例为 7 天）组成。模型中Window形状对DurationUnit与Duration均标记为 required（见 service-2.json），因此这两项必须同时提供。
• AttainmentGoal：目标达成率（double 类型），示例为90.0。
• WarningThreshold：警告阈值（double 类型），示例为50.0，达成率低于该值时触发警告级别。

两条关键约束同样来自服务模型的 API 文档注释（service-2.json）：

1. 部分更新：“If you omit parameters, the previous values of those parameters are retained.” 即未提交字段沿用旧值，这正是示例只用id+goal即可更新目标的原因。
2. 评估类型不可切换：“You cannot change from a period-based SLO to a request-based SLO, or change from a request-based SLO to a period-based SLO.” 换言之，SliConfig与RequestBasedSliConfig二选一且不可互转。

底层请求语义与错误处理

操作定义中，UpdateServiceLevelObjective使用 HTTPPATCH方法请求/slo/{Id}端点，成功响应码为 200（service-2.json）。PATCH + 部分字段的组合与“省略即保留”的文档描述一致，属于典型的局部更新语义。

该操作声明了三个错误形状：

• ValidationException：HTTP 400，客户端错误，表示输入不合法（如DurationUnit/Duration缺失或类型错误）；
• ResourceNotFoundException：SLO 的id不存在；
• ThrottlingException：请求被限流。

因此在脚本化调用时，可以针对 400/404 做参数修正重试，而将 429/限流类错误交给 CLI 内置的重试策略处理。

输出结构：确认更新后的 SLO 全貌

命令执行成功后返回UpdateServiceLevelObjectiveOutput，其中包含必填的Slo成员——即“刚更新的 SLO 的完整信息”（service-2.json）。官方示例输出的 JSON 结构如下（关键字段均有注释）：

{ "Slo": { "Arn": "arn:aws:application-signals:us-east-1:123456789101:slo/SLOName", "Name": "SLOName", "Description": "Description of your SLO", "CreatedTime": "2024-12-24T22:19:18.624000+05:30", "LastUpdatedTime": "2024-12-27T08:51:38.278000+05:30", "Sli": { "SliMetric": { "MetricDataQueries": [{ "Id": "m1", "MetricStat": { "Metric": { "Namespace": "AWS/EC2", "MetricName": "CPUUtilization", "Dimensions": [{ "Name": "InstanceId", "Value": "i-00987654345222" }] }, "Period": 60, "Stat": "Average" }, "ReturnData": true }] }, "MetricThreshold": 200.0, "ComparisonOperator": "LessThanOrEqualTo" }, "EvaluationType": "PeriodBased", "Goal": { "Interval": { "RollingInterval": { "DurationUnit": "DAY", "Duration": 7 } }, "AttainmentGoal": 90.0, "WarningThreshold": 50.0 } } }

输出中可以重点核对的字段：

• Goal应与提交文件中修改后的值一致（示例中AttainmentGoal从创建时的 99.0 更新为 90.0）；
• LastUpdatedTime应刷新为本次更新时间；
• Sli与EvaluationType（示例为PeriodBased）保持不变，印证了本次调用只触碰了目标字段。

与 SLO 生命周期命令的衔接

update-service-level-objective是 SLO 生命周期中的一环。同目录下的 awscli/examples/application-signals/ 提供了配套示例，可组成完整的操作闭环：

• 创建：create-service-level-objective.rst 演示用--name、--description、--sli-config file://sli-config.json创建 SLO，并展示默认Goal（7 天滚动窗口、AttainmentGoal99.0、WarningThreshold50.0）；
• 查询：get-service-level-objective.rst 演示用--id按 ARN 查询单个 SLO，适合在更新后做回读校验；
• 列表：list-service-level-objectives.rst 用于先找到待更新 SLO 的 ARN；
• 预算报告：batch-get-service-level-objective-budget-report.rst 演示按时间戳批量获取 SLO 预算报告，输出中的BudgetStatus（OK/BREACHED）、Attainment、TotalBudgetSeconds、BudgetSecondsRemaining等字段可以直接反映AttainmentGoal调整后的预算余量变化；
• 删除：delete-service-level-objective.rst 演示按 ARN 删除 SLO，该命令无输出。

一个实用的工作流是：list-service-level-objectives找到 ARN → 准备只含变更字段的 JSON →update-service-level-objective --cli-input-json file://update-slo.json→get-service-level-objective回读确认。对于复杂输入，可先用aws application-signals update-service-level-objective --generate-cli-skeleton input生成输入骨架再手动填充，骨架格式即--cli-input-json所期望的格式。

适用前提与注意事项

• 操作对象必须是一个已存在的 SLO，id使用其 ARN 或名称；示例中us-east-1区域、账号123456789101为文档占位值，使用时应替换为真实资源。
• 调用者需要具备对该操作（application-signals:UpdateServiceLevelObjective资源级动作）的 IAM 权限，否则会遇到访问拒绝类错误（模型中定义了 403 的AccessDeniedException形状）。
• 仓库中该服务的模型版本目录为 awscli/botocore/data/application-signals/2024-04-15/，即本文字段与约束均基于 2024-04-15 版 API 模型；如服务后续新增字段，以当前安装的 aws-cli 版本内嵌模型为准。
• 由于评估类型（period-based 与 request-based）不可互相切换，修改 SLI 指标时应始终使用与现有 SLO 同一类型的配置结构（sli-config或 request-based 对应结构），避免触发ValidationException。

综上，update-service-level-objective通过--cli-input-json file://...提交最小化 JSON 即可完成 SLO 目标的局部更新；理解“省略即保留”的部分更新语义、Goal中滚动窗口与阈值字段的必填关系，以及PATCH /slo/{Id}的底层请求模型，能帮助你把该命令安全地用于日常 SLO 调参与自动化脚本中。

【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli