企业官网建设流程全解析

AWS CLI 实战：用aws apigateway get-base-path-mappings查询自定义域名的 Base Path 映射

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

aws apigateway get-base-path-mappings是 AWS CLI 提供的 API Gateway 命令，用于列出某个自定义域名（custom domain name）下全部 Base Path 映射（Base Path Mapping），帮助开发者确认哪个 REST API 的哪个 Stage 被挂载到了域名的哪个路径前缀上。读完本文，你将掌握该命令的完整参数、输出结构与分页用法，并理解其底层服务模型实现，能够直接在实际项目中查询和排查自定义域名的路由配置。

Base Path Mapping 是什么

在 API Gateway 中，自定义域名（例如api.example.com）本身并不直接指向某个 API，而是通过Base Path Mapping（基础路径映射）将「域名 + 路径前缀」绑定到「某个 REST API 的某个 Stage」。

一个典型的映射关系如下：

• 请求https://subdomain.domain.tld/v1/...→ 转发到 REST API1234w4321e的apiStage；
• 请求https://subdomain.domain.tld/...（无路径前缀）→ 转发到 REST API1234w4321e的devStage。

get-base-path-mappings命令解决的就是批量查看这些映射关系的问题：给定一个域名，返回该域名下的所有 Base Path Mapping 条目；如果只想查某一条，则使用单数形式的get-base-path-mapping命令。

命令语法与参数详解

关联文档给出了命令的最基本形态：

aws apigateway get-base-path-mappings --domain-name subdomain.domain.tld

从服务模型中可以看到，该操作的 HTTP 层实现为GET /domainnames/{domain_name}/basepathmappings（见 service-2.json），对应的请求参数定义在GetBasePathMappingsRequestshape 中。除了必填的domainName外，还支持以下可选参数：

其中--position和--limit是服务端分页控制参数：服务模型注释明确写明 limit "The default value is 25 and the maximum value is 500"。多数情况下，配合 CLI 的--page-size参数即可自动处理分页，无需手工传入position。

输出结构：BasePathMappings 与 BasePathMapping

命令的响应结构由BasePathMappings定义，包含两个成员：

• position：String 类型，指示当前分页位置。若返回了该字段，说明还有更多数据，可将其作为下一轮请求的--position传入；
• items：BasePathMapping 对象列表，即当前页的映射条目。

每个映射条目（BasePathMappingshape）包含三个字段，含义如下：

• basePath：调用方在域名后必须提供的路径前缀。关联文档输出中的"(none)"是 API Gateway 的特殊表示，含义是没有路径前缀，即该映射挂在域名的根路径/上；
• restApiId：所关联 REST API 的字符串标识符；
• stage：所关联 Stage 的名称。

解读关联文档中的示例输出

{ "items": [ { "basePath": "(none)", "restApiId": "1234w4321e", "stage": "dev" }, { "basePath": "v1", "restApiId": "1234w4321e", "stage": "api" } ] }

这条输出说明域名subdomain.domain.tld下配置了两条映射：

1. basePath为(none)，即请求https://subdomain.domain.tld/会路由到 REST API1234w4321e的devStage；
2. basePath为v1，即请求https://subdomain.domain.tld/v1/会路由到同一个 REST API 的apiStage。

注意：当 API 未配置任何 Stage 时，stage字段可能为空；输出中未出现position字段，说明结果集只有一页，无需继续分页。

分页与大量结果的查询策略

get-base-path-mappings支持分页。仓库中的 paginators-1.json 为GetBasePathMappings定义了分页配置：

input_token: position output_token: position limit_key: limit result_key: items

这意味着 AWS CLI 的底层 botocore 已经将该操作注册为可分页操作，items是结果聚合键。在实际使用中，如果域名下映射较多（超过单页限制），最稳妥的写法是利用 CLI 内置的分页参数：

aws apigateway get-base-path-mappings --domain-name subdomain.domain.tld --page-size 100

--page-size会把底层请求的limit设为 100；若想一次性拉取全部结果（自动翻页直到position为空），可以追加：

aws apigateway get-base-path-mappings --domain-name subdomain.domain.tld --max-items 1000

如果需要手动控制游标，也可以先执行一次请求，读取返回的position，再把它作为--position传入第二轮请求。

错误场景速查

服务模型GetBasePathMappings定义了四类异常（见 service-2.json 中该操作的errors列表）：

• BadRequestException：请求参数非法，例如域名格式错误；
• NotFoundException：指定的--domain-name不存在，通常是域名尚未在 API Gateway 中注册或已被删除；
• UnauthorizedException：当前凭证无权查看该域名的映射；
• TooManyRequestsException：触发了 API 限流，可适当重试。

实际排查时，遇到NotFoundException应优先检查域名是否已通过aws apigateway get-domain-names创建成功，以及域名是否属于当前账号与区域。

与关联命令组合成完整工作流

get-base-path-mappings通常与同一套 Base Path Mapping 管理命令配合使用，仓库的 examples/apigateway 目录中收录了完整的增删改查示例：

• 创建映射：create-base-path-mapping.rst

aws apigateway create-base-path-mapping --domain-name subdomain.domain.tld --rest-api-id 1234123412 --stage prod --base-path v1

• 查询单条映射：get-base-path-mapping.rst

aws apigateway get-base-path-mapping --domain-name subdomain.domain.tld --base-path v1

• 修改映射的 basePath：update-base-path-mapping.rst

aws apigateway update-base-path-mapping --domain-name api.domain.tld --base-path prod --patch-operations op='replace',path='/basePath',value='v1'

• 删除映射：delete-base-path-mapping.rst

aws apigateway delete-base-path-mapping --domain-name 'api.domain.tld' --base-path 'dev'

典型的排查流程是：先用get-base-path-mappings列出域名下的全部映射，确认目标 API 与 Stage 是否已挂载、basePath是否符合预期；若未挂载则用create-base-path-mapping创建；若路径前缀写错则用update-base-path-mapping通过--patch-operations以 JSON Patch 方式替换/basePath；需要下线时再执行delete-base-path-mapping。

小结

• aws apigateway get-base-path-mappings --domain-name <域名>用于列出指定自定义域名下的全部 Base Path Mapping，输出项包含basePath、restApiId、stage；
• basePath为(none)表示根路径映射；响应中的position字段用于手动分页游标；
• 单页默认 25 条、上限 500 条，建议使用--page-size/--max-items由 CLI 自动翻页；
• 该命令对应 REST 接口GET /domainnames/{domain_name}/basepathmappings，分页配置与响应结构可直接在仓库的 service-2.json 与 paginators-1.json 中核对。

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