使用 AWS CLI 的 apigatewayv2 create-api-mapping 为自定义域名创建 API 映射实战指南

使用 AWS CLI 的 apigatewayv2 create-api-mapping 为自定义域名创建 API 映射实战指南【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli导读本文围绕 AWS CLI 官方示例文档 create-api-mapping.rst 展开系统讲解aws apigatewayv2 create-api-mapping命令的完整用法如何将 API Gateway v2HTTP API 与 WebSocket API中的某个 stage部署阶段映射到自定义域名Custom Domain Name的指定路径下。读完本文你将掌握 API 映射的概念、命令参数与返回字段的语义、从创建自定义域名到建立映射的完整工作流以及配套的查询、更新与删除命令并了解其底层 API 协议与常见错误处理方式。API 映射是什么为什么需要 create-api-mapping在 API Gateway v2即apigatewayv2服务中**API 映射API Mapping**负责把「自定义域名 路径前缀」与「具体的 API 及其 stage」绑定起来。其作用可以概括为让你的 API 通过自己拥有的域名如regional.example.com对外提供服务而不是默认的execute-api域名通过ApiMappingKey路径前缀在同一个域名下区分并路由到不同的 API 或不同的 stage例如https://regional.example.com/myApi映射到 APIa1b2c3d4的test阶段一个自定义域名可以挂载多个 API 映射每个映射对应不同的路径前缀实现域名复用与多环境共存。从本仓库的 API 模型看apigatewayv2服务还包含UpdateApiMapping修改映射、GetApiMappings列出映射、GetApiMapping查询单个映射与DeleteApiMapping删除映射等配套操作共同构成 API 映射的完整生命周期管理。模型文件位于 awscli/botocore/data/apigatewayv2/2018-11-29/service-2.json。前置条件必须先有自定义域名create-api-mapping命令的第一个必填参数就是--domain-name因此在使用本命令前你需要先完成自定义域名的注册与配置。仓库中同目录的示例 create-domain-name.rst 给出了标准的创建方式aws apigatewayv2 create-domain-name \ --domain-name regional.example.com \ --domain-name-configurations CertificateArnarn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678该命令会创建区域型REGIONAL自定义域名并将 AWS Certificate ManagerACM签发的 TLS 证书绑定到该域名。返回结果中值得注意的字段包括ApiMappingSelectionExpression值为$request.basepath即默认的 API 映射选择表达式——它决定入站请求的哪个部分这里是基础路径被提取出来与各映射的ApiMappingKey做匹配DomainNameStatusAVAILABLE表示域名已就绪可以开始创建 API 映射ApiGatewayDomainName、HostedZoneId用于在 Route 53 中配置 DNS 解析记录将自定义域名指向 API Gateway 分配的端点。只有域名状态变为AVAILABLE后create-api-mapping才能成功执行否则会返回域名相关错误。核心命令create-api-mapping 完整示例原文档create-api-mapping.rst提供的示例将 APIa1b2c3d4的test阶段映射到自定义域名regional.example.com的/myApi路径aws apigatewayv2 create-api-mapping \ --domain-name regional.example.com \ --api-mapping-key myApi \ --api-id a1b2c3d4 \ --stage test执行成功后的返回输出{ ApiId: a1b2c3d4, ApiMappingId: 0qzs2sy7bh, ApiMappingKey: myApi, Stage: test }创建完成后向https://regional.example.com/myApi/...发起的请求就会被路由到 APIa1b2c3d4的test阶段。参数详解字段语义、必填性与约束对照 service-2.json 中CreateApiMappingRequest的建模信息命令涉及的参数如下CLI 参数模型字段位置必填说明--domain-nameDomainNameURI 路径必填要绑定 API 的自定义域名必须已通过create-domain-name创建成功--api-idApiId请求体必填目标 API 的标识符HTTP API 或 WebSocket API 的 ID--stageStage请求体必填要暴露的部署阶段名称其长度约束为 1128 个字符--api-mapping-keyApiMappingKey请求体可选映射键路径前缀类型为选择键SelectionKey。省略时映射将绑定到域名的根路径几个值得深入的点--api-mapping-key的作用原理根据模型中对SelectionKey类型的描述API Gateway 会先对入站请求求值映射选择表达式默认$request.basepath再把求值结果与各映射的选择键逐一比对命中的映射即负责处理该请求。这也解释了示例中myApi对应路径/myApi的原因——基础路径正好与选择键相等。--stage的长度限制模型将其定义为StringWithLengthBetween1And128即长度必须在 1128 之间超长或为空均会被拒绝。--domain-name走 URI 而非请求体从模型可以看出DomainName的 location 是uri意味着它会被拼接到请求路径/v2/domainnames/{domainName}/apimappings中。这正是调用方参数如何映射到底层 HTTP 请求的体现——AWS CLI 的 botocore 解析层会依据该模型自动完成参数注入。底层 API 协议视角从仓库模型可以进一步确认该操作对应的底层 API 事实这部分属于服务模型而非 CLI 独有方法POST请求路径/v2/domainnames/{domainName}/apimappings成功状态码201 Created可返回的错误类型NotFoundException域名/API/stage 不存在、BadRequestException参数非法、ConflictException映射已存在、TooManyRequestsException请求频率超限。CLI 执行失败时这些异常会经由 AWS CLI 的错误处理链路以可读的错误信息呈现给用户。了解这些错误码有助于快速定位问题例如出现ConflictException说明该域名下已存在相同映射需要改用update-api-mapping或删除旧映射。完整工作流从域名到 API 映射将上述内容串联起来一个生产可用的最小流程如下准备 API 与 stage确认目标 HTTP/WebSocket API 存在且已通过create-deployment/create-stage准备好要暴露的阶段示例可参考同目录的 create-stage.rst。创建自定义域名执行上文create-domain-name命令并在 Route 53 配置 DNS 后等待DomainNameStatus变为AVAILABLE。创建 API 映射执行本文核心命令create-api-mapping将域名、API、stage、路径前缀绑定。验证通过curl https://regional.example.com/myApi/...或使用aws apigatewayv2 get-api-mappings确认映射生效。管理与排查配套命令API 映射创建后日常运维还需要查询、修改与删除能力仓库同目录提供了对应的官方示例列出某域名下所有映射get-api-mappings.rstaws apigatewayv2 get-api-mappings \ --domain-name api.example.com返回Items数组其中每个元素包含ApiId、ApiMappingId、ApiMappingKey与Stage可用于快速浏览域名下各路径的归属。查询单个映射详情get-api-mapping.rstaws apigatewayv2 get-api-mapping \ --api-mapping-id a1b2c3 \ --domain-name api.example.com更新映射update-api-mapping命令PATCH /v2/domainnames/{domainName}/apimappings/{apiMappingId}可修改ApiId、ApiMappingKey、Stage适用于调整路径前缀或切换目标 API/stage 的场景。删除映射delete-api-mapping命令DELETE同路径成功返回204用于解除域名与 API 的绑定。此外模型显示GetApiMappings还支持MaxResults与NextToken查询参数分别用于限制返回条数与翻页获取更多结果映射数量较多时可据此分批拉取。常见问题与注意事项映射键冲突同一域名下不同映射的ApiMappingKey不能重复冲突时会触发ConflictException。设计路径前缀时应统一规划避免多环境如test/dev互相覆盖。域名状态未就绪域名DomainNameStatus非AVAILABLE时创建映射会失败请先检查 ACM 证书绑定与 DNS 配置。stage 名称拼写--stage必须与已创建的 stage 名称完全一致1128 字符可通过get-stages确认现有 stage 列表。路径前缀与选择表达式匹配映射键应与域名级ApiMappingSelectionExpression默认$request.basepath的求值结果一致否则请求将无法被正确路由。小结aws apigatewayv2 create-api-mapping是打通「自定义域名 → API → stage → 路径前缀」链路的关键命令。本文以其官方示例create-api-mapping.rst为骨架结合 service-2.json 中的请求/响应建模、参数约束与底层 REST 协议补充了域名创建、映射查询、更新、删除的完整闭环。实际部署时请以仓库中同目录的 create-domain-name.rst、get-api-mappings.rst 等示例为参考按「先域名、后映射」的顺序完成配置即可。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考