# API Gateway での HTTP API のカスタムドメイン名
*カスタムドメイン名*は、API ユーザーに提供できる、よりシンプルで直感的な URL です。
API のデプロイ後、お客様 (およびその顧客) は、以下の形式のデフォルトのベース URL を使用して API を呼び出すことができます。
```
https://api-id.execute-api.region.amazonaws.com/stage
```
*api-id* は API Gateway が生成します。*region* は AWS リージョンであり、*stage* は API のデプロイ時にユーザーが指定します。
URL のホスト名の部分 (`api-id.execute-api.region.amazonaws.com`) は、API エンドポイントを参照します。デフォルトの API エンドポイント名は、ランダムに生成され、再呼び出しが難しく、ユーザーフレンドリではありません。
カスタムドメイン名を使用すると、API のホスト名を設定し、代替パスを API にマッピングするための基本パス (`myservice` など) を選択できます。たとえば、API のよりわかりやすい ベース URL は以下のようになります。
```
https://api.example.com/myservice
```
## 考慮事項
以下の考慮事項は、カスタムドメイン名の使用に影響する可能性があります。
+ リージョン別カスタムドメイン名は、REST API や HTTP API に関連付けることができます。API Gateway バージョン 2 の API を使用すると、REST API のリージョン別カスタムドメイン名を作成および管理できます。
+ TLS の最小バージョンでは、TLS 1.2 のみがサポートされます。
+ API エンドポイントにマッピングするために DNS プロバイダーのリソースレコードを作成または更新する必要があります。このマッピングを行わないと、カスタムドメイン名宛ての API リクエストが API Gateway に届きません。
+ ワイルドカード証明書を使用すると、デフォルトのクォータを超えることなく、ほぼ無数のドメイン名をサポートできます。詳細については、「[ワイルドカードカスタムドメイン名](#http-wildcard-custom-domain-names)」を参照してください。
## 前提条件
カスタムドメイン名を作成するための前提条件は、以下のとおりです。
### ドメイン名を登録する
API のカスタムドメイン名を設定するには、登録されたインターネットドメイン名が必要です。インターネットドメインを登録するには、[Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) を使用するか、任意のサードパーティのドメインレジストラを使用できます。カスタムドメイン名は、登録したインターネットドメインのサブドメイン名またはルートドメイン名 ("Zone Apex" とも呼ばれます) にすることができます。
ドメイン名は [RFC 1035](https://tools.ietf.org/html/rfc1035#section-2.3.4) 仕様に準拠している必要があり、ラベルあたり最大 63オクテット、合計 255 オクテットを含めることができます。
### カスタムドメイン名の証明書
API のカスタムドメイン名を設定する前に、ACM で SSL/TLS 証明書を準備する必要があります。カスタムドメイン名を作成する AWS リージョンで ACM を使用できない場合は、そのリージョンの API Gateway に証明書をインポートする必要があります。
SSL/TLS 証明書をインポートするには、カスタムドメイン名の PEM 形式の SSL/TLS 認証本文、そのプライベートキー、およびカスタムドメイン名の証明書チェーンを提供する必要があります。
ACM に保存された各証明書は ARN によって識別されます。ACM 発行の証明書により、プライベートキーなど証明書の機密の詳細が漏れる心配はありません。AWS で管理された証明書をドメイン名で使用するには、その ARN を単に参照します。
アプリケーションで証明書ピンニング (SSL ピンニングとも呼ばれる) を使用して ACM 証明書を固定すると、AWS が証明書を更新した後にアプリケーションがドメインに接続できないことがあります。詳細については、「*AWS Certificate Manager ユーザーガイド*」の「[証明書のピンニングの問題](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-pinning.html)」を参照してください。
## ワイルドカードカスタムドメイン名
ワイルドカードカスタムドメイン名を使用すると、[デフォルトのクォータ](limits.md)を超えずにほぼ無数のドメイン名をサポートできます。たとえば、各お客様に個別のドメイン名を付けることができます `customername.api.example.com`。
ワイルドカードカスタムドメイン名を制作するためには、ルートドメインの可能なすべてのサブドメインを表すカスタムドメインの最初のサブドメインとして、ワイルドカード (`*`) を指定します。
たとえば、ワイルドカードカスタムドメイン名として `*.example.com` を使用すると、`a.example.com`、`b.example.com`、`c.example.com` などのサブドメインが生成され、これらはすべて同じドメインにルーティングされます。
ワイルドカードカスタムドメイン名は、API Gateway の標準のカスタムドメイン名とは異なる設定をサポートします。たとえば、1 つの AWS アカウントで、`*.example.com` と `a.example.com` を異なる動作に設定できます。
ワイルドカードカスタムドメイン名を作成するには、DNS または E メール検証方法を使用して検証された証明書を ACM から発行してもらう必要があります。
**注記**
別の AWS アカウントで作成済みのカスタムドメイン名と競合するようなワイルドカードカスタムドメイン名を作成することはできません。たとえば、アカウント A で `a.example.com` が作成済みである場合、アカウント B はワイルドカードカスタムドメイン名として `*.example.com` を作成できません。
アカウント A とアカウント B の所有者が同じである場合は、[AWS サポートセンター](https://console.aws.amazon.com/support/home#/)に連絡して例外をリクエストできます。
## カスタムドメイン名に関する次のステップ
HTTP API のカスタムドメイン名を設定するには、「API Gateway 開発者ガイド」の「REST API」セクションの説明に従います。
まず、カスタムドメイン名の証明書を指定します。詳細については、「[AWS Certificate Manager で証明書を準備する](how-to-specify-certificate-for-custom-domain-name.md)」を参照してください。次に、リージョン別カスタムドメイン名を作成します。詳細については、「[API Gateway でリージョン別カスタムドメイン名を設定する](apigateway-regional-api-custom-domain-create.md)」を参照してください。
# API ステージを HTTP API のカスタムドメイン名にマッピングする
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 リクエストのルーティング
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` を選択します。 |
## 制限事項
+ 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 マッピングを作成する
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
```
------
# HTTP API のデフォルトのエンドポイントを無効にする
デフォルトでは、クライアントは、API Gateway が API 用に生成する `execute-api` エンドポイントを使用して API を呼び出すことができます。クライアントがカスタムドメイン名を使用した場合のみ API にアクセスできるようにするには、デフォルトの `execute-api` エンドポイントを無効にします。デフォルトのエンドポイントを無効にすると、API のすべてのステージに影響します。
次の手順では、HTTP API のデフォルトのエンドポイントを無効にする方法を示します。
------
#### [ AWS マネジメントコンソール ]
1. API Gateway コンソール ([https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)) にサインインします。
1. HTTP API を選択します。
1. API の ID を選択して、**[API の詳細]** ページを開きます。
1. **[API の詳細]** で、**[編集]** を選択します。
1. **[デフォルトのエンドポイント]** で、**[無効化]** を選択します。
1. **[保存]** を選択します。
ステージの自動デプロイを有効にすると、変更を有効にするために API を再デプロイする必要はありません。それ以外の場合は、API を再デプロイする必要があります。
1. (オプション) **[デプロイ]** を選択して API を再デプロイするか、新しいステージを作成して変更を有効にします。
------
#### [ AWS CLI ]
次の [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) コマンドは、HTTP API のデフォルトエンドポイントを無効にします。
```
aws apigatewayv2 update-api \
--api-id abcdef123 \
--disable-execute-api-endpoint
```
デフォルトエンドポイントを無効にした後は、自動デプロイが有効になっている場合を除き、その変更を有効にするために API をデプロイする必要があります。
次の [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-deployment.html) コマンドでは、デプロイを作成します。
```
aws apigatewayv2 create-deployment \
--api-id abcdef123 \
--stage-name dev
```
------
# HTTP API のカスタムドメイン名の IP アドレスタイプ
API を作成する場合、ドメイン を呼び出すことができる IP アドレスのタイプを指定します。IPv4 を選択すると、IPv4 アドレスを解決してドメインを呼び出すことができます。デュアルスタックを選択すると、IPv4 アドレスと IPv6 アドレスの両方を指定してドメインを呼び出すことができます。IP アドレスタイプをデュアルスタックに設定して、IP スペースの枯渇の問題を軽減したり、セキュリティ体制を強化したりすることをお勧めします。デュアルスタック IP アドレスタイプの利点の詳細については、「[IPv6 on AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html)」を参照してください。
## IP アドレスタイプに関する考慮事項
以下の考慮事項は、IP アドレスタイプの使用に影響する可能性があります。
+ API Gateway カスタムドメイン名のデフォルトの IP アドレスタイプは IPv4 です。
+ カスタムドメイン名には、マッピングされたすべての API で同じ IP アドレスタイプを使用する必要はありません。デフォルトの API エンドポイントを無効にすると、発信者が API を呼び出す方法が影響を受ける可能性があります。
## カスタムドメイン名の IP アドレスタイプを変更する
IP アドレスタイプは、ドメインのエンドポイント設定を更新して、変更できます。ドメインのエンドポイント設定は、AWS マネジメントコンソール、AWS CLI、CloudFormation、または AWS SDK を使用して、更新できます。
------
#### [ AWS マネジメントコンソール ]
**カスタムドメイン名の IP アドレスタイプを変更するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. パブリックカスタムドメイン名を選択します。
1. **[エンドポイント設定]** を選択します。
1. [IP アドレスタイプ] で、**[IPv4]** または **[デュアルスタック]** を選択します。
1. **[保存]** を選択します。
------
#### [ AWS CLI ]
次の [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) コマンドは、IP アドレスタイプがデュアルスタックになるように API を更新します。
```
aws apigatewayv2 update-domain-name \
--domain-name dualstack.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc,IpAddressType=dualstack
```
出力は次のようになります。
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "dualstack.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z3LQWSYCGH4ADY",
"SecurityPolicy": "TLS_1_2",
"IpAddressType": "dualstack"
}
],
"Tags": {}
}
```
------