2026/9/14 12:06:13
FEATURED · 精选文章 
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定义可知该操作共支持以下参数参数类型必填位置说明--api-idstring是URI 路径/v2/apis/{apiId}/routesAPI 标识符--max-resultsstring否查询参数单次请求返回的最大元素数量--next-tokenstring否查询参数用于获取下一页结果的分页令牌注意--max-results在 API 层面是字符串类型shape: __stringlocation: querystring这是 AWS API 模型中的一个细节——分页限制值在传输层以字符串形式传递。三、响应字段Route 结构体完整说明每条路由由Route结构体表示。结合 service-2.json 中的完整字段定义各字段含义如下字段类型说明RouteIdstring路由标识符由 API Gateway 自动生成RouteKeystring必填路由键格式为HTTP方法 路径如ANY /admin、GET /pets或 WebSocket 动作如$connectTargetstring路由目标通常为集成 ID格式为integrations/integration-idAuthorizationTypeenum授权类型取值见下文ApiKeyRequiredboolean是否要求 API Key仅 WebSocket API 支持ApiGatewayManagedboolean是否为 API Gateway 自动管理的路由Quick Create 生成的$default路由即为此类型AuthorizationScopeslistJWT 授权器使用的授权范围列表AuthorizerIdstring关联的自定义授权器标识符OperationNamestring路由操作名称RequestModels/RequestParameters/RouteResponseSelectionExpression—仅 WebSocket API 支持的字段AuthorizationType 取值范围从源码中的枚举定义可以确认该字段在两种 API 类型下有不同的合法值WebSocket APINONE— 开放访问无需授权AWS_IAM— 使用 IAM 权限验证CUSTOM— 使用 Lambda 自定义授权器HTTP APINONE— 开放访问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 参数CLI 参数说明--starting-token指定从哪里开始分页值为上次响应的NextToken--max-items命令输出中返回的总元素数量上限超出时输出NextToken--page-size每次 API 调用的页面大小较小的值可减少单次调用超时风险--no-paginate禁用自动分页仅执行单次 API 调用重要提示来自 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#sigv4AWS Signature Version 4该服务使用sigv4签名认证签名名称为apigateway注意apigatewayv2服务的签名名称继承自apigateway这是一个容易混淆的细节。可能返回的错误错误类型含义NotFoundException请求指定的资源API不存在TooManyRequestsException请求频率超过限制限流BadRequestException请求中的某个参数无效遇到NotFoundException时首先检查--api-id是否正确遇到TooManyRequestsException时建议加入重试退避逻辑。六、示例文档的生成机制get-routes.rst所在的 awscli/examples/apigatewayv2/ 目录中的.rst文件是 AWS CLI 帮助文档中Examples小节的来源。其工作机制由 addexamples.py 实现当用户执行aws apigatewayv2 get-routes help时CLI 触发doc-examples.*.*事件add_examples函数根据event_class格式为服务名.操作名定位到对应路径的.rst文件若文件存在将其内容以 HTML 片段形式插入生成的帮助文档中并在顶部附加一条说明提示提醒用户需先安装配置 AWS CLI。这意味着你在终端中看到的所有官方示例都直接来源于仓库中这些.rst文件的内容而非硬编码在代码中。七、实战示例组合列出路由并筛选特定 RouteKeyaws apigatewayv2 get-routes \ --api-id a1b2c3d4 \ --query Items[?RouteKeyANY /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-routeget-routes返回的列表中每条路由的RouteId可作为 get-route 命令的入参用于查看单条路由的完整配置包括AuthorizationScopes、AuthorizerId等字段aws apigatewayv2 get-route \ --api-id a1b2c3d4 \ --route-id 72jz1wk八、参考文件文件说明get-routes.rst本文核心示例来源get-route.rst单条路由查询示例service-2.jsonAPI 模型定义含 GetRoutes 操作、Route 结构体paginators-1.json分页器配置paginate.pyCLI 分页参数统一封装实现addexamples.py示例文档注入帮助系统的机制【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
AWS CLI 中 API Gateway V2 的 get-routes 命令：列出 HTTP/WebSocket API 路由的完整指南
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定义可知该操作共支持以下参数参数类型必填位置说明--api-idstring是URI 路径/v2/apis/{apiId}/routesAPI 标识符--max-resultsstring否查询参数单次请求返回的最大元素数量--next-tokenstring否查询参数用于获取下一页结果的分页令牌注意--max-results在 API 层面是字符串类型shape: __stringlocation: querystring这是 AWS API 模型中的一个细节——分页限制值在传输层以字符串形式传递。三、响应字段Route 结构体完整说明每条路由由Route结构体表示。结合 service-2.json 中的完整字段定义各字段含义如下字段类型说明RouteIdstring路由标识符由 API Gateway 自动生成RouteKeystring必填路由键格式为HTTP方法 路径如ANY /admin、GET /pets或 WebSocket 动作如$connectTargetstring路由目标通常为集成 ID格式为integrations/integration-idAuthorizationTypeenum授权类型取值见下文ApiKeyRequiredboolean是否要求 API Key仅 WebSocket API 支持ApiGatewayManagedboolean是否为 API Gateway 自动管理的路由Quick Create 生成的$default路由即为此类型AuthorizationScopeslistJWT 授权器使用的授权范围列表AuthorizerIdstring关联的自定义授权器标识符OperationNamestring路由操作名称RequestModels/RequestParameters/RouteResponseSelectionExpression—仅 WebSocket API 支持的字段AuthorizationType 取值范围从源码中的枚举定义可以确认该字段在两种 API 类型下有不同的合法值WebSocket APINONE— 开放访问无需授权AWS_IAM— 使用 IAM 权限验证CUSTOM— 使用 Lambda 自定义授权器HTTP APINONE— 开放访问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 参数CLI 参数说明--starting-token指定从哪里开始分页值为上次响应的NextToken--max-items命令输出中返回的总元素数量上限超出时输出NextToken--page-size每次 API 调用的页面大小较小的值可减少单次调用超时风险--no-paginate禁用自动分页仅执行单次 API 调用重要提示来自 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#sigv4AWS Signature Version 4该服务使用sigv4签名认证签名名称为apigateway注意apigatewayv2服务的签名名称继承自apigateway这是一个容易混淆的细节。可能返回的错误错误类型含义NotFoundException请求指定的资源API不存在TooManyRequestsException请求频率超过限制限流BadRequestException请求中的某个参数无效遇到NotFoundException时首先检查--api-id是否正确遇到TooManyRequestsException时建议加入重试退避逻辑。六、示例文档的生成机制get-routes.rst所在的 awscli/examples/apigatewayv2/ 目录中的.rst文件是 AWS CLI 帮助文档中Examples小节的来源。其工作机制由 addexamples.py 实现当用户执行aws apigatewayv2 get-routes help时CLI 触发doc-examples.*.*事件add_examples函数根据event_class格式为服务名.操作名定位到对应路径的.rst文件若文件存在将其内容以 HTML 片段形式插入生成的帮助文档中并在顶部附加一条说明提示提醒用户需先安装配置 AWS CLI。这意味着你在终端中看到的所有官方示例都直接来源于仓库中这些.rst文件的内容而非硬编码在代码中。七、实战示例组合列出路由并筛选特定 RouteKeyaws apigatewayv2 get-routes \ --api-id a1b2c3d4 \ --query Items[?RouteKeyANY /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-routeget-routes返回的列表中每条路由的RouteId可作为 get-route 命令的入参用于查看单条路由的完整配置包括AuthorizationScopes、AuthorizerId等字段aws apigatewayv2 get-route \ --api-id a1b2c3d4 \ --route-id 72jz1wk八、参考文件文件说明get-routes.rst本文核心示例来源get-route.rst单条路由查询示例service-2.jsonAPI 模型定义含 GetRoutes 操作、Route 结构体paginators-1.json分页器配置paginate.pyCLI 分页参数统一封装实现addexamples.py示例文档注入帮助系统的机制【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
