AWS CLI 实战：apigateway get-deployments 命令详解与部署列表查询

AWS CLI 实战：apigateway get-deployments 命令详解与部署列表查询

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

导读

aws apigateway get-deployments是 AWS CLI 中用于查询 API Gateway REST API 全部部署（Deployment）记录的集合类命令。本文以仓库中的官方示例文档 get-deployments.rst 为骨架，结合 API Gateway 服务模型与 AWS CLI 分页实现源码，完整讲解命令参数、返回结构、分页策略以及与创建/查询/更新/删除部署的联动用法。读完本文，你将能够熟练查询任意 REST API 的部署历史，并能在脚本中用--query、--paginate等高级参数可靠地处理大规模部署列表。

命令概览：为什么需要 get-deployments

在 API Gateway 中，Deployment（部署）是 RestApi 资源在某一时刻的不可变快照。当你在 API 中修改了方法、集成或模型后，必须重新创建 Deployment，并将它关联到一个 Stage 上，这些变更才会对公网调用生效（对应服务模型中的描述："An immutable representation of a RestApi resource that can be called by users using Stages"，见 service-2.json）。

get-deployments的作用就是列出某个 REST API 名下所有历史部署的集合，返回零到多个部署的引用与摘要。它的典型应用场景包括：

• 审计某个 API 发布过多少次、每次发布的时间与描述；
• 在回滚前确认可用的历史部署 ID（配合get-deployment查看详情）；
• 批量巡检多个 API 的发布状态，纳入 CI/CD 流水线。

基本用法：一行命令列出全部部署

官方示例给出了最简洁的调用形式（见 get-deployments.rst）：

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

其中--rest-api-id是 REST API 的字符串标识符（可在aws apigateway get-rest-apis的输出中获取）。命令返回 JSON 如下：

{ "items": [ { "createdDate": 1453797217, "id": "0a2b4c", "description": "Deployed my API for the first time" } ] }

对照 service-2.json 中的Deployments输出模型，返回体是一个集合资源，包含两个字段：

Deployment元素本身则包含id（部署标识符）、description（部署描述）、createdDate（创建时间，Unix 时间戳，单位为秒）以及apiSummary（该部署创建时刻 RestApi 的方法快照摘要）。示例输出中的1453797217正是这样一个 epoch 秒级时间戳，可用date -d @1453797217之类的方式转换为人可读的时间。

参数详解：分页与条数控制

GetDeployments操作在服务模型中被定义为对GET /restapis/{restapi_id}/deployments的 HTTP 调用（见 service-2.json 第 906 行附近）。其请求结构GetDeploymentsRequest定义了三个成员：

因此你可以在脚本中主动控制单页大小：

# 每页最多返回 100 条部署记录 aws apigateway get-deployments --rest-api-id 1234123412 --limit 100

注意--rest-api-id是唯一必填参数；当不指定--limit时，API 侧默认每页返回 25 条，超出部分会通过position游标分页返回。

分页策略：从手写游标到 --paginate

分页是get-deployments最需要掌握的实际技能。仓库中的 paginators-1.json 为GetDeployments声明了标准的分页配置：

"GetDeployments": { "input_token": "position", "output_token": "position", "limit_key": "limit", "result_key": "items" }

这意味着该操作采用 "position 游标 + limit 条数 + items 结果" 的翻页模型：请求时把上次响应里的position作为下一页的--position传入，直到响应中不再出现position字段即表示已遍历完。

手写翻页循环

position="" while :; do if [ -z "$position" ]; then resp=$(aws apigateway get-deployments --rest-api-id 1234123412) else resp=$(aws apigateway get-deployments --rest-api-id 1234123412 --position "$position") fi echo "$resp" | jq -r '.items[].id' position=$(echo "$resp" | jq -r '.position // empty') [ -z "$position" ] && break done

使用内置 --paginate 简化

AWS CLI 在 clidriver.py 的_make_client_call中提供了自动化分页开关：当操作可被分页且命令行指定了--paginate时，会自动把每一次响应中的游标续上并合并为完整结果：

if client.can_paginate(py_operation_name) and parsed_globals.paginate: paginator = client.get_paginator(py_operation_name) response = paginator.paginate(**parameters)

因此一行即可拿到全量部署列表：

aws apigateway get-deployments --rest-api-id 1234123412 --paginate

底层实现上，paginate.py 的build_full_result会逐页消费响应，按result_key（这里是items）把各页元素增量合并进完整结果，从而保证输出里包含全部部署记录而非仅首页。如果你只需要第一页若干条用于快速巡检，则不加--paginate并配合--limit即可，避免无谓的多次请求。

结合查询与输出格式化：只取关心的字段

部署列表往往只用于提取部署 ID 和时间，可以通过--query与--output把输出压缩成易解析的形式：

# 只输出 "id 创建时间" 两列的表格 aws apigateway get-deployments --rest-api-id 1234123412 \ --query "items[].[id, createdDate]" --output table # 只输出部署 ID 列表（便于脚本循环） aws apigateway get-deployments --rest-api-id 1234123412 \ --query "items[].id" --output text

当需要自动化构造请求或保存参数模板时，可以使用 AWS CLI 自带的骨架能力（相关实现见 generatecliskeleton.py 与 cliinputjson.py）：

# 生成该命令的参数 JSON 骨架 aws apigateway get-deployments --generate-cli-skeleton

{ "restApiId": "", "position": "", "limit": 0 }

将骨架保存后填入真实值，再用--cli-input-json传入即可完成同样的查询，适合在编排系统中复用参数模板。

与部署生命周期其他命令联动

get-deployments是部署查询链路中的一环，与仓库中同目录的其他示例文档构成了完整的部署生命周期：

一个典型的回滚排查流程是：先用get-deployments列出历史部署 → 对感兴趣的id执行get-deployment查看快照与描述 → 用update-stage将 Stage 指向目标部署完成回滚。由于 Deployment 是不可变资源，get-deployments返回的id可以稳定地作为后续操作（get-deployment、update-deployment、delete-deployment）的参数来源。

示例：get-deployment.rst 展示的查询单个部署命令为：

aws apigateway get-deployment --rest-api-id 1234123412 --deployment-id ztt4m2

其返回结构比列表项更完整，同样包含description、id、createdDate，可作为对列表结果的补充验证。

错误处理与排查建议

根据 service-2.json 中GetDeployments的errors声明，调用可能遇到以下异常：

小结

aws apigateway get-deployments --rest-api-id <API_ID>以一行命令返回 REST API 的全部部署记录，其参数模型（position/limit）与分页配置（items结果键）在 service-2.json 与 paginators-1.json 中有完整的机器可读定义。实际使用时，单次简单查询直接调用即可；面对大量部署，推荐结合--limit手写游标循环，或直接用--paginate交给 AWS CLI 底层分页器（paginate.py）自动合并全量结果，再配合--query与--output提取所需字段，即可把部署审计与回滚流程稳定地脚本化。

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