# API マッピングを使用して、API ステージを REST API のカスタムドメイン名に接続します。
<a name="rest-api-mappings"></a>

API マッピングを使用して、API ステージをカスタムドメイン名に接続します。これにより、API へのトラフィックがカスタムドメイン名を経由して送信されます。

API マッピングは、API、ステージ、およびオプションでマッピングに使用するパスを指定します。例えば、`https://api.example.com/orders` を API の `production` ステージにマッピングできます。

HTTP API と 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 は `orders/shop/5/hats` リソースではなく API の `test` ステージの `/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 マッピングにリクエストを送信します。

空のパス `(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 は、最も長い一致パスを持つ API マッピングを選択します。リクエストの最後にある `123` は、選択には影響しません。「[カスタムドメイン名への受信リクエスト](#rest-api-mappings-incoming-requests)」を参照してください。  | 
|  `https://api.example.com/orders/v2/items/categories/5`  |  API 5  |  API Gateway は、最も長い一致パスを持つ API マッピングを選択します。  | 
|  `https://api.example.com/customers`  |  API 1  |  API Gateway は、空のマッピングをキャッチオールとして使用します。  | 
|  `https://api.example.com/ordersandmore`  |  API 2  |  API Gateway は、一致するプレフィックスが最も長い API マッピングを選択します。 単一レベルのマッピングで設定されたカスタムドメイン名の場合 (`https://api.example.com/orders` と`https://api.example.com/` のみなど)、API ゲートウェイは、`ordersandmore` と一致するパスがないため、`API 1` を選択します。  | 

## 制限事項
<a name="rest-api-mappings-restrictions"></a>
+ API マッピングでは、カスタムドメイン名とマップされた API が同じ AWS アカウントにある必要があります。
+ API マッピングに含めることができるのは、文字、数字、および `$-_.+!*'()/` の文字だけです。
+ API マッピングのパスの最大文字数は 300 文字です。
+ ドメイン名ごとに、複数のレベルで 200 個の API マッピングを設定できます。この制限には、`/prod` などの単一レベルの API マッピングは含まれません。
+ 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 で「[Sessions With SAM](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains)」を参照してください。

------
#### [ AWS マネジメントコンソール ]

1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。

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 およびステージに `api.example.com/v1/orders` に対するリクエストを送信します。

**注記**  
複数のレベルで 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
```

------