本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 將 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 Gateway 只會考慮為 API 映射而非 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`。
+ 您只能將 HTTP API 映射至具有 TLS 1.2 安全政策的區域自訂網域名稱。
+ 您無法將 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. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。

1. 選擇 **Custom domain names** (自訂網域名稱)。

1. 選取您已建立的自訂網域名稱。

1. 選擇 **API mappings** (API 映射)。

1. 選擇 **Configure API mappings (設定 API 映射)**。

1. 選擇 **Add new mapping (新增映射)**。

1. 輸入 **API**、**Stage** (階段)，以及選擇性地輸入 **Path** (路徑)。

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
```

------