# 使用 API 映射将 API 阶段连接到 REST API 的自定义域名
<a name="rest-api-mappings"></a>

您可以使用 API 映射将 API 阶段连接到自定义域名。这样可以通过您的自定义域名将流量发送到 API。

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

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

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

## 针对自定义域名的传入请求
<a name="rest-api-mappings-incoming-requests"></a>

当您将自定义域名映射到 API 的某个阶段时，API Gateway 会删除传入的基本路径。这会移除从调用到 API 的映射基本路径。例如，如果基本路径映射是从 `https://api.example.com/orders/shop/5` 到 `test` 阶段，并且您使用了以下请求 `https://api.example.com/orders/shop/5/hats`，则 API Gateway 将调用 API 的 `test` 阶段的 `/hats` 资源，而不是 `orders/shop/5/hats` 资源。

## 映射 API 请求
<a name="rest-api-mappings-evalutation"></a>

以下内容解释 API Gateway 如何评估 API 映射。

可以使用单级映射创建 API 映射，例如从 `orders` 到 API 的 `beta` 阶段的 API 映射，以及从 `shipping` 到 API 的 `alpha` 阶段的 API 映射。对于采用 TLS 1.2 安全策略的区域自定义域名，API Gateway 支持多级 API 映射。可以创建从 `orders/v1/items` 到 API 的 `alpha` 阶段以及从 `orders/v2/items` 到 API 的 `beta` 阶段的 API 映射。当您创建具有多个级别的映射时，API Gateway 将请求发送到匹配路径最长的 API 映射。

可以创建到空路径 `(none)` 的 API 映射。如果没有任何路径与请求匹配，API Gateway 将请求发送到空路径 `(none)`。

在本例中，自定义域名 `https://api.example.com` 具有以下 API 映射。


|  API 映射  |  选定的 API  | 
| --- | --- | 
|  `(none)`  |   API 1   | 
|   `orders`   |   API 2   | 
|  `orders/v1/items`  |   API 3   | 
|  `orders/v2/items`  |   API 4   | 
|  `orders/v1/items/categories`  |   API 5   | 

下表显示了 API Gateway 如何将之前的 API 映射应用于示例请求。


| 请求 | 选定的 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` 不影响选择。请参阅[针对自定义域名的传入请求](#rest-api-mappings-incoming-requests)。  | 
|  `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="rest-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 映射后，您必须创建或更新 DNS 提供商的资源记录以映射到您的 API 端点。
+ 如果您创建具有多个级别的 API 映射，API Gateway 会将所有标头名称转换为小写。

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

要创建 API 映射，您必须首先创建自定义域名、API 和阶段。自定义域名的路由模式必须设置为 `ROUTING_RULE_THEN_API_MAPPING` 或 `API_MAPPING_ONLY`。有关如何设置路由模式的信息，请参阅[为自定义域名设置路由模式](set-routing-mode.md)。

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

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

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

1. 从主导航窗格中选择**自定义域名**。

1. 选择自定义域名。

1. 在**路由详情**选项卡上，选择**配置 API 映射**。

1. 输入映射的 **API**、**阶段**和**路径**。

1. 选择**保存**。

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

使用以下 [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api-mapping.html) 命令创建 API 映射。在此示例中，API Gateway 将请求发送到 `api.example.com/v1/orders`，到指定的 API 和阶段。

**注意**  
要创建具有多个级别的 API 映射，必须使用 `apigatewayv2`。

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

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

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

**注意**  
要创建具有多个级别的 API 映射，必须使用 `AWS::ApiGatewayV2`。

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

------