AWS CLI 实战使用aws apigateway create-base-path-mapping为自定义域名配置 API Gateway 基础路径映射【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli导读本文基于 aws-cli 仓库中create-base-path-mapping官方示例文档系统讲解 API Gateway 自定义域名下的 BasePathMapping基础路径映射机制如何将形如subdomain.domain.tld/v1的请求路径精确路由到指定 REST API 的某个 Stage。你将掌握create-base-path-mapping的全部参数语义包括(none)特殊值、私有自定义域名的domainNameId参数、底层 REST API 调用模型以及查询、修改、删除映射的完整命令行生命周期。什么是 BasePathMapping在 API Gateway 中自定义域名Custom Domain Name是用户对外暴露 API 的入口。一个自定义域名下往往承载着多个 API、多个版本或多个环境需要一种机制把域名之后的第一段 URL 路径解析到某个 REST API 的某个 Stage。这个机制就是BasePathMapping基础路径映射。从本仓库的 API 模型定义看awscli/botocore/data/apigateway/2015-07-09/service-2.json 中的BasePathMapping结构一个映射由三个核心字段组成字段含义basePath调用方必须在域名之后提供的路径段用于识别该映射restApiId关联的 REST API 字符串标识符stage该 API 下被关联的 Stage 名称CreateBasePathMapping操作在模型中的文档说明是 Creates a new BasePathMapping resource其 HTTP 定义为POST /domainnames/{domain_name}/basepathmappings成功返回 HTTP 201。也就是说每个映射资源都隶属于某个域名domain_name一个域名下可以注册多条映射。核心命令创建基础路径映射create-base-path-mapping示例文档awscli/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这条命令的效果当客户端请求https://subdomain.domain.tld/v1/...时API Gateway 会把请求转发到restApiId为1234123412的 REST API 的prodStage。参数详解对照模型CreateBasePathMappingRequestservice-2.json 中同名字节该命令支持的参数及语义如下参数必填类型说明--domain-name是String要创建映射的自定义域名。在底层 REST API 中作为 URI 路径变量domain_name传递--rest-api-id是String关联的 REST API 字符串标识符形如1234123412--base-path否String调用方在域名之后必须提供的路径段。该值在一个 API 的所有映射中必须唯一。若不想让调用方在域名后携带路径需显式传(none)--stage否String该 API 下用于此映射的 Stage 名。若希望调用方显式拼接 Stage 名则传(none)--domain-name-id否String域名资源标识符仅私有自定义域名PRIVATE endpoint type必填以查询字符串domainNameId传递这里有两个极易混淆的(none)约定值得单独强调--base-path (none)表示没有路径前缀即请求https://subdomain.domain.tld/直接命中映射--stage (none)表示不在映射中固定 Stage调用方必须在 base path 之后显式写出 stage 名例如https://subdomain.domain.tld/v1/prod/...。注意(none)是带括号的字符串字面量命令中必须用引号包裹以避免 shell 解析问题。前置条件自定义域名必须已存在映射是挂在域名之下的资源URI 为/domainnames/{domain_name}/basepathmappings因此在执行create-base-path-mapping之前必须先通过aws apigateway create-domain-name创建对应的自定义域名。仓库中的 awscli/examples/apigateway/create-domain-name.rst 给出了两种典型场景公共自定义域名aws apigateway create-domain-name \ --domain-name my.domain.tld \ --certificate-name my.domain.tld cert \ --certificate-arn arn:aws:acm:us-east-1:012345678910:certificate/fb1b9770-a305-495d-aefb-27e5e101ff3私有自定义域名需显式指定 PRIVATE endpoint 类型并附加资源策略策略通常以文件形式传入aws apigateway create-domain-name \ --domain-name my.private.domain.tld \ --certificate-name my.domain.tld cert \ --certificate-arn arn:aws:acm:us-east-1:012345678910:certificate/fb1b9770-a305-495d-aefb-27e5e101ff3 \ --endpoint-configuration {types: [PRIVATE]} \ --security-policy TLS_1_2 \ --policy file://policy.json私有域名创建成功后响应中会返回domainNameId如abcd1234和domainNameArn。这个domainNameId正是前述--domain-name-id参数的取值来源——在私有自定义域名场景下创建映射时必须把它一并传入API Gateway 才能唯一定位目标域名资源。这也解释了为什么CreateBasePathMappingRequest模型中domainNameId的文档描述明确写着 Required for private custom domain names。映射的生命周期管理基础路径映射创建后并非一成不变本仓库awscli/examples/apigateway/目录下还提供了与之配套的查询、修改与删除示例共同构成完整的操作闭环。查看单个映射get-base-path-mappingawscli/examples/apigateway/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 }对应底层GET /domainnames/{domain_name}/basepathmappings/{base_path}返回BasePathMapping结构basePath、restApiId、stage 三个字段。列出域名下全部映射get-base-path-mappingsawscli/examples/apigateway/get-base-path-mappings.rst 展示了列表查询可以看到同一域名下可同时存在多条映射例如一条(none)根路径映射指向 dev一条v1映射指向 apiaws apigateway get-base-path-mappings --domain-name subdomain.domain.tld{ items: [ { basePath: (none), restApiId: 1234w4321e, stage: dev }, { basePath: v1, restApiId: 1234w4321e, stage: api } ] }从模型看GetBasePathMappingsRequest支持position分页游标和limit每页最大结果数默认 25、上限 500两个可选参数对应返回结构BasePathMappings由position与items组成。仓库的 awscli/botocore/data/apigateway/2015-07-09/paginators-1.json 中将GetBasePathMappings声明为可分页操作input_token: position、output_token: position、limit_key: limit、result_key: items因此你可以在 CLI 中直接追加--page-size、--max-items等参数控制分页遍历由 CLI 自动循环翻页。修改映射update-base-path-mapping修改映射走 API Gateway 通用的 PATCH 语义底层为PATCH /domainnames/{domain_name}/basepathmappings/{base_path}通过--patch-operations传入一组 PatchOperation。awscli/examples/apigateway/update-base-path-mapping.rst 示例将 basePath 从prod改为v1aws apigateway update-base-path-mapping --domain-name api.domain.tld --base-path prod --patch-operations opreplace,path/basePath,valuev1{ basePath: v1, restApiId: 1234123412, stage: api }对照模型PatchOperationservice-2.jsonop的合法取值为add、remove、replace、move、copy、test具体哪些操作对 BasePathMapping 生效取决于服务端支持path使用 JSON Pointer 语法定位目标属性例如/basePath、/stage、/restApiId路径中的/字符需转义为~1value是 add/replace 操作的新值。当value是 JSON 对象时模型文档特别提示在 Linux shell 下要用单引号包裹如{a: ...}。删除映射delete-base-path-mappingawscli/examples/apigateway/delete-base-path-mapping.rst 给出删除命令底层对应DELETE /domainnames/{domain_name}/basepathmappings/{base_path}成功返回 HTTP 202aws apigateway delete-base-path-mapping --domain-name api.domain.tld --base-path dev底层 REST API 映射一览把上述 CLI 命令与模型http定义一一对应可以得到清晰的调用链全部来自 service-2.json 中operations定义CLI 命令HTTP 方法URI 模板成功状态码create-base-path-mappingPOST/domainnames/{domain_name}/basepathmappings201get-base-path-mappingGET/domainnames/{domain_name}/basepathmappings/{base_path}200get-base-path-mappingsGET/domainnames/{domain_name}/basepathmappings200update-base-path-mappingPATCH/domainnames/{domain_name}/basepathmappings/{base_path}200delete-base-path-mappingDELETE/domainnames/{domain_name}/basepathmappings/{base_path}202可以看到base_path在创建时是请求体字段在查询、修改、删除时则升级为 URI 路径变量——这正解释了为什么更新 basePath 时需要先按旧路径如示例中的prod定位资源再通过 PATCH 替换成新值。使用建议与注意事项先建域名再建映射create-base-path-mapping依赖已存在的自定义域名且私有域名还需先拿到domainNameId顺序不可颠倒。basePath 唯一性模型明确要求 base path 在单个 API 的所有映射中唯一规划多版本共存时建议采用v1、v2或环境名作为路径段。理解(none)的两种用法--base-path (none)与--stage (none)含义完全不同前者去掉路径前缀后者要求调用方显式携带 Stage 名切勿混用。更新映射用 PATCH 而非重建优先通过update-base-path-mapping配合 JSON Pointer 精准修改单个属性避免删除重建造成的短暂不可用。利用分页域名下映射数量较多时get-base-path-mappings支持position/limit分页CLI 端可配合--max-items安全遍历全量结果。小结aws apigateway create-base-path-mapping是打通自定义域名 → REST API → Stage三层路由的关键命令。通过本文你已掌握其参数语义、(none)特殊约定、私有域名的domainNameId要求以及 get/update/delete 组成的完整映射生命周期操作所有命令均可在 aws-cli 仓库的 awscli/examples/apigateway 目录下找到配套示例模型级参数定义可进一步查阅 awscli/botocore/data/apigateway/2015-07-09/service-2.json 进行交叉验证。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考