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

# 使用 API 映射將 API 階段連線至 REST APIs 的自訂網域名稱
<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 映射。您可以從 建立 API 映射`orders/v1/items`至 API 的 `alpha`階段，以及 `orders/v2/items` API 的 `beta`階段。當您建立具有多個層級的映射時，API Gateway 會將請求傳送至具有最長相符路徑的 API 映射。

您可以建立對空白路徑 的 API 映射`(none)`。如果沒有路徑符合請求，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 映射中，自訂網域名稱和映射APIs 必須在相同的 AWS 帳戶中。
+ API 映射只能包含字母、數字和下列字元：`$-_.+!*'()/`。
+ API 映射中路徑的最大長度為 300 個字元。
+ 您可以為每個域名設定具有 200 個具多個層級的 API 映射。此限制不包含具有單一層級的 API 映射，例如 `/prod`。
+ 您只能將 HTTP API 映射至具有 TLS 1.2 安全政策的區域自訂網域名稱。
+ 您無法將 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. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。

1. 從主要導覽窗格中，選擇 **Custom Domain Names (自訂網域名稱)**。

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

------