# 将 API 阶段映射到 HTTP API 的自定义域名
<a name="http-api-mappings"></a>

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

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

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

在创建 API 映射之前，您必须拥有 API、阶段和自定义域名。要了解有关创建自定义域名的更多信息，请参阅 [在 API Gateway 中设置区域自定义域名](apigateway-regional-api-custom-domain-create.md)。

## 路由 API 请求
<a name="http-api-mappings-evalutation"></a>

您可以使用多个级别配置 API 映射，例如 `orders/v1/items` 和 `orders/v2/items`。

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

对于使用具有多个级别的 API 映射的自定义域名，API Gateway 将请求路由到匹配前缀最长的 API 映射。

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

1. `(none)` 映射到 API 1。

1. `orders` 映射到 API 2。

1. `orders/v1/items` 映射到 API 3。

1. `orders/v2/items` 映射到 API 4。

1. `orders/v2/items/categories` 映射到 API 5。


| 请求 | 选定的 API | 说明 | 
| --- | --- | --- | 
|  `https://api.example.com/orders`  |  `API 2`  |  请求完全匹配此 API 映射。  | 
|  `https://api.example.com/orders/v1/items`  |  `API 3`  |  请求完全匹配此 API 映射。  | 
|  `https://api.example.com/orders/v2/items`  |  `API 4`  |  请求完全匹配此 API 映射。  | 
|  `https://api.example.com/orders/v1/items/123`  |  `API 3`  |  API Gateway 选择匹配路径最长的映射。请求结尾处的 `123` 不影响选择。  | 
|  `https://api.example.com/orders/v2/items/categories/5`  |  `API 5`  |  API Gateway 选择匹配路径最长的映射。  | 
|  `https://api.example.com/customers`  |  `API 1`  |  API Gateway 使用空映射作为“捕获全部”。  | 
|  `https://api.example.com/ordersandmore`  |  `API 2`  |  API Gateway 选择匹配前缀最长的映射。 对于配置了单级映射的自定义域名（例如，仅 `https://api.example.com/orders` 和 `https://api.example.com/`），API Gateway 会选择 `API 1`，因为没有与 `ordersandmore` 匹配的路径。  | 

## 限制
<a name="http-api-mappings-restrictions"></a>
+ 在 API 映射中，自定义域名和映射的 API 必须位于同一个AWS账户中。
+ API 映射必须仅包含字母、数字和以下字符：`$-_.+!*'()/`。
+ API 映射中路径的最大长度为 300 个字符。
+ 每个域名可以有 200 个具有多个级别的 API 映射。此限制不包括单级的 API 映射，例如 `/prod`。
+ 您只能使用 TLS 1.2 安全策略将 HTTP API 映射到区域自定义域名。
+ 您不能将 WebSocket API 映射到与 HTTP API 或 REST API 相同的自定义域名。
+ 如果您创建具有多个级别的 API 映射，API Gateway 会将所有标头名称转换为小写。

## 创建 API 映射
<a name="http-api-mappings-examples"></a>

要创建 API 映射，您必须首先创建自定义域名、API 和阶段。有关使用自定义域名的更多信息，请参阅 [在 API Gateway 中设置区域自定义域名](apigateway-regional-api-custom-domain-create.md)。

例如，创建所有资源的 AWS Serverless Application Model 模板，请参阅 GitHub 上的[使用 SAM 的会话](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains)。

------
#### [ AWS 管理控制台 ]

**创建 API 映射**

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

1. 选择**自定义域名**。

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

1. 选择 **API 映射**。

1. 选择 **Configure API mappings (配置 API 映射)**。

1. 选择 **Add new mapping (添加新映射)**。

1. 输入 **API**、**阶段**以及可选的**路径**。

1. 选择**保存**。

------
#### [ AWS CLI ]

使用以下 [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) 命令创建 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
```

------
#### [ CloudFormation ]

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

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

------