使用 AWS CLI 查询 API Gateway Stage：get-stage 命令完整实战与字段深度解析

使用 AWS CLI 查询 API Gateway Stage：get-stage 命令完整实战与字段深度解析

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

本指南以 AWS CLI 官方示例文档 awscli/examples/apigateway/get-stage.rst 为骨架，围绕aws apigateway get-stage命令展开：先给出可直接复制的命令与完整输出，再基于仓库内的 API 模型 service-2.json 逐项解读返回的Stage对象与methodSettings字段，最后串联创建、查看、更新、删除 Stage 的完整生命周期操作。读完本文，你将掌握用 AWS CLI 查询任意 API 的某个 Stage 配置、理解每一行返回值的业务含义，并能熟练使用update-stage做方法级配置调整。

Stage 是什么：REST API 的版本化部署入口

在 API Gateway 的模型中，一个 REST API（RestApi）可以包含多个部署（Deployment），而Stage（阶段）是将某个 Deployment 发布为可被外部调用入口的逻辑概念。Stage 名称会成为调用 URL 中的第一段路径，例如https://api-id.execute-api.region.amazonaws.com/dev中的dev。

从仓库的 API 模型 service-2.json 中可以看到Stage对象的官方定义：它"表示一个已部署 RestApi 版本的唯一标识，可供用户调用"，是 API 从开发到生产的发布单元。典型用法是同一个 REST API 下维护dev、test、prod等多个 Stage，分别指向不同 Deployment，从而实现环境隔离与灰度发布。

与 Stage 相关的操作在模型中都定义在同一资源路径上：

其中get-stage对应GetStage操作，返回类型为Stage；该操作在模型中标记restApiId与stageName两个必填参数，且都以 URI 路径参数（location: uri）方式传递。

get-stage 命令实操

查询某个 API 的指定 Stage，命令极简，只需两个必填参数：

aws apigateway get-stage --rest-api-id 1234123412 --stage-name dev

• --rest-api-id：REST API 的字符串标识符，即创建 API 后分配的那个 ID（示例中的1234123412为占位符，实际使用时替换为你自己的 API ID）。
• --stage-name：要查询的 Stage 名称，必须与创建时一致。

该命令对应的服务端操作是GET /restapis/{restapi_id}/stages/{stage_name}，返回整个 Stage 的完整配置对象。

完整输出逐字段解读

执行上面的命令，AWS CLI 会返回类似如下的 JSON（取自 get-stage.rst 的官方示例输出）：

{ "stageName": "dev", "cacheClusterSize": "0.5", "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": "rbh1fj", "lastUpdatedDate": 1466802961, "createdDate": 1460682074, "methodSettings": { "*/*": { "cacheTtlInSeconds": 300, "loggingLevel": "INFO", "dataTraceEnabled": false, "metricsEnabled": true, "unauthorizedCacheControlHeaderStrategy": "SUCCEED_WITH_RESPONSE_HEADER", "throttlingRateLimit": 500.0, "cacheDataEncrypted": false, "cachingEnabled": false, "throttlingBurstLimit": 1000, "requireAuthorizationForCacheControl": true }, "~1resource/GET": { "cacheTtlInSeconds": 300, "loggingLevel": "INFO", "dataTraceEnabled": false, "metricsEnabled": true, "unauthorizedCacheControlHeaderStrategy": "SUCCEED_WITH_RESPONSE_HEADER", "throttlingRateLimit": 500.0, "cacheDataEncrypted": false, "cachingEnabled": false, "throttlingBurstLimit": 1000, "requireAuthorizationForCacheControl": true } } }

对照模型文件中的Stageshape，返回对象的每个成员含义如下：

时间戳说明

示例输出中createdDate: 1460682074、lastUpdatedDate: 1466802961是 Unix 秒级时间戳（分别对应 2016-04-15 与 2016-06-24 左右）。这是早期 API Gateway 返回的格式；较新版本（如 update-stage.rst 示例所示）会返回 ISO 8601 字符串（如"2022-07-18T10:11:18-07:00"）。写脚本解析时建议对两种格式做兼容处理。

methodSettings：方法级配置的解析重点

methodSettings是get-stage输出中最值得深入理解的部分，它以Map形式返回该 Stage 上每个 HTTP 方法的具体行为配置。模型文档明确指出，Map 的键有两种形式：

• {resource_path}/{http_method}：针对单个方法的覆盖配置，例如~1resource/GET；
• */*：针对 Stage 下所有方法的默认配置。

示例输出中恰好同时出现了这两种键：*/*是全局默认设置，~1resource/GET则是对名为resource的子资源的GET方法的单独覆盖。

键中的~1是什么

~1是 JSON Pointer 转义语法：在 JSON Pointer 中/需要转义为~1。因此输出里~1resource/GET实际表示路径/resource/GET。同理，在 get-stages.rst 的输出中可以看到~1resource~1subresource/POST，它代表/resource/subresource路径上的POST方法。使用update-stage构造 patch 路径时同样遵循这一转义规则（下文示例中的path=/~1resourceName/GET/logging/dataTrace即对应/resourceName/GET）。

MethodSetting 字段详解

结合 service-2.json 中MethodSettingshape 的定义，每个方法设置包含以下字段：

在示例输出中，*/*与~1resource/GET两组配置几乎一致（cachingEnabled均为false、throttlingRateLimit均为500.0、throttlingBurstLimit均为1000、cacheTtlInSeconds为300、loggingLevel为INFO、metricsEnabled为true），说明该 API 的resource的GET方法沿用了全局默认配置，未做单独覆盖。

从查询到管理：Stage 生命周期实战串联

get-stage只是读取操作，配合其他命令才能完整管理 Stage。以下示例均来自仓库的 awscli/examples/apigateway 目录，可直接组合使用。

1. 创建 Stage（create-stage）

基础创建：为已有 Deployment 建立名为dev的阶段。

aws apigateway create-stage \ --rest-api-id 1234123412 \ --stage-name dev \ --description 'Development stage' \ --deployment-id a1b2c3

创建时指定 Stage 变量（可在集成中通过stageVariables.key引用）：

aws apigateway create-stage \ --rest-api-id 1234123412 \ --stage-name dev \ --description 'Development stage' \ --deployment-id a1b2c3 \ --variables key='value',otherKey='otherValue'

根据模型定义，create-stage的必填参数为restApiId、stageName、deploymentId；还可选传cacheClusterEnabled、cacheClusterSize、canarySettings、tracingEnabled、tags等。Stage 名称命名约束与查询一致：只能含字母数字、连字符、下划线，最长 128 字符。

2. 查看全部 Stage（get-stages）

不带--stage-name列出该 REST API 下所有 Stage：

aws apigateway get-stages --rest-api-id 1234123412

输出为{ "item": [ Stage, ... ] }数组，每个元素结构与get-stage返回的单对象相同，可用于快速盘点各环境的部署状态与缓存配置。模型还支持可选参数--deployment-id，用于过滤属于特定 Deployment 的 Stage。

3. 更新 Stage（update-stage）

update-stage基于 PATCH 语义，通过--patch-operations对配置做定点修改。下面两个官方示例分别演示了方法级与全局级修改。

示例一：关闭单个资源方法的完整请求/响应日志

aws apigateway update-stage \ --rest-api-id 1234123412 \ --stage-name dev \ --patch-operations op=replace,path=/~1resourceName/GET/logging/dataTrace,value=false

注意 patch 路径中的~1转义：/~1resourceName/GET/logging/dataTrace实际指向/resourceName/GET的dataTrace设置。返回结果中methodSettings只包含~1resourceName/GET这一个键，且dataTraceEnabled变为false。

示例二：打开所有方法的数据追踪日志

aws apigateway update-stage \ --rest-api-id 1234123412 \ --stage-name dev \ --patch-operations 'op=replace,path=/*/*/logging/dataTrace,value=true'

此处 patch 路径使用*/*通配符，作用于 Stage 下所有资源的所有方法。返回结果中methodSettings出现"*/*"键，dataTraceEnabled变为true。两种写法与get-stage输出中methodSettings的键格式完全对应，可用于验证更新是否生效。

4. 删除 Stage（delete-stage）

aws apigateway delete-stage --rest-api-id 1234123412 --stage-name dev

模型显示delete-stage（DeleteStage）无返回体，成功后 Stage 即被移除，对应调用 URL 停止服务。删除前建议先用get-stage确认目标 Stage 及关联的 Deployment，避免误删正在提供服务的环境。

源码视角：CLI 参数如何绑定到请求

理解 CLI 命令与底层请求的映射有助于排查参数问题。在 service-2.json 中，GetStageRequestshape 定义了restApiId与stageName两个必填成员，且都带有：

• "location": "uri"：表明二者是URI 路径参数，而非请求体或查询串参数；
• "locationName": "restapi_id"/"locationName": "stage_name"：指定了路径模板中的占位符名称。

结合GetStage操作声明的requestUri: /restapis/{restapi_id}/stages/{stage_name}，可以看到aws apigateway get-stage --rest-api-id 1234123412 --stage-name dev最终构造的请求就是GET /restapis/1234123412/stages/dev。AWS CLI 的 apigateway 命令集由该模型文件驱动：CLI 据此生成参数名、必填校验、参数校验与输出解析，因此文档中的参数语义与模型完全一致，任何--rest-api-id或--stage-name的缺失都会在发送请求前被 CLI 层直接拦截。

如果你希望绕过 CLI 直接观察原始请求，也可以使用等价操作：GetStage、GetStages、CreateStage、UpdateStage、DeleteStage均定义在同一个模型文件中，任意语言 SDK 与aws apigateway命令共用同一套参数与返回结构。

常见问题与使用建议

• 返回cacheClusterStatus: NOT_AVAILABLE是否异常？不一定。示例中cacheClusterEnabled为false，此时状态显示NOT_AVAILABLE属正常；只有cacheClusterEnabled为true时，状态才会走向AVAILABLE。见 get-stages.rst 输出中cacheClusterEnabled: true与cacheClusterStatus: "AVAILABLE"的对应关系。
• */*与具体路径配置并存时以谁为准？*/*是 Stage 级默认值，{resource}/{method}是单个方法覆盖值；查询时两者都会返回，便于对比实际生效配置。修改单个方法后建议重新执行get-stage确认覆盖项。
• 生产环境谨慎开启dataTraceEnabled：模型文档明确提示其可能记录敏感数据，不建议在生产 API 上启用；排查问题时用update-stage临时打开，结束后再关闭。
• 缓存相关字段联动：方法级cachingEnabled依赖 Stage 级cacheClusterEnabled，二者需配合开启；TTL 建议结合业务缓存命中率调整（示例默认 300 秒）。
• 输出格式差异：同一字段在不同时期可能返回 Unix 时间戳或 ISO 8601 字符串，脚本解析时做双格式兼容更稳妥。

掌握get-stage及其配套命令，你就能以"读取-修改-验证"的闭环管理 API Gateway 的每个发布阶段。所有命令与输出均可在仓库的 awscli/examples/apigateway 目录下找到对应官方示例文件，模型细节则以 service-2.json 为权威依据。

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