aws-cli 中的 apigatewayv2 get-stages 命令：查询 API Gateway HTTP API 阶段列表的完整实践

aws-cli 中的 apigatewayv2 get-stages 命令查询 API Gateway HTTP API 阶段列表的完整实践【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli本文以 aws-cli 官方示例文档awscli/examples/apigatewayv2/get-stages.rst为主体讲解aws apigatewayv2 get-stages命令的用法、完整 JSON 输出结构与响应字段含义并结合 aws-cli 仓库中的 API 服务模型文件awscli/botocore/data/apigatewayv2/2018-11-29/service-2.json与文档注入机制awscli/customizations/addexamples.py从源码层面说明该命令的参数约束、分页机制与错误处理。读完后你将能够在脚本或 CI 中可靠地列出某个 HTTP API 的全部阶段Stage、按环境解读StageVariables与部署信息并正确处理分页与常见错误码。1. 命令用途与基本用法get-stages用于获取指定 APIREST 或 HTTP API下所有阶段Stage的列表。官方示例给出的最简命令如下引自awscli/examples/apigatewayv2/get-stages.rstaws apigatewayv2 get-stages \ --api-id a1b2c3d4其中--api-id目标 API 的标识符API identifier。在仓库内置的 API 模型中该参数在GetStagesRequest结构里被标记为required见awscli/botocore/data/apigatewayv2/2018-11-29/service-2.json#L9004-L9028且location为uri、locationName为apiId——这意味着 CLI 会把它拼接到请求路径/v2/apis/{apiId}/stages中而不是查询串里。也就是说--api-id是调用该命令的必要前提缺少它命令无法发出有效请求。可选的--max-results与--starting-token参数对应模型中的MaxResults和NextToken成员location均为querystring分别映射为查询参数maxResults与nextToken用于对阶段数量较多的 API 进行分页拉取详见第 4 节。该操作在模型中的定义为 HTTPGET /v2/apis/{apiId}/stages成功时返回200见service-2.json#L2047-L2076。2. 完整输出示例与字段解读官方示例给出的返回结果包含三个阶段$default、dev与prod完整结构如下{ Items: [ { ApiGatewayManaged: true, AutoDeploy: true, CreatedDate: 2020-04-08T00:08:44Z, DefaultRouteSettings: { DetailedMetricsEnabled: false }, DeploymentId: dty748, LastDeploymentStatusMessage: Successfully deployed stage with deployment ID dty748, LastUpdatedDate: 2020-04-08T00:09:49Z, RouteSettings: {}, StageName: $default, StageVariables: {}, Tags: {} }, { AutoDeploy: true, CreatedDate: 2020-04-08T00:35:06Z, DefaultRouteSettings: { DetailedMetricsEnabled: false }, LastUpdatedDate: 2020-04-08T00:35:48Z, RouteSettings: {}, StageName: dev, StageVariables: { function: my-dev-function }, Tags: {} }, { 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: {} } ] }2.1 顶层结构GetStagesResponse仅有两个成员Items__listOfStage列表即各阶段对象的集合与NextToken分页游标最后一页时不返回见service-2.json#L9030-L9043。示例输出中没有NextToken说明结果一页内全部返回完毕。2.2 各阶段对象的关键字段以示例中的三个阶段为参照各字段含义如下StageName阶段名。$default是 API 创建时自动生成的默认阶段示例中它带有ApiGatewayManaged: true标记表示该阶段由 API Gateway 托管管理dev、prod则是由用户显式创建的环境阶段。StageVariables阶段变量是理解多环境部署的关键。示例中dev阶段的变量为{function: my-dev-function}prod为{function: my-prod-function}——这是典型的“同一 API、按阶段把$context.stageVariables.function指向不同 Lambda 函数”的路由模式。$default阶段没有任何变量说明它不做此类路由定制。DeploymentId/LastDeploymentStatusMessage记录该阶段当前绑定的部署Deployment及其最近一次部署状态。注意示例中dev阶段没有DeploymentId而prod有x1zwyv——从示例数据看AutoDeploy: true的阶段可能省略该字段阶段由 API Gateway 自动跟随最新部署而无AutoDeploy的prod阶段则显式绑定了特定部署 ID。这一点仅能从示例数据结构推断具体以 API Gateway 官方行为为准。AutoDeploy标记该阶段是否启用自动部署。$default与dev均为true。ApiGatewayManaged标记该阶段是否由 API Gateway 托管$default为true用户通常不应修改托管阶段。CreatedDate/LastUpdatedDate阶段创建与最近更新时间UTCISO 8601 格式。DefaultRouteSettings/RouteSettings默认路由设置与按路由的覆盖设置。示例中DefaultRouteSettings均为{DetailedMetricsEnabled: false}未开启详细指标RouteSettings为空对象即未配置任何路由级覆盖。Tags阶段资源标签示例中均为空。3. 分页MaxResults 与 NextTokenGetStages支持分页。从源码结构看service-2.json#L9004-L9028请求参数中有两个分页成员CLI 参数模型成员位置查询参数名说明--max-resultsMaxResultsquerystringmaxResults本次最多返回的阶段数量--starting-tokenNextTokenquerystringnextToken下一页的起始位置不是集合最后一个元素时有效响应中的NextToken成员service-2.json#L9038-L9042返回下一次调用应使用的游标取完最后一页后该字段不再出现。典型脚本化写法是# 第一页 aws apigatewayv2 get-stages --api-id a1b2c3d4 --max-results 2 # 用上一页输出中的 nextToken 继续取后续页 aws apigatewayv2 get-stages --api-id a1b2c3d4 --starting-token 上一页返回的 nextToken对大多数 API阶段数量通常很少一次调用即可取回全部结果即官方示例未使用分页参数的场景。4. 错误处理模型中GetStages声明了三类错误service-2.json#L2061-L2074NotFoundException请求中指定的资源如--api-id指向不存在的 API找不到TooManyRequestsException客户端单位时间内请求过多触发限流BadRequestException请求中的某个参数无效。脚本化使用时建议对NotFoundException单独捕获并校验 API ID对TooManyRequestsException做退避重试。5. 这个示例是如何进入 aws-cli 帮助文档的该.rst文件并非独立的离线文档而是 aws-cli 帮助系统的一部分。其加载机制实现在awscli/customizations/addexamples.py文档中说明的约定是见该文件模块 docstringawscli/customizations/addexamples.py#L13-L28为某个操作提供示例需在examples/service_name目录下创建与操作同名的 ReST 片段如examples/apigatewayv2/get-stages.rstadd_examples函数awscli/customizations/addexamples.py#L36-L63会根据帮助命令的event_class形如doc-examples.apigatewayv2.get-stages拼出examples/apigatewayv2/get-stages.rst的路径若文件存在就在生成的帮助页中插入 Examples 二级标题、安装配置提示然后逐行写入示例内容。因此在已安装 aws-cli 的环境中执行aws apigatewayv2 get-stages help就会看到本文第 1、2 节中的命令与示例输出。这也解释了为什么awscli/examples/apigatewayv2/目录下有create-stage.rst、get-stage.rst、update-stage.rst、delete-stage.rst等 59 个兄弟示例文件——它们是同一服务的成套官方示例阶段相关的完整生命周期操作创建、查询、更新、删除、路由设置管理都能在同目录找到对应参考。6. 实操建议与适用前提适用前提本机已安装并配置好 aws-cli有可用凭证与目标 API 所在区域的访问权限目标资源为 API Gateway v2HTTP API / WebSocket API。只读操作get-stages是纯 GET 请求不修改任何资源可安全用于审计脚本、CI 检查如核对生产阶段的StageVariables是否符合预期。环境校验模式配合--output json与--query可快速提取关键字段例如--query Items[].{name:StageName,vars:StageVariables}以表格化方式核对各环境的变量绑定。与单阶段查询的分工get-stages返回全部阶段若只需某一个阶段的详情应使用同系列的aws apigatewayv2 get-stage示例见awscli/examples/apigatewayv2/get-stage.rst。如需了解 API Gateway 阶段的工作原理如$default阶段、阶段变量在$context中的使用可参考官方开发者指南中 “Working with stages for HTTP APIs” 一章原文示例文件末尾即给出该指引。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考