对 HTTP API 使用 API 映射 - Amazon API Gateway
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

对 HTTP API 使用 API 映射

您可以使用 API 映射将 API 阶段连接到自定义域名。创建域名并配置 DNS 记录后,您可以使用 API 映射通过自定义域名向 API 发送流量。

API 映射指定了用于映射的 API、阶段以及可选的路径。例如,您可以将 API 的 production 阶段映射到 https://api.example.com/orders

您可以将 HTTP 和 REST API 阶段映射到相同的自定义域名。

在创建 API 映射之前,您必须拥有 API、阶段和自定义域名。要了解有关创建自定义域名的更多信息,请参阅 在 API Gateway 中设置区域自定义域名

路由 API 请求

您可以使用多个级别配置 API 映射,例如 orders/v1/itemsorders/v2/items

API Gateway 将请求路由到匹配路径最长的 API 映射。选择要调用的 API 时,API Gateway 仅考虑为 API 映射配置的路径,而不考虑 API 路由。如果没有与请求匹配的路径,API Gateway 会将请求发送到已映射到空路径 (none) 的 API。

例如,考虑使用以下 API 映射的自定义域名 https://api.example.com

  1. 映射到 API 1 的 (none)

  2. 映射到 API 2 的 orders/v1/items

  3. 映射到 API 3 的 orders/v2/items

  4. 映射到 API 4 的 orders/v2/items/categories

请求 选定的 API 说明

https://api.example.com/orders/v1/items

API 2

请求完全匹配此 API 映射。

https://api.example.com/orders/v2/items

API 3

请求完全匹配此 API 映射。

https://api.example.com/orders/v1/items/123

API 2

API Gateway 选择匹配路径最长的映射。请求结尾处的 123 不影响选择。

https://api.example.com/orders/v2/items/categories/5

API 4

API Gateway 选择匹配路径最长的映射。

https://api.example.com/customers

API 1

API Gateway 使用空映射作为“捕获全部”。

限制

  • 在 API 映射中,自定义域名和映射的 API 必须位于同一个 AWS 账户中。

  • API 映射必须仅包含字母、数字和以下字符:$-_.+!*'()/

  • API 映射中路径的最大长度为 300 个字符。

  • 您只能使用 TLS 1.2 安全策略将 HTTP API 映射到区域自定义域名。

  • 您不能将 WebSocket API 映射到与 HTTP API 或 REST API 相同的自定义域名。

创建 API 映射

要创建 API 映射,您必须首先创建自定义域名、API 和阶段。有关使用自定义域名的更多信息,请参阅 在 API Gateway 中设置区域自定义域名

例如,创建所有资源的 AWS Serverless Application Model 模板,请参阅 GitHub 上的使用 SAM 的会话

AWS Management Console

创建 API 映射

  1. 通过以下网址登录到 Amazon API Gateway 控制台:https://console.aws.amazon.com/apigateway

  2. 选择自定义域名

  3. 选择您已经创建的自定义域名。

  4. 选择 API 映射

  5. 选择 Configure API mappings (配置 API 映射)

  6. 选择 Add new mapping (添加新映射)

  7. 输入 API阶段以及可选的路径

  8. 选择 Save

AWS CLI

以下 AWS CLI 命令创建一个 API 映射。在此示例中,API Gateway 将请求发送到 api.example.com/v1/orders,到指定的 API 和阶段。

aws apigatewayv2 create-api-mapping \ --domain-name api.example.com \ --api-mapping-key v1/orders \ --api-id a1b2c3d4 \ --stage test
AWS CloudFormation

以下 AWS CloudFormation 示例创建了一个 API 映射。

MyApiMapping: Type: 'AWS::ApiGatewayV2::ApiMapping' Properties: DomainName: api.example.com.com ApiMappingKey: 'orders/v2/items' ApiId: !Ref MyApi Stage: !Ref MyStage