AWS CLI apigatewayv2 update-stage 实战为 HTTP API 路由配置自定义限流与 Stage 参数【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli本篇基于 aws-cli 仓库中apigatewayv2服务的官方示例文档awscli/examples/apigatewayv2/update-stage.rst展开讲解如何使用aws apigatewayv2 update-stage命令修改 API Gateway HTTP API 的 Stage阶段重点演示为指定路由配置自定义限流throttling的完整操作。读完本文你可以完整复现示例命令并理解每一段输出字段的含义结合 botocore 服务模型文件掌握update-stage的全部参数、约束与底层 HTTP 调用方式并了解该示例文档是如何被 aws-cli 构建进aws help帮助输出的。一、示例场景为指定路由配置自定义限流原始文档update-stage.rst给出的是一个实际运维中常见的场景默认情况下 API Gateway 会按账户维度对请求进行限流当某条路由例如GET /pets的流量特征与其他路由明显不同时可以为该路由单独设置更高的突发容量burst与速率上限rate limit。命令如下与原文档一致可直接复制执行aws apigatewayv2 update-stage \ --api-id a1b2c3d4 \ --stage-name dev \ --route-settings {GET /pets:{ThrottlingBurstLimit:100,ThrottlingRateLimit:2000}}参数说明--api-id a1b2c3d4目标 API 的标识符URI 路径参数必填--stage-name dev要更新的 Stage 名称URI 路径参数必填。根据服务模型的定义Stage 名称只能包含字母数字、连字符、下划线或为特殊值$default最大长度 128 个字符--route-settingsJSON 格式的路由设置映射key 为路由键routeKey如GET /petsvalue 为该路由的设置对象。本例为该路由设置了突发上限 100、速率上限 2000。执行成功后命令返回更新后的 Stage 资源完整描述原文档给出的真实输出{ CreatedDate: 2020-04-05T16:21:1600:00, DefaultRouteSettings: { DetailedMetricsEnabled: false }, DeploymentId: shktxb, LastUpdatedDate: 2020-04-08T22:23:1700:00, RouteSettings: { GET /pets: { ThrottlingBurstLimit: 100, ThrottlingRateLimit: 2000.0 } }, StageName: dev, StageVariables: {}, Tags: {} }注意输出中的几个细节ThrottlingRateLimit在请求中以整数2000传入在返回 JSON 中表现为浮点2000.0——因为服务模型将该字段定义为 double 类型而ThrottlingBurstLimit是 integer 类型两者返回格式不同RouteSettings按路由键组织与请求中传入的GET /pets一一对应说明限流规则只作用于这条路由DefaultRouteSettings是 Stage 级默认路由设置本例中仅启用了/未启用DetailedMetricsEnabled未在此配置限流未单独配置的其余路由会走默认行为。二、命令的底层实现HTTP 请求与服务模型aws-cli 的每个子命令行为都由内嵌的 botocore 服务模型驱动。update-stage对应的模型定义在 service-2.jsonAPI 版本 2018-11-29协议为 rest-json。从UpdateStage操作定义可以看到CLI 参数最终会翻译为如下 HTTP 请求方法与路径PATCH /v2/apis/{apiId}/stages/{stageName}其中{apiId}、{stageName}分别由--api-id和--stage-name填充两者在模型中标记为required其余可选参数如route-settings序列化后作为 JSON 请求体发送成功时返回 200 与 Stage 资源描述。模型中声明的四个错误类型也值得在排错时留意错误含义NotFoundException请求中指定的资源API 或 Stage不存在BadRequestException请求参数不合法例如--route-settingsJSON 格式错误ConflictException资源已存在产生冲突TooManyRequestsException客户端单位时间内发送请求过多被限流三、update-stage 的全部可更新参数结合服务模型中UpdateStageRequest结构的成员定义update-stage支持更新以下字段必填项为--api-id与--stage-name其余可选参数类型说明--api-idstringURIAPI 标识符必填--stage-namestringURIStage 名称必填仅允许字母数字、连字符、下划线或$default最长 128 字符--route-settingsmaprouteKey → RouteSettings按路由粒度的设置示例文档的主用途--default-route-settingsRouteSettingsStage 的默认路由设置作用于未单独配置的路由--stage-variablesmapstring → string值最长 2048Stage 变量映射变量名仅允许字母数字与下划线值需匹配[A-Za-z0-9-._~:/?#,]--access-log-settingsAccessLogSettings该 Stage 的访问日志设置--auto-deploybooleanAPI 更新是否自动触发新部署默认 false--deployment-idstringStage 关联的部署 ID模型注释明确开启autoDeploy时不可更新--client-certificate-idstring客户端证书标识仅 WebSocket API 支持--descriptionstring0–1024 字符Stage 描述RouteSettings对象即--route-settings中每个路由键对应的值包含五个字段字段类型说明ThrottlingBurstLimitinteger限流突发上限ThrottlingRateLimitdouble限流速率上限DetailedMetricsEnabledboolean是否启用详细指标DataTraceEnabledboolean数据追踪日志仅 WebSocket API 支持LoggingLevelenumERROR/INFO/OFF路由日志级别影响推送至 CloudWatch Logs 的日志条目仅 WebSocket API 支持从模型中RouteSettings各字段的注释可以推断限流两个字段是 HTTP API 与 WebSocket API 通用的核心配置而DataTraceEnabled与LoggingLevel仅对 WebSocket API 生效这解释了示例文档聚焦限流场景的原因。四、该示例文档如何进入 aws-cli 的帮助输出awscli/examples/apigatewayv2/update-stage.rst这类 RST 片段并不是独立的文档页面而是被 CLI 帮助系统动态注入的。在 addexamples.py 中可以看到其工作机制该定制模块向doc-examples.*.*文档事件注册add_examples处理器处理器会读取awscli/examples/service_name/目录下与子命令同名的 RST 文件本例即examples/apigatewayv2/update-stage.rst在生成aws apigatewayv2 update-stage help的帮助页时将示例片段连同一段固定声明示例需遵循 Unix 风格引号规则、在部分 shell 中需要适配等合并进输出。因此执行aws apigatewayv2 update-stage help时To configure custom throttling 这一小节及其命令、输出会直接出现在帮助文档的 Examples 区域这正是本文第一节内容的来源。五、配套操作Stage 生命周期中的相关命令限流配置只是 Stage 管理的一环结合仓库中同目录的其它示例文档可以把update-stage放回完整的 Stage 操作链中创建 Stage——create-stage.rst 展示了最小化创建方式aws apigatewayv2 create-stage \ --api-id a1b2c3d4 \ --stage-name dev新 Stage 的RouteSettings为空对象{}DefaultRouteSettings.DetailedMetricsEnabled为 false——这与update-stage返回结构中该字段的初始状态一致说明限流规则需要在 Stage 创建后另行添加。删除路由设置——delete-route-settings.rst 展示了撤销限流配置的方式aws apigatewayv2 delete-route-settings \ --api-id a1b2c3d4 \ --stage-name dev \ --route-key GET /pets该命令无输出执行成功即表示指定路由的设置已被清除。六、实操要点小结两级路由设置--default-route-settings提供 Stage 级默认值--route-settings按 routeKey 单独覆盖。示例文档的场景单路由提额正属于后者两者可以同时出现在一个update-stage请求中。限流参数类型差异ThrottlingBurstLimit为整数、ThrottlingRateLimit为双精度浮点构造--route-settingsJSON 时保持数值类型即可CLI 无需额外单位换算。$defaultStage 的限制服务模型响应结构中的ApiGatewayManaged字段说明通过 quick create 创建的 API 其$defaultStage 由 API Gateway 托管不可修改操作托管 Stage 时应以get-stage返回的该字段为准。auto-deploy与--deployment-id的互斥关系模型注释指出开启自动部署后deploymentId不可更新配置这两个参数时需确认当前 Stage 的autoDeploy状态。参数约束以模型为准Stage 名称、Stage 变量名的字符集与长度限制名称 ≤128 字符、变量值 ≤2048 字符且需匹配指定字符集均来自 service-2.json 中的形状定义构造 JSON 参数前可对照检查避免触发BadRequestException。以上所有参数定义、字段约束与错误类型均以仓库内awscli/botocore/data/apigatewayv2/2018-11-29/下的服务模型为准示例命令与输出则以 update-stage.rst 原文为准可直接在当前安装的 AWS CLI 环境中复现验证。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考