企业官网建设流程全解析

aws apigatewayv2 get-routing-rule 实战指南：查询 API Gateway 自定义域名的路由规则

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

本文以 aws-cli 内置的get-routing-rule官方示例为骨架，完整讲解该命令的参数、输出结构及其在服务模型中的底层定义。读完本文，你可以直接在 AWS API Gateway 中按域名与规则 ID 查询路由规则，理解Actions、Conditions、Priority等输出字段的真实含义，并掌握与create-routing-rule、put-routing-rule、list-routing-rules配套的完整路由规则管理流程。

一、路由规则（Routing Rule）是什么

API Gateway 的自定义域名（Custom Domain Name）上可以挂载多条路由规则。每条规则由两部分组成：

• Conditions（条件）：描述什么样的请求会命中该规则，例如按请求 URI 的基础路径（base path）匹配；
• Actions（动作）：请求命中后要执行的动作，当前模型中仅支持InvokeApi，即把请求转发给某个 API 的某个 Stage。

通过get-routing-rule，你可以拉取某条路由规则的完整定义，用于验证路由配置是否正确、排查自定义域名上请求转发不符合预期的问题。aws-cli 仓库中该操作的示例文档位于 get-routing-rule.rst。

二、命令与完整示例

get-routing-rule的用法是：指定域名（--domain-name）和路由规则 ID（--routing-rule-id），即可取回该规则。仓库示例中的完整命令如下：

aws apigatewayv2 get-routing-rule \ --domain-name 'regional.example.com' \ --routing-rule-id aaa111

返回输出（示例原文档中的完整返回体）：

{ "Actions": [ { "InvokeApi": { "ApiId": "abcd1234", "Stage": "prod", "StripBasePath": false } } ], "Conditions": [ { "MatchBasePaths": { "AnyOf": [ "PetStoreShopper" ] } } ], "Priority": 50, "RoutingRuleArn": "arn:aws:apigateway:us-east-2:123456789012:/domainnames/regional.example.com/routingrules/aaa111", "RoutingRuleId": "aaa111" }

从返回体可以读出这条规则的语义：凡是以基础路径PetStoreShopper开头的请求，都会被转发到 APIabcd1234的prod阶段，且不做基础路径剥离（StripBasePath: false）。

三、参数详解

结合 aws-cli 随附的 API Gateway V2 服务模型 service-2.json（GetRoutingRuleRequest结构定义），该命令的请求参数如下：

模型中required字段明确列出RoutingRuleId和DomainName两个必填成员，这也解释了为什么示例命令必须同时提供--domain-name和--routing-rule-id。

四、输出字段逐项解析

GetRoutingRuleResponse结构（见 service-2.json）定义了五个返回字段，逐一对照上面示例输出：

• Actions：命中条件后执行的动作列表。模型文档说明“Only InvokeApi is supported”，即列表中每个动作对象只会出现InvokeApi键，其下包含：
  • ApiId：目标 API 的 ID；
  • Stage：目标阶段（Stage）名称；
  • StripBasePath：转发时是否剥离 URI 中的基础路径，示例中为false，即保留原始路径转发。
• Conditions：规则匹配条件列表。示例中的MatchBasePaths.AnyOf表示只要请求的基础路径匹配数组中任意一个值即命中；该结构是“匹配基础路径”这类条件的标准写法。
• Priority：规则的求值优先级。模型文档明确写道：“Priority is evaluated from the lowest value to the highest value”，即 API Gateway按数值从小到大依次评估规则，数值小的规则先被匹配，命中即停止。示例中Priority: 50。
• RoutingRuleArn：规则的资源 ARN，格式为arn:aws:apigateway:<region>:<account-id>:/domainnames/<domain-name>/routingrules/<routing-rule-id>，可用于 IAM 授权与资源引用。
• RoutingRuleId：规则 ID，与请求参数--routing-rule-id对应，后续put-routing-rule（更新）、delete-routing-rule（删除）都需要用它。

五、模型层的 API 行为：HTTP 方法与错误码

从服务模型看（GetRoutingRule 操作定义），该命令底层发起的 HTTP 请求为：

GET /v2/domainnames/{domainName}/routingrules/{routingRuleId}

成功时返回 HTTP 200。模型同时声明了三种可能的错误，对应到 CLI 执行时的报错场景：

因此在编写自动化脚本时，建议对NotFoundException（404）单独处理，以区分“规则不存在”和真正的网络/权限故障。

六、配套操作：路由规则的完整生命周期

get-routing-rule通常不是孤立使用的。aws-cli 仓库在同一目录下提供了整套路由规则示例（均位于 awscli/examples/apigatewayv2/ 目录），与查询操作构成完整的 CRUD 流程：

1. 创建：create-routing-rule在域名上新建一条规则，需指定--priority、--conditions、--actions，详见 create-routing-rule.rst：

aws apigatewayv2 create-routing-rule \ --domain-name 'regional.example.com' \ --priority 50 \ --conditions '[ \ { \ "MatchBasePaths": { \ "AnyOf": [ \ "PetStoreShopper" \ ] \ } \ } \ ]' \ --actions '[ \ { \ "InvokeApi": { \ "ApiId": "abcd1234", \ "Stage": "prod" \ } \ } \ ]'

2. 查询单条：本文讲解的get-routing-rule，按域名 + 规则 ID 精确取回一条规则。
3. 列出全部：list-routing-rules列出某域名下的所有规则，输出为包含RoutingRules数组的列表结构（支持分页时携带NextToken），详见 list-routing-rules.rst。实践中可以先用list-routing-rules获取RoutingRuleId，再调用get-routing-rule查看单条详情。
4. 更新：put-routing-rule按规则 ID 更新规则内容（优先级、条件、动作），注意它是整体替换语义，更新时需要重新提交完整的--conditions与--actions，详见 put-routing-rule.rst：

aws 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" } } ]'

示例把优先级从50调整为150，说明通过get→ 修改 →put的流程可以安全地调整规则优先级。 5.删除：delete-routing-rule按规则 ID 删除，对应文件 delete-routing-rule.rst。

七、使用建议与注意事项

• 前提条件：执行该命令需要有效的 AWS 凭证与 API Gateway 调用权限，且目标域名与规则必须存在于当前凭证所在区域内；--domain-name必须是已配置在 API Gateway 下的自定义域名（如regional.example.com形式的区域域名）。
• 规则 ID 的获取：RoutingRuleId可从list-routing-rules输出中读取，也可以从任意规则的RoutingRuleArn末段解析得到（示例中为aaa111）。
• 优先级排序方向：再次强调，Priority数值越小越先评估。调整规则顺序时，put-routing-rule是唯一的修改入口。
• 条件与动作的组合：Conditions是数组、Actions也是数组，但模型层面Actions仅支持InvokeApi；条件方面MatchBasePaths使用AnyOf列表表达“任一匹配即命中”，编写--conditionsJSON 时注意其为 JSON 数组字符串。
• 排障顺序：当自定义域名的流量没有按预期转发时，建议先list-routing-rules确认规则是否存在，再get-routing-rule核对Priority、Conditions与InvokeApi指向的 API/Stage 是否正确，最后检查StripBasePath的设置是否符合后端路由要求。

以上命令与输出均源自 aws-cli 仓库中apigatewayv2的官方示例与服务模型定义，可直接作为脚本与自动化任务中的参照模板。

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