企业官网建设流程全解析

使用 AWS CLI 创建 API Gateway 用量计划（Usage Plan）：节流与配额配置实战指南

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

导读

本指南围绕 AWS CLI 的apigateway create-usage-plan命令展开，以 awscli/examples/apigateway/create-usage-plan.rst 中"创建带月度重置配额与节流限制的用量计划"为核心场景，结合本仓库的 API 服务模型源码，系统讲解用量计划的name、description、throttle、quota等全部入参、参数取值规则、命令行 shorthand 语法，以及用量计划创建后的配套管理操作。读完本文，你将能够直接用一行 AWS CLI 命令为 API 消费者配置速率限制与配额，并通过 API Key 关联、用量查询与补丁式修改完成全生命周期的用量治理。

什么是 Usage Plan（用量计划）

在 Amazon API Gateway 中，Usage Plan（用量计划）用于向 API 调用方提供**节流（throttle）与配额（quota）**双重要求：

• 节流：控制 API 请求的瞬时速率与突发速率，防止单个消费者打满后端资源；
• 配额：控制指定时间周期（天/周/月）内允许请求的总次数，常用于按套餐、按计费层级限制调用量。

用量计划本身不直接关联 API Key，它通过后续将 API Key 关联进用量计划，从而对使用该 Key 的客户端生效。创建用量计划后，还会得到usagePlanId，后续关联 API Key、查询用量、修改配额/节流都依赖该 ID。

在 AWS CLI 服务模型 中，CreateUsagePlan的底层 HTTP 定义为POST /usageplans，成功返回 HTTP 201 并携带完整的UsagePlan对象（见 service-2.json#L260-L278），其请求入参结构为CreateUsagePlanRequest。

create-usage-plan 命令完整入参

根据CreateUsagePlanRequest结构（见 service-2.json#L3075-L3105），该命令支持以下参数：

注意：模型定义中该结构仅有name为必填，throttle与quota均可选——你可以只创建带名称的用量计划，随后再通过update-usage-plan补配限制，也可以创建时一次性全部指定。

实战：创建带节流与月度配额重置的用量计划

原文档示例（create-usage-plan.rst）给出如下命令：

aws apigateway create-usage-plan --name "New Usage Plan" --description "A new usage plan" --throttle burstLimit=10,rateLimit=5 --quota limit=500,offset=0,period=MONTH

命令解析：

• --name "New Usage Plan"：用量计划名称，必填；
• --description "A new usage plan"：可读性描述；
• --throttle burstLimit=10,rateLimit=5：设置突发上限 10 次/秒、稳定速率 5 次/秒；
• --quota limit=500,offset=0,period=MONTH：每月（MONTH）最多 500 次请求，offset 为 0，即配额在每月月初完整重置。

这正是原文档标题所述场景：一个"配额在每个月初重置"（resets at the beginning of the month）的用量计划。

throttle 参数详解（ThrottleSettings）

ThrottleSettings结构（见 service-2.json#L6897-L6910）包含两个成员：

burstLimit与rateLimit的关系是：突发上限允许短时间（令牌桶的桶深）内的超额流量，而稳定速率决定长期平均吞吐。二者配合使用可同时约束"瞬时峰值"与"平均速率"。由于rateLimit是 Double 类型，CLI 中也可以传小数，例如rateLimit=2.5。

quota 参数详解（QuotaSettings）

QuotaSettings结构（见 service-2.json#L6252-L6269）包含三个成员：

period的类型QuotaPeriodType在模型中显式枚举为["DAY", "WEEK", "MONTH"]（见 service-2.json#L6244-L6251），因此 CLI 中只能传这三个值之一。

offset的作用值得展开：它不是"第几天开始计费"，而是在第一个周期里先扣减一部分额度。例如limit=500, offset=100，则第一个周期实际可用 400 次，从第二个周期起恢复为 500 次；原文档示例中offset=0表示首个周期不做扣减，直接可用满 500 次。结合period=MONTH，即每个月第一天配额重置为 500 次。

进阶：创建时同时关联 API 阶段

CreateUsagePlanRequest还支持apiStages参数，用于在创建用量计划的同时绑定 API 阶段。ApiStage结构（见 service-2.json#L2285-L2299）包含：

CLI shorthand 语法可以写成：

aws apigateway create-usage-plan --name "Plan with Stage" \ --api-stages apiId=abc123,stage=prod \ --throttle burstLimit=10,rateLimit=5 \ --quota limit=1000,offset=0,period=DAY

这里将prod阶段的 APIabc123直接纳入用量计划。注意--api-stages是复数列表参数，可传入多个阶段（用空格分隔多个apiId=...,stage=...组合）；CLI 会将key=value结构自动解析为ApiStage对象，throttle子对象以嵌套 map 形式提供（如throttle={method=GET,burstLimit=...,rateLimit=...}）。

创建后的完整用量治理链路

创建用量计划拿到usagePlanId后，常用的配套命令同样收录在本仓库的 apigateway 示例目录中：

1. 关联 API Key

用量计划需要与 API Key 关联后才对客户端生效。参考 create-usage-plan-key.rst：

aws apigateway create-usage-plan-key --usage-plan-id a1b2c3 --key-type "API_KEY" --key-id 4vq3yryqm5

底层对应CreateUsagePlanKey，即POST /usageplans/{usageplanId}/keys（见 service-2.json#L279-L297）。

2. 查询用量计划的用量

创建并运行一段时间后，可用get-usage按日期区间拉取实际用量明细（参考 get-usage.rst）：

aws apigateway get-usage --usage-plan-id a1b2c3 --start-date "2016-08-16" --end-date "2016-08-17"

3. 修改配额与节流

用量计划创建后同样支持补丁式修改，参考 update-usage-plan.rst：

# 修改配额周期为 MONTH aws apigateway update-usage-plan --usage-plan-id a1b2c3 --patch-operations op="replace",path="/quota/period",value="MONTH" # 修改配额上限为 500 aws apigateway update-usage-plan --usage-plan-id a1b2c3 --patch-operations op="replace",path="/quota/limit",value="500" # 修改节流稳定速率 aws apigateway update-usage-plan --usage-plan-id a1b2c3 --patch-operations op="replace",path="/throttle/rateLimit",value="10" # 修改节流突发上限 aws apigateway update-usage-plan --usage-plan-id a1b2c3 --patch-operations op="replace",path="/throttle/burstLimit",value="20"

注意 patch 路径的大小写：配额成员是/quota/period、/quota/limit、/quota/offset，节流成员是/throttle/rateLimit、/throttle/burstLimit（rateLimit/burstLimit采用驼峰命名）。

4. 查看与删除

• 列出/查看用量计划：aws apigateway get-usage-plans、aws apigateway get-usage-plan --usage-plan-id <id>；
• 删除用量计划：aws apigateway delete-usage-plan --usage-plan-id <id>（对应DELETE /usageplans/{usageplanId}）。

参数缩写与 shorthand 语法速查

AWS CLI 允许使用参数名缩写，例如--name可缩写为--n，--description缩写为--d。结构体参数统一使用key=value逗号分隔的 shorthand 形式（如burstLimit=10,rateLimit=5），嵌套结构使用花括号包裹的 map 形式（如throttle={method=GET,burstLimit=20,rateLimit=10}），复杂场景也可改用--cli-input-json传入 JSON。当同一参数需要传多个对象时，用空格分隔多个key=value组合（如多个--api-stages条目）。

小结

create-usage-plan是 API Gateway 用量治理的入口命令。通过--throttle控制每秒请求速率与突发能力，通过--quota结合DAY/WEEK/MONTH与offset实现周期配额（含月度重置场景），创建后还能继续关联 API Key、查询用量并补丁式调整限制。本仓库对应的示例与底层模型分别位于 awscli/examples/apigateway/create-usage-plan.rst 与 awscli/botocore/data/apigateway/2015-07-09/service-2.json，可结合阅读以获得完整参考。

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