# API ステージを HTTP API のカスタムドメイン名にマッピングする
<a name="http-api-mappings"></a>

API マッピングを使用して、API ステージをカスタムドメイン名に接続します。ドメイン名を作成し、DNS レコードを設定したら、API マッピングを使用して、カスタムドメイン名を使用して API にトラフィックを送信します。

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

HTTP API と 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. API 1 にマッピングされている `(none)`。

1. API 2 にマッピングされている `orders`。

1. API 3 にマッピングされている `orders/v1/items`。

1. API 4 にマッピングされている `orders/v2/items`。

1. API 5 にマッピングされている `orders/v2/items/categories`。


| リクエスト | 選択した 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` は、選択には影響しません。  | 
|  `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="http-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 マッピングを作成する場合、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 で「[Sessions With 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. [**カスタムドメイン名**] を選択します。

1. 既に作成したカスタムドメイン名を選択します。

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

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

------