企业官网建设流程全解析

AWS CLI 中 API Gateway V2 的 get-routes 命令：列出 HTTP/WebSocket API 路由的完整指南

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

导读

本文基于 AWS CLI 仓库中aws apigatewayv2 get-routes的官方示例文档，系统讲解该命令的使用方法、请求/响应参数、分页机制以及底层调用原理。读完后，你可以直接在生产环境中通过 AWS CLI 列出指定 API 的全部路由，理解每条路由的授权类型、API Key 要求和目标集成，并能通过源码级的证据确认该命令在 AWS CLI 中的实际行为。

一、命令基本用法与核心示例

基本命令格式

get-routes用于列出指定 API 的所有路由。其最小可用形式如下：

aws apigatewayv2 get-routes \ --api-id a1b2c3d4

其中--api-id是必填参数，对应目标 API 的标识符。从服务模型定义 service-2.json 可以确认，GetRoutesRequest结构体的required字段仅包含ApiId，即该命令唯一的强制性入参。

典型输出

执行后返回 JSON 结构，Items数组中每个元素代表一条路由：

{ "Items": [ { "ApiKeyRequired": false, "AuthorizationType": "NONE", "RouteId": "72jz1wk", "RouteKey": "ANY /admin", "Target": "integrations/a1b2c3" }, { "ApiGatewayManaged": true, "ApiKeyRequired": false, "AuthorizationType": "NONE", "RouteId": "go65gqi", "RouteKey": "$default", "Target": "integrations/a1b2c4" } ] }

第二条路由带有"ApiGatewayManaged": true标记，RouteKey为$default。这是因为使用 Quick Create 方式创建 API 时，API Gateway 会自动生成一条受管的$default路由，其RouteKey不可被用户修改。

二、请求参数详解

从 service-2.json 中的GetRoutesRequest定义可知，该操作共支持以下参数：

注意：--max-results在 API 层面是字符串类型（shape: __string，location: querystring），这是 AWS API 模型中的一个细节——分页限制值在传输层以字符串形式传递。

三、响应字段：Route 结构体完整说明

每条路由由Route结构体表示。结合 service-2.json 中的完整字段定义，各字段含义如下：

AuthorizationType 取值范围

从源码中的枚举定义可以确认，该字段在两种 API 类型下有不同的合法值：

WebSocket API：

• NONE— 开放访问，无需授权
• AWS_IAM— 使用 IAM 权限验证
• CUSTOM— 使用 Lambda 自定义授权器

HTTP API：

• NONE— 开放访问
• JWT— 使用 JSON Web Token 授权
• AWS_IAM— 使用 IAM 权限验证
• CUSTOM— 使用 Lambda 自定义授权器

四、分页机制

分页器配置

从 paginators-1.json 中可以看到GetRoutes的分页配置：

{ "input_token": "NextToken", "limit_key": "MaxResults", "output_token": "NextToken", "result_key": "Items" }

这意味着get-routes是一个自动分页操作：AWS CLI 会在需要时自动发起多次 API 调用来获取完整数据集，并在最终输出的NextToken字段（如果结果被截断）中提供续传令牌。

CLI 层统一分页参数

AWS CLI 通过 paginate.py 中的register_pagination函数对分页参数进行统一封装，为get-routes这类可分页操作注入以下 CLI 参数：

重要提示（来自 paginate.py 的文档说明）：当使用--output text配合--query参数时，JMESPath 查询表达式必须从Items键中提取数据，因为这是分页结果的result_key。

手动分页 vs 自动分页

如果你熟悉底层 API，也可以直接使用原始分页参数（--max-results、--next-token）。从 paginate.py 源码中可以看到，一旦检测到用户传入了这些"手动"分页参数，AWS CLI 会自动禁用自动分页（parsed_globals.paginate = False），并恢复原始参数行为。这一设计保证了向后兼容性——老版本脚本中手动分页的逻辑不会因 CLI 升级而失效。

五、底层 API 调用与错误处理

HTTP 层行为

从 service-2.json 中的操作定义：

HTTP 方法：GET 请求 URI： /v2/apis/{apiId}/routes 响应码： 200 认证方式： aws.auth#sigv4（AWS Signature Version 4）

该服务使用sigv4签名认证，签名名称为apigateway（注意：apigatewayv2服务的签名名称继承自apigateway，这是一个容易混淆的细节）。

可能返回的错误

遇到NotFoundException时，首先检查--api-id是否正确；遇到TooManyRequestsException时，建议加入重试退避逻辑。

六、示例文档的生成机制

get-routes.rst所在的 awscli/examples/apigatewayv2/ 目录中的.rst文件，是 AWS CLI 帮助文档中Examples小节的来源。其工作机制由 addexamples.py 实现：

1. 当用户执行aws apigatewayv2 get-routes help时，CLI 触发doc-examples.*.*事件；
2. add_examples函数根据event_class（格式为服务名.操作名）定位到对应路径的.rst文件；
3. 若文件存在，将其内容以 HTML 片段形式插入生成的帮助文档中，并在顶部附加一条说明提示（提醒用户需先安装配置 AWS CLI）。

这意味着，你在终端中看到的所有官方示例，都直接来源于仓库中这些.rst文件的内容，而非硬编码在代码中。

七、实战示例组合

列出路由并筛选特定 RouteKey

aws apigatewayv2 get-routes \ --api-id a1b2c3d4 \ --query "Items[?RouteKey=='ANY /admin'].RouteId" \ --output text

限制返回数量并手动分页

# 第一页 aws apigatewayv2 get-routes \ --api-id a1b2c3d4 \ --max-results 10 # 使用返回的 NextToken 获取下一页 aws apigatewayv2 get-routes \ --api-id a1b2c3d4 \ --max-results 10 \ --next-token <上一步返回的NextToken>

获取完整路由详情（配合 get-route）

get-routes返回的列表中，每条路由的RouteId可作为 get-route 命令的入参，用于查看单条路由的完整配置（包括AuthorizationScopes、AuthorizerId等字段）：

aws apigatewayv2 get-route \ --api-id a1b2c3d4 \ --route-id 72jz1wk

八、参考文件

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