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

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-cliaws 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外还支持以下可选参数参数类型位置是否必填说明--domain-nameStringURI必填要查询的自定义域名名称对应 URL 路径中的{domain_name}--domain-name-idStringquery可选域名资源的标识符仅私有自定义域名private custom domain使用--positionStringquery可选分页游标用于从「当前分页位置」继续拉取下一页结果--limitIntegerquery可选每页最多返回的结果数默认值 25最大 500其中--position和--limit是服务端分页控制参数服务模型注释明确写明 limit The default value is 25 and the maximum value is 500。多数情况下配合 CLI 的--page-size参数即可自动处理分页无需手工传入position。输出结构BasePathMappings 与 BasePathMapping命令的响应结构由BasePathMappings定义包含两个成员positionString 类型指示当前分页位置。若返回了该字段说明还有更多数据可将其作为下一轮请求的--position传入itemsBasePathMapping 对象列表即当前页的映射条目。每个映射条目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下配置了两条映射basePath为(none)即请求https://subdomain.domain.tld/会路由到 REST API1234w4321e的devStagebasePath为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.rstaws apigateway create-base-path-mapping --domain-name subdomain.domain.tld --rest-api-id 1234123412 --stage prod --base-path v1查询单条映射get-base-path-mapping.rstaws apigateway get-base-path-mapping --domain-name subdomain.domain.tld --base-path v1修改映射的 basePathupdate-base-path-mapping.rstaws apigateway update-base-path-mapping --domain-name api.domain.tld --base-path prod --patch-operations opreplace,path/basePath,valuev1删除映射delete-base-path-mapping.rstaws 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、stagebasePath为(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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考