使用 AWS CLI 的 list-routing-rules 命令管理 API Gateway V2 自定义域名路由规则【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli导读本文基于 AWS CLI 官方示例文档awscli/examples/apigatewayv2/list-routing-rules.rst系统讲解如何使用aws apigatewayv2 list-routing-rules命令列出 API Gateway 自定义域名下绑定的路由规则并结合仓库内apigatewayv2服务的 API 模型service-2.json与分页器定义paginators-1.json深入剖析其请求参数、返回结构与底层调用链。读完本文你将掌握路由规则的查询命令、结果解读方法、分页参数的使用技巧并能通过配套的创建create-routing-rule与更新put-routing-rule示例构建完整的路由规则生命周期管理方案。一、路由规则Routing Rule是什么在 API Gateway 中路由规则用于将自定义域名下的请求按条件如 Base Path、请求头分发到不同的API 阶段Stage。它是把一个域名对应多个 API/版本落地为现实的关键机制Actions动作定义匹配成功后把请求转发给哪个 API 的哪个阶段InvokeApi。Conditions条件定义什么样的请求才会命中这条规则例如MatchBasePaths按基础路径匹配、MatchHeaders按请求头匹配。Priority优先级当多条规则同时可能命中时按优先级决定最终生效的规则。list-routing-rules命令正是用于查看某个自定义域名当前配置的全部路由规则是排障、审计和自动化脚本中的高频只读操作。仓库中与它配套的示例还包括创建规则 create-routing-rule.rst、更新规则 put-routing-rule.rst、删除规则 delete-routing-rule.rst以及单条查询 get-routing-rule.rst共同组成路由规则的完整操作集合。二、官方示例列出指定域名下的路由规则官方示例list-routing-rules.rst展示了一个最典型的用法——通过--domain-name指定域名列出该域名下的全部路由规则aws apigatewayv2 list-routing-rules \ --domain-name regional.example.com命令执行后的输出示例如下{ RoutingRules: [ { Actions: [ { InvokeApi: { ApiId: abcd1234, Stage: prod, StripBasePath: false } } ], Conditions: [ { MatchBasePaths: { AnyOf: [ PetStoreShopper ] } } ], Priority: 150, RoutingRuleArn: arn:aws:apigateway:us-east-1:123456789012:/domainnames/regional.example.com/routingrules/aaa111, RoutingRuleId: aaa111 } ] }输出字段逐项解读对照 service-2.json 中RoutingRule结构约第 10853 行的定义响应中每个规则对象包含以下字段字段类型说明Actions数组规则命中后执行的动作列表。当前仅支持InvokeApi一种动作RoutingRuleAction结构中InvokeApi为必填项。Conditions数组规则匹配条件列表支持MatchBasePaths基础路径匹配与MatchHeaders请求头匹配两类条件。Priority整数规则优先级取值范围 11,000,000RoutingRulePriority定义见 service-2.json 第 11004 行。数值越小优先级越高。RoutingRuleArn字符串规则的 Amazon 资源名称ARN格式形如arn:aws:apigateway:region:account-id:/domainnames/domain-name/routingrules/rule-id。RoutingRuleId字符串规则的唯一 ID后续执行put-routing-rule、delete-routing-rule时需用它来定位规则。在上述示例中Actions.InvokeApi.ApiId abcd1234表示命中后转发到 ID 为abcd1234的 APIActions.InvokeApi.Stage prod表示转发到该 API 的prod阶段Actions.InvokeApi.StripBasePath false表示不剥离匹配到的基础路径即上游 API 仍能收到完整的请求路径Conditions.MatchBasePaths.AnyOf [PetStoreShopper]表示当请求基础路径等于PetStoreShopper时命中本规则MatchBasePaths的AnyOf为必填且匹配是大小写敏感的见 service-2.json 第 10964 行的文档说明Priority 150表示该规则的优先级数值。从 API 模型看InvokeApi动作的ApiId与Stage均为必填RoutingRuleActionInvokeApi的required字段因此list-routing-rules返回的每个动作必然带有这两个属性StripBasePath为可选布尔值未设置时示例中显示为false。三、命令与请求参数详解3.1 参数一览根据 service-2.json 中ListRoutingRulesRequest结构第 8790 行的定义list-routing-rules支持以下参数CLI 参数位置必填说明--domain-nameURI 路径是自定义域名名称如regional.example.com。该参数会拼接到GET /v2/domainnames/{domainName}/routingrules请求中。--domain-name-id查询字符串否域名 ID用于在域名存在同名歧义时精确指定目标域名。--max-results查询字符串否单页最多返回的规则条数取值范围 1100MaxResults结构定义见 service-2.json 第 11010 行。--next-token查询字符串否分页游标。当结果多于max-results时从上一页响应的NextToken字段取值用于获取下一页数据。从 HTTP 层看ListRoutingRules操作在模型中被定义为GET /v2/domainnames/{domainName}/routingrules见 service-2.json 第 1994-1997 行响应码为 200DomainName是唯一必填参数。3.2 底层调用链在 AWS CLI 架构中aws apigatewayv2 list-routing-rules的执行路径大致为CLI 的argparser/argprocess模块解析命令行参数如--domain-name、--next-token并按照 service-2.json 中的参数定义完成参数校验与序列化botocore 依据模型中location: uri/location: querystring的定义把参数拼接到 HTTP 请求的 URI 路径与查询字符串上服务端返回的 JSON 响应由 botocore 的解析器按ListRoutingRulesResponse结构反序列化其中RoutingRules为规则数组、NextToken为分页游标见 service-2.json 第 8822-8834 行CLI 最终以 JSON默认或用户指定的输出格式呈现结果。3.3 错误处理ListRoutingRules在模型中声明了三种可能的错误见 service-2.json 第 2006-2018 行NotFoundException指定的域名或资源不存在即resource not foundTooManyRequestsException客户端请求频率超过服务端允许的每秒请求上限BadRequestException请求中的某个参数非法。在脚本中使用时建议对上述异常做好捕获与重试/降级处理。四、处理大量路由规则分页查询当域名下挂载的路由规则较多时单次调用可能返回不全。此时可以利用分页参数分批获取全部规则。从 paginators-1.json第 63-68 行可以看到ListRoutingRules已在服务端声明了分页器定义ListRoutingRules: { input_token: NextToken, output_token: NextToken, limit_key: MaxResults, result_key: RoutingRules }这意味着 AWS CLI 的--paginate机制可以直接作用于本命令input_token/output_token均为NextTokenlimit_key为MaxResults结果累积键为RoutingRules。4.1 方式一使用--paginate自动翻页aws apigatewayv2 list-routing-rules \ --domain-name regional.example.com \ --max-results 50 \ --paginateCLI 会自动循环携带NextToken发起多次请求并把多页的RoutingRules合并输出无需手工处理游标。4.2 方式二手工分页# 第一页 aws apigatewayv2 list-routing-rules \ --domain-name regional.example.com \ --max-results 50拿到响应中的NextToken后再请求下一页aws apigatewayv2 list-routing-rules \ --domain-name regional.example.com \ --max-results 50 \ --next-token PASTE_NEXT_TOKEN_HERE当响应中不再出现NextToken或其为 null时说明已经取完所有数据。五、实战结合创建与更新命令完成规则生命周期管理仅查询规则往往不够实际运维中通常是创建 → 查询确认 → 更新 → 再次查询验证的组合流程。仓库中与list-routing-rules强相关的示例可直接复用5.1 创建一条路由规则参考 create-routing-rule.rst创建优先级为50的规则把基础路径PetStoreShopper的请求转发到 APIabcd1234的prod阶段aws apigatewayv2 create-routing-rule \ --domain-name regional.example.com \ --priority 50 \ --conditions [ { MatchBasePaths: { AnyOf: [ PetStoreShopper ] } } ] \ --actions [ { InvokeApi: { ApiId: abcd1234, Stage: prod } } ]创建成功后返回的响应结构与list-routing-rules中单个规则对象的结构完全一致其中RoutingRuleId如aaa111和RoutingRuleArn会一并返回可直接用于后续查询与更新。5.2 更新规则优先级参考 put-routing-rule.rst通过--routing-rule-id指定规则把优先级从50调整到150aws apigatewayv2 put-routing-rule \ --routing-rule-id aaa111 \ --domain-name regional.example.com \ --priority 150 \ --conditions [ { MatchBasePaths: { AnyOf: [ PetStoreShopper ] } } ] \ --actions [ { InvokeApi: { ApiId: abcd1234, Stage: prod } } ]5.3 用 list-routing-rules 验证变更aws apigatewayv2 list-routing-rules --domain-name regional.example.com此时输出中对应规则的Priority应已变为150。通过修改 → 列表查询 → 核对字段的循环可以可靠地确认配置已按预期生效适合纳入自动化脚本或 CI 检查。5.4 在 Shell 脚本中过滤结果配合--query与--output选项可以把列表结果加工成更易用的形式。例如只列出每条规则的 ID 与优先级aws apigatewayv2 list-routing-rules \ --domain-name regional.example.com \ --query RoutingRules[].[RoutingRuleId, Priority] \ --output text或者按优先级从高到低排序优先级数值越小越优先aws apigatewayv2 list-routing-rules \ --domain-name regional.example.com \ --query sort_by(RoutingRules, Priority)[].[RoutingRuleId, Priority, RoutingRuleArn] \ --output table六、前置条件与注意事项命令可用版本list-routing-rules属于 API Gateway V2 的路由规则功能需要安装的 AWS CLI 版本内置的 botocore 服务模型包含ListRoutingRules操作可确认本地模型文件 service-2.json 中是否存在该定义。凭据与权限执行该命令需要具备apigateway:GET或对应路由规则只读权限且账号需能够访问目标域名所在的区域。区域一致性示例中RoutingRuleArn形如arn:aws:apigateway:us-east-1:...命令默认使用当前配置的区域如需操作其他区域的域名请通过--region显式指定。大小写敏感MatchBasePaths的AnyOf匹配是大小写敏感的service-2.json 第 10964 行文档原文为 case sensitive base path查询与创建时必须保持路径写法一致。优先级范围Priority合法取值范围为 11,000,000超出该范围将被服务端拒绝。七、小结aws apigatewayv2 list-routing-rules是查看 API Gateway 自定义域名路由规则配置的最直接入口。本文围绕官方示例list-routing-rules.rst完整拆解了命令用法与输出结构并从仓库的 API 模型service-2.json和分页器定义paginators-1.json出发解释了参数来源、分页机制与错误语义最后结合 create-routing-rule.rst 与 put-routing-rule.rst 给出了创建—查询—更新—验证的完整实践路径。掌握本命令即可高效地审计与维护自定义域名下的多 API 路由分发配置。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考