Amazon API Gateway v2 阶段管理实战使用 AWS CLI 的 create-stage 命令创建 API Stage【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli导读本指南以 AWS CLI 官方示例文档 create-stage.rst 为核心系统讲解aws apigatewayv2 create-stage命令的完整用法从最小可用命令出发到访问日志、路由限流、阶段变量、标签与自动部署等生产级配置并结合仓库内 API Gateway v2 服务模型service-2.json逐字段解析参数语义与输出结构。读完本指南你将能够通过命令行为 HTTP API 与 WebSocket API 创建、验证并管理阶段Stage掌握阶段与部署Deployment、路由设置Route Settings之间的联动关系。Stage 是什么为什么需要为 API 创建阶段在 Amazon API Gateway 中**Stage阶段**是 API 的一个具名运行环境快照用来表示 API 的部署生命周期状态。最常见的使用方式是用dev、test、prod等名称区分不同环境同一份 API 定义可以同时以多个阶段对外提供服务各阶段拥有独立的访问日志、限流策略和阶段变量。create-stage命令执行的操作在服务端对应一次POST /v2/apis/{apiId}/stages请求协议为 rest-json签名方式为 SigV4成功创建后返回 HTTP 201 状态码。也就是说阶段隶属于某个已存在的 API——你首先需要一个apiId它可以通过aws apigatewayv2 create-api或get-apis获得。从源码结构看apigatewayv2服务模型位于 awscli/botocore/data/apigatewayv2/2018-11-29/其中service-2.json定义了全部操作与数据形状AWS CLI 直接依据该模型自动生成create-stage等命令的参数解析、校验与序列化逻辑因此命令行为与模型定义一一对应。创建阶段的最小可用命令根据官方示例文档 create-stage.rst创建一个名为dev的阶段只需要两个参数API 标识符与阶段名。aws apigatewayv2 create-stage \ --api-id a1b2c3d4 \ --stage-name dev命令执行成功后返回的 JSON 输出如下{ CreatedDate: 2020-04-06T23:23:46Z, DefaultRouteSettings: { DetailedMetricsEnabled: false }, LastUpdatedDate: 2020-04-06T23:23:46Z, RouteSettings: {}, StageName: dev, StageVariables: {}, Tags: {} }对输出做几点解读CreatedDate/LastUpdatedDate阶段的创建与最后更新时间ISO 8601 格式时间戳。刚创建完成时两者相同。DefaultRouteSettings默认路由设置此处显示DetailedMetricsEnabled为false表示默认未开启详细指标。RouteSettings按路由键routeKey细分的设置集合初始为空。StageVariables阶段变量映射初始为空。Tags资源标签初始为空。对照服务模型的CreateStageRequest形状可以看出ApiId与StageName是仅有的两个必填字段这也解释了为何上述命令能够以最小参数成功执行。ApiId在 HTTP 请求中位于 URI 路径location: uriStageName位于请求体。create-stage 全部参数详解依据 service-2.json 中CreateStageRequest的定义create-stage支持的完整参数如下CLI 参数类型必填说明--api-idstring✅API 标识符位于请求 URI 路径--stage-namestring✅阶段名称长度 1–128 个字符--deployment-idstring否该阶段关联的部署标识符--descriptionstring否阶段描述长度 0–1024 个字符--auto-deployboolean否对 API 的更新是否自动触发新部署默认值为false--default-route-settingsstructure否阶段的默认路由设置--route-settingsmap否按 routeKey 区分的路由设置--stage-variablesmap否阶段变量映射--access-log-settingsstructure否阶段访问日志设置--client-certificate-idstring否客户端证书标识仅 WebSocket API 支持--tagsmap否资源标签集合路由设置RouteSettings--default-route-settings与--route-settings都使用RouteSettings结构两者的区别在于作用范围前者作用于阶段内所有未单独配置的路由后者按 routeKey 精确覆盖到具体路由。该结构包含以下字段字段类型说明DetailedMetricsEnabledboolean是否开启详细指标ThrottlingBurstLimitinteger突发burst限流阈值ThrottlingRateLimitdouble每秒速率限流阈值LoggingLevelenum日志级别ERROR、INFO或OFF仅 WebSocket API 支持DataTraceEnabledboolean是否开启数据追踪日志仅 WebSocket API 支持注意LoggingLevel与DataTraceEnabled只对 WebSocket API 生效它们影响推送到 Amazon CloudWatch Logs 的日志条目ThrottlingBurstLimit与ThrottlingRateLimit则对 HTTP API 与 WebSocket API 均适用。访问日志设置AccessLogSettings--access-log-settings用于为阶段配置访问日志包含两个字段DestinationArn接收访问日志的 CloudWatch Logs 日志组 ARN。Format访问日志的单行输出格式由$context变量拼写而成格式串必须至少包含$context.requestId。在创建阶段时若不传入该参数则阶段默认不记录访问日志如需禁用某阶段已有的访问日志可参考 delete-access-log-settings.rst 中的说明——直接删除访问日志设置即可aws apigatewayv2 delete-access-log-settings \ --api-id a1b2c3d4 \ --stage-name $default阶段变量与标签--stage-variables阶段变量映射。变量名允许字母数字与下划线变量值必须匹配正则[A-Za-z0-9-._~:/?#,]且长度不超过 2048 个字符。阶段变量可以在 Lambda 集成等场景中向后端传递环境相关的配置。--tags资源标签集合每个标签值为长度 1–1600 的字符串用于成本分配与资源管理。进阶实战一次创建带完整配置的生产级阶段下面组合多个参数创建一个名为prod的阶段绑定已有部署、开启详细指标、写入阶段变量、打上标签并配置访问日志aws apigatewayv2 create-stage \ --api-id a1b2c3d4 \ --stage-name prod \ --deployment-id x1zwyv \ --auto-deploy \ --description Production stage \ --default-route-settings {DetailedMetricsEnabled:true,ThrottlingBurstLimit:1000,ThrottlingRateLimit:10000.0} \ --stage-variables {function:my-prod-function} \ --tags {Environment:prod,Team:platform} \ --access-log-settings {DestinationArn:arn:aws:logs:us-west-2:123456789012:log-group:my-api-access-logs,Format:$context.requestId $context.identity.sourceIp $context.requestTime}各参数说明--deployment-id将阶段关联到指定部署。若开启--auto-deploy后续对 API 定义的更新会自动生成并发布新部署此时无需手动指定部署标识。--auto-deploy结合 create-api.rst 中 quick create 的说明使用快速创建生成的 API 会自带一个$default阶段并默认开启自动部署而自行创建的阶段默认autoDeploy为false。--access-log-settings日志格式必须包含$context.requestId否则服务端会返回参数校验错误。验证阶段创建结果创建完成后可以通过get-stage命令查验阶段的实际配置。官方示例 get-stage.rst 演示了查询prod阶段aws apigatewayv2 get-stage \ --api-id a1b2c3d4 \ --stage-name prod输出示例{ CreatedDate: 2020-04-08T00:36:05Z, DefaultRouteSettings: { DetailedMetricsEnabled: false }, DeploymentId: x1zwyv, LastUpdatedDate: 2020-04-08T00:36:13Z, RouteSettings: {}, StageName: prod, StageVariables: { function: my-prod-function }, Tags: {} }可以看到get-stage返回的字段结构与create-stage的响应一致。此外CreateStageResponse还包含两个值得关注的字段ApiGatewayManaged阶段是否由 API Gateway 托管。使用 quick create 创建的 API 其$default阶段由 API Gateway 托管此类阶段不可修改。LastDeploymentStatusMessage描述最近一次部署的状态消息仅对开启autoDeploy的阶段有效可用来判断自动部署是否成功。按路由配置自定义限流用 update-stage 动态调整阶段创建后路由级限流设置可通过update-stage动态调整。官方示例 update-stage.rst 演示了为dev阶段的GET /pets路由配置自定义限流aws apigatewayv2 update-stage \ --api-id a1b2c3d4 \ --stage-name dev \ --route-settings {GET /pets:{ThrottlingBurstLimit:100,ThrottlingRateLimit:2000}}输出示例{ 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: {} }这个例子揭示了RouteSettingsMap的数据结构它是一个以 routeKey如GET /pets为键、RouteSettings为值的映射与create-stage中--route-settings的 JSON 写法完全一致。业务上通常将高价值路由的限流阈值调高、将弱依赖或代价高的路由调低从而实现精细化流量治理。错误处理与排错对照服务模型中CreateStage操作声明的错误列表创建阶段可能遇到四类异常错误含义常见原因与处理NotFoundException资源不存在--api-id对应的 API 不存在或不属于当前账号/区域检查 API 标识符ConflictException资源已存在同名阶段已存在阶段名在单个 API 内必须唯一改用其他名称或先删除旧阶段BadRequestException请求参数无效参数类型错误、阶段名超长1–128、阶段变量值不匹配正则等对照参数表检查TooManyRequestsException请求过于频繁超过 API 调用速率限制采用指数退避策略重试另外需要注意托管阶段ApiGatewayManaged为 true如 quick create 生成的$default阶段无法修改对这类阶段执行update-stage会失败若需独立管理应自行创建 API 或使用自定义阶段名。端到端工作流从 API 到阶段将仓库中多个示例串起来可以形成一条完整的发布链路创建 API用 create-api.rst 创建 HTTP API如my-http-api从输出中取得ApiId。创建部署用aws apigatewayv2 create-deployment --api-id api-id生成部署并记录DeploymentId。创建阶段用本文的create-stage将部署绑定到dev/prod等阶段名配置路由限流、访问日志与阶段变量。验证与调整用get-stage核对配置用update-stage按需调整限流用delete-access-log-settings关闭访问日志。借助这一流程团队可以在不触碰生产流量的前提下用命令行脚本化地完成多环境 API 发布而这正是 AWS CLI 管理 API Gateway v2 的核心价值所在。总结aws apigatewayv2 create-stage是管理 HTTP API 与 WebSocket API 运行环境的核心入口。本文从官方示例的最小命令出发结合仓库内 service-2.json 中的CreateStageRequest模型逐字段拆解了全部参数——包括必填的api-id与stage-name以及路由限流、访问日志、阶段变量、标签、自动部署等生产级配置同时通过 get-stage.rst 与 update-stage.rst 展示了阶段的查询与动态调优方法。文中所有命令均可直接复制运行只需将a1b2c3d4等占位符替换为你实际环境中的 API 标识符与资源名称。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/14 12:45:15 · 阅读 1.2k Amazon API Gateway v2 阶段管理实战：使用 AWS CLI 的 create-stage 命令创建 API Stage
Amazon API Gateway v2 阶段管理实战使用 AWS CLI 的 create-stage 命令创建 API Stage【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli导读本指南以 AWS CLI 官方示例文档 create-stage.rst 为核心系统讲解aws apigatewayv2 create-stage命令的完整用法从最小可用命令出发到访问日志、路由限流、阶段变量、标签与自动部署等生产级配置并结合仓库内 API Gateway v2 服务模型service-2.json逐字段解析参数语义与输出结构。读完本指南你将能够通过命令行为 HTTP API 与 WebSocket API 创建、验证并管理阶段Stage掌握阶段与部署Deployment、路由设置Route Settings之间的联动关系。Stage 是什么为什么需要为 API 创建阶段在 Amazon API Gateway 中**Stage阶段**是 API 的一个具名运行环境快照用来表示 API 的部署生命周期状态。最常见的使用方式是用dev、test、prod等名称区分不同环境同一份 API 定义可以同时以多个阶段对外提供服务各阶段拥有独立的访问日志、限流策略和阶段变量。create-stage命令执行的操作在服务端对应一次POST /v2/apis/{apiId}/stages请求协议为 rest-json签名方式为 SigV4成功创建后返回 HTTP 201 状态码。也就是说阶段隶属于某个已存在的 API——你首先需要一个apiId它可以通过aws apigatewayv2 create-api或get-apis获得。从源码结构看apigatewayv2服务模型位于 awscli/botocore/data/apigatewayv2/2018-11-29/其中service-2.json定义了全部操作与数据形状AWS CLI 直接依据该模型自动生成create-stage等命令的参数解析、校验与序列化逻辑因此命令行为与模型定义一一对应。创建阶段的最小可用命令根据官方示例文档 create-stage.rst创建一个名为dev的阶段只需要两个参数API 标识符与阶段名。aws apigatewayv2 create-stage \ --api-id a1b2c3d4 \ --stage-name dev命令执行成功后返回的 JSON 输出如下{ CreatedDate: 2020-04-06T23:23:46Z, DefaultRouteSettings: { DetailedMetricsEnabled: false }, LastUpdatedDate: 2020-04-06T23:23:46Z, RouteSettings: {}, StageName: dev, StageVariables: {}, Tags: {} }对输出做几点解读CreatedDate/LastUpdatedDate阶段的创建与最后更新时间ISO 8601 格式时间戳。刚创建完成时两者相同。DefaultRouteSettings默认路由设置此处显示DetailedMetricsEnabled为false表示默认未开启详细指标。RouteSettings按路由键routeKey细分的设置集合初始为空。StageVariables阶段变量映射初始为空。Tags资源标签初始为空。对照服务模型的CreateStageRequest形状可以看出ApiId与StageName是仅有的两个必填字段这也解释了为何上述命令能够以最小参数成功执行。ApiId在 HTTP 请求中位于 URI 路径location: uriStageName位于请求体。create-stage 全部参数详解依据 service-2.json 中CreateStageRequest的定义create-stage支持的完整参数如下CLI 参数类型必填说明--api-idstring✅API 标识符位于请求 URI 路径--stage-namestring✅阶段名称长度 1–128 个字符--deployment-idstring否该阶段关联的部署标识符--descriptionstring否阶段描述长度 0–1024 个字符--auto-deployboolean否对 API 的更新是否自动触发新部署默认值为false--default-route-settingsstructure否阶段的默认路由设置--route-settingsmap否按 routeKey 区分的路由设置--stage-variablesmap否阶段变量映射--access-log-settingsstructure否阶段访问日志设置--client-certificate-idstring否客户端证书标识仅 WebSocket API 支持--tagsmap否资源标签集合路由设置RouteSettings--default-route-settings与--route-settings都使用RouteSettings结构两者的区别在于作用范围前者作用于阶段内所有未单独配置的路由后者按 routeKey 精确覆盖到具体路由。该结构包含以下字段字段类型说明DetailedMetricsEnabledboolean是否开启详细指标ThrottlingBurstLimitinteger突发burst限流阈值ThrottlingRateLimitdouble每秒速率限流阈值LoggingLevelenum日志级别ERROR、INFO或OFF仅 WebSocket API 支持DataTraceEnabledboolean是否开启数据追踪日志仅 WebSocket API 支持注意LoggingLevel与DataTraceEnabled只对 WebSocket API 生效它们影响推送到 Amazon CloudWatch Logs 的日志条目ThrottlingBurstLimit与ThrottlingRateLimit则对 HTTP API 与 WebSocket API 均适用。访问日志设置AccessLogSettings--access-log-settings用于为阶段配置访问日志包含两个字段DestinationArn接收访问日志的 CloudWatch Logs 日志组 ARN。Format访问日志的单行输出格式由$context变量拼写而成格式串必须至少包含$context.requestId。在创建阶段时若不传入该参数则阶段默认不记录访问日志如需禁用某阶段已有的访问日志可参考 delete-access-log-settings.rst 中的说明——直接删除访问日志设置即可aws apigatewayv2 delete-access-log-settings \ --api-id a1b2c3d4 \ --stage-name $default阶段变量与标签--stage-variables阶段变量映射。变量名允许字母数字与下划线变量值必须匹配正则[A-Za-z0-9-._~:/?#,]且长度不超过 2048 个字符。阶段变量可以在 Lambda 集成等场景中向后端传递环境相关的配置。--tags资源标签集合每个标签值为长度 1–1600 的字符串用于成本分配与资源管理。进阶实战一次创建带完整配置的生产级阶段下面组合多个参数创建一个名为prod的阶段绑定已有部署、开启详细指标、写入阶段变量、打上标签并配置访问日志aws apigatewayv2 create-stage \ --api-id a1b2c3d4 \ --stage-name prod \ --deployment-id x1zwyv \ --auto-deploy \ --description Production stage \ --default-route-settings {DetailedMetricsEnabled:true,ThrottlingBurstLimit:1000,ThrottlingRateLimit:10000.0} \ --stage-variables {function:my-prod-function} \ --tags {Environment:prod,Team:platform} \ --access-log-settings {DestinationArn:arn:aws:logs:us-west-2:123456789012:log-group:my-api-access-logs,Format:$context.requestId $context.identity.sourceIp $context.requestTime}各参数说明--deployment-id将阶段关联到指定部署。若开启--auto-deploy后续对 API 定义的更新会自动生成并发布新部署此时无需手动指定部署标识。--auto-deploy结合 create-api.rst 中 quick create 的说明使用快速创建生成的 API 会自带一个$default阶段并默认开启自动部署而自行创建的阶段默认autoDeploy为false。--access-log-settings日志格式必须包含$context.requestId否则服务端会返回参数校验错误。验证阶段创建结果创建完成后可以通过get-stage命令查验阶段的实际配置。官方示例 get-stage.rst 演示了查询prod阶段aws apigatewayv2 get-stage \ --api-id a1b2c3d4 \ --stage-name prod输出示例{ CreatedDate: 2020-04-08T00:36:05Z, DefaultRouteSettings: { DetailedMetricsEnabled: false }, DeploymentId: x1zwyv, LastUpdatedDate: 2020-04-08T00:36:13Z, RouteSettings: {}, StageName: prod, StageVariables: { function: my-prod-function }, Tags: {} }可以看到get-stage返回的字段结构与create-stage的响应一致。此外CreateStageResponse还包含两个值得关注的字段ApiGatewayManaged阶段是否由 API Gateway 托管。使用 quick create 创建的 API 其$default阶段由 API Gateway 托管此类阶段不可修改。LastDeploymentStatusMessage描述最近一次部署的状态消息仅对开启autoDeploy的阶段有效可用来判断自动部署是否成功。按路由配置自定义限流用 update-stage 动态调整阶段创建后路由级限流设置可通过update-stage动态调整。官方示例 update-stage.rst 演示了为dev阶段的GET /pets路由配置自定义限流aws apigatewayv2 update-stage \ --api-id a1b2c3d4 \ --stage-name dev \ --route-settings {GET /pets:{ThrottlingBurstLimit:100,ThrottlingRateLimit:2000}}输出示例{ 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: {} }这个例子揭示了RouteSettingsMap的数据结构它是一个以 routeKey如GET /pets为键、RouteSettings为值的映射与create-stage中--route-settings的 JSON 写法完全一致。业务上通常将高价值路由的限流阈值调高、将弱依赖或代价高的路由调低从而实现精细化流量治理。错误处理与排错对照服务模型中CreateStage操作声明的错误列表创建阶段可能遇到四类异常错误含义常见原因与处理NotFoundException资源不存在--api-id对应的 API 不存在或不属于当前账号/区域检查 API 标识符ConflictException资源已存在同名阶段已存在阶段名在单个 API 内必须唯一改用其他名称或先删除旧阶段BadRequestException请求参数无效参数类型错误、阶段名超长1–128、阶段变量值不匹配正则等对照参数表检查TooManyRequestsException请求过于频繁超过 API 调用速率限制采用指数退避策略重试另外需要注意托管阶段ApiGatewayManaged为 true如 quick create 生成的$default阶段无法修改对这类阶段执行update-stage会失败若需独立管理应自行创建 API 或使用自定义阶段名。端到端工作流从 API 到阶段将仓库中多个示例串起来可以形成一条完整的发布链路创建 API用 create-api.rst 创建 HTTP API如my-http-api从输出中取得ApiId。创建部署用aws apigatewayv2 create-deployment --api-id api-id生成部署并记录DeploymentId。创建阶段用本文的create-stage将部署绑定到dev/prod等阶段名配置路由限流、访问日志与阶段变量。验证与调整用get-stage核对配置用update-stage按需调整限流用delete-access-log-settings关闭访问日志。借助这一流程团队可以在不触碰生产流量的前提下用命令行脚本化地完成多环境 API 发布而这正是 AWS CLI 管理 API Gateway v2 的核心价值所在。总结aws apigatewayv2 create-stage是管理 HTTP API 与 WebSocket API 运行环境的核心入口。本文从官方示例的最小命令出发结合仓库内 service-2.json 中的CreateStageRequest模型逐字段拆解了全部参数——包括必填的api-id与stage-name以及路由限流、访问日志、阶段变量、标签、自动部署等生产级配置同时通过 get-stage.rst 与 update-stage.rst 展示了阶段的查询与动态调优方法。文中所有命令均可直接复制运行只需将a1b2c3d4等占位符替换为你实际环境中的 API 标识符与资源名称。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考