企业官网建设流程全解析

使用 aws-cli 的 update-base-path-mapping 修改 API Gateway 自定义域名的基础路径

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

导读

本文围绕 aws-cli 官方示例 update-base-path-mapping.rst 展开，讲解如何通过aws apigateway update-base-path-mapping命令修改 Amazon API Gateway 自定义域名（Custom Domain Name）上的基础路径（Base Path）映射。你将掌握该命令的完整参数语义、PATCH 操作（Patch Operation）的写法与取值范围，以及结合创建、查询、删除等配套命令进行生命周期管理的完整实战流程。

一、背景：什么是 Base Path Mapping

在 API Gateway 中，自定义域名（Custom Domain Name）需要绑定到一个具体的 REST API 与 Stage 上才能对外提供服务，这一绑定关系就是 Base Path Mapping。它决定了调用方在访问你的 API 时，URL 中域名之后必须携带哪一段路径前缀。

从服务模型看，一个 BasePathMapping 资源由三个字段构成（见 service-2.json 中BasePathMapping结构定义）：

也就是说，映射关系可以理解为domain-name + basePath → restApiId + stage。当你在api.domain.tld这个域名上配置了basePath = v1，那么请求https://api.domain.tld/v1/...就会被路由到对应 REST API 的对应 Stage。

二、核心命令：修改基础路径

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'

执行成功后返回该映射的最新状态：

{ "basePath": "v1", "restApiId": "1234123412", "stage": "api" }

2.1 命令参数逐项拆解

• --domain-name api.domain.tld：要修改映射的自定义域名名称，用于定位目标 BasePathMapping 资源；
• --base-path prod：当前已存在的旧基础路径，用于精确定位要修改的映射；
• --patch-operations ...：以 JSON 列表形式传入的 PATCH 操作数组，驱动本次修改的具体行为。

根据 service-2.json 中UpdateBasePathMappingRequest的定义，domainName与basePath都是必填参数，且两者都被放入请求 URI（/domainnames/{domain_name}/basepathmappings/{base_path}）；其中basePath有明确说明：若要指定空基础路径，可将该参数设置为'(none)'。此外还有一个可选参数domainNameId，仅用于私有自定义域名场景下的域名资源标识。

2.2 PATCH 操作语法：op / path / value

patchOperations中的每个元素都对应 service-2.json 中PatchOperation结构 的一个实例，包含四个成员：

示例中的op='replace',path='/basePath',value='v1'即表示：用 JSON Pointer/basePath定位旧基础路径字段，将其值prod替换为新值v1。

在使用 AWS CLI 时，--patch-operations参数可以直接写成op='replace',path='/basePath',value='v1'这样的逗号分隔简写形式，CLI 会自动将其解析为结构化的 JSON 列表。若要为属性传递 JSON 值，官方建议在 Linux shell 中用单引号包裹整个 JSON 对象，例如'{"a": ...}'（参见 service-2.json 中value字段的文档说明）。

三、PATCH 请求底层原理

UpdateBasePathMapping在 API 层面对应一次 HTTPPATCH请求，请求 URI 为/domainnames/{domain_name}/basepathmappings/{base_path}（见 service-2.json 中UpdateBasePathMapping操作定义）。这意味着：

• 修改基础路径本质上是面向资源的部分更新，而非整体替换；
• 请求可能返回的异常类型包括BadRequestException、ConflictException、LimitExceededException、NotFoundException、UnauthorizedException与TooManyRequestsException，你可以在脚本中据此区分错误场景（如资源不存在、权限不足或触发限流）。

从 CLI 的视角看，--patch-operations中的path字段之所以写作/basePath，是因为其目标对象是 BasePathMapping 资源本身，资源中可更新字段的 JSON Pointer 路径就是/basePath、/restApiId、/stage等。因此你同样可以借助 replace 操作修改该映射绑定的restApiId或stage，实现"保持域名不变、切换后端 API 或阶段"的效果。

四、完整的 Base Path Mapping 生命周期实战

修改只是生命周期中的一个环节。aws-cli 仓库在 awscli/examples/apigateway/ 目录下提供了全套配套示例，下面串成一条完整链路。

4.1 创建映射

参考 create-base-path-mapping.rst，将域名subdomain.domain.tld映射到 REST API1234123412的prod阶段，并指定基础路径为v1：

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

4.2 查询单个映射

参考 get-base-path-mapping.rst，按域名与基础路径精确查询：

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

输出示例：

{ "basePath": "v1", "restApiId": "1234w4321e", "stage": "api" }

4.3 列出域名下的全部映射

参考 get-base-path-mappings.rst，列出某域名下的所有映射（get-base-path-mappings是支持分页的列表操作，其GetBasePathMappings分页器定义在 paginators-1.json 中）：

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

输出示例中可以看到两种典型情况："(none)"表示该映射使用空基础路径（即直接以域名根路径访问），而v1则是一个带路径前缀的映射：

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

4.4 修改映射（本文主题）

需要"换路径"或"换 Stage"时，使用update-base-path-mapping执行 PATCH 替换：

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

4.5 删除映射

参考 delete-base-path-mapping.rst，解除域名与 API 的绑定关系：

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

五、常见场景与注意事项

1. 切换 Stage 做灰度：通过op='replace',path='/stage',value='new-stage'可将域名流量从旧 Stage 切到新 Stage，比删除重建更安全、更原子。
2. 空基础路径的处理：当映射使用根路径时，查询结果中basePath显示为"(none)"；若要修改或删除此类映射，--base-path参数同样需要传'(none)'。
3. 多操作组合：--patch-operations支持传入多个操作，例如同时替换basePath与stage，可写成op='replace',path='/basePath',value='v1' op='replace',path='/stage',value='api'（操作间以空格分隔）。
4. 错误处理：请求可能返回NotFoundException（资源不存在，通常是域名或基础路径写错）、BadRequestException（参数非法）或TooManyRequestsException（触发限流），建议在自动化脚本中对这几类错误分别处理并实现重试策略。

六、小结

update-base-path-mapping是管理 API Gateway 自定义域名路由的关键命令。理解其背后的 BasePathMapping 资源模型与 Patch Operation 语义（op/path/value/from），再配合create-、get-、get-*-s、delete-系列命令，即可在无需重建域名绑定关系的前提下，灵活调整 API 对外暴露的路径与版本，完成平滑的版本切换和灰度发布。

延伸阅读：完整的操作定义与参数结构可查阅 apigateway 服务模型，配套示例集中在 awscli/examples/apigateway/ 目录，其中与本主题直接相关的还包括 create-base-path-mapping.rst、get-base-path-mapping.rst、get-base-path-mappings.rst 与 delete-base-path-mapping.rst。

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