# API Gateway でのパブリック REST 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
```
**注記**
プライベート API のカスタムドメイン名の詳細については、「[API Gateway でのプライベート API のカスタムドメイン名](apigateway-private-custom-domains.md)」を参照してください。
## 考慮事項
以下の考慮事項は、カスタムドメイン名の使用に影響する可能性があります。
+ API のデフォルトのエンドポイントを無効にすることができます。クライアントは引き続きデフォルトのエンドポイントに接続できますが、`403 Forbidden` ステータスコードを受け取ります。
+ リージョン別カスタムドメイン名は、REST API や HTTP API に関連付けることができます。[API Gateway バージョン 2 の API](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/api-reference.html) を使用すると、REST API のリージョン別カスタムドメイン名を作成および管理できます。
+ カスタムドメイン名は、すべての AWS アカウントにおいてリージョン内で一意である必要があります。
+ カスタムドメイン名をエッジ最適化エンドポイントとリージョンエンドポイントの間で移行することはできますが、パブリックカスタムドメイン名をプライベートカスタムドメイン名に移行することはできません。
+ API エンドポイントにマッピングするために DNS プロバイダーのリソースレコードを作成または更新する必要があります。このマッピングを行わないと、カスタムドメイン名宛ての API リクエストが API Gateway に届きません。
+ ワイルドカード証明書を使用すると、デフォルトのクォータを超えることなく、ほぼ無数のドメイン名をサポートできます。詳細については、「[ワイルドカードカスタムドメイン名](#wildcard-custom-domain-names)」を参照してください。
+ カスタムドメイン名のセキュリティポリシーを選択できます。詳細については、「[API Gateway でカスタムドメインのセキュリティポリシーを選択する](apigateway-custom-domain-tls-version.md)」を参照してください。
+ 複数のレベルで API マッピングを設定するには、リージョン別カスタムドメイン名と TLS 1.2 セキュリティポリシーを使用する必要があります。
## カスタムドメイン名の前提条件
パブリックまたはプライベートカスタムドメイン名を作成するには、次のような前提条件があります。プライベート API のカスタムドメイン名の詳細については、「[API Gateway でのプライベート API のカスタムドメイン名](apigateway-private-custom-domains.md)」を参照してください。
### ドメイン名を登録する
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.example.com`。
ワイルドカードカスタムドメイン名を制作するためには、ルートドメインの可能なすべてのサブドメインを表すカスタムドメインの最初のサブドメインとして、ワイルドカード (`*`) を指定します。
たとえば、ワイルドカードカスタムドメイン名として `*.example.com` を使用すると、`a.example.com`、`b.example.com`、`c.example.com` などのサブドメインが生成されます。ワイルドカードカスタムドメイン名を作成すると、そのすべてのサブドメインはワイルドカードドメイン名のルーティングモードによってルーティングされます。サブドメインを異なる API にルーティングするには、次のいずれかを実行します。
+ ルーティングルールを使用し、`Host` ヘッダーを使用して `*.example.com` への受信リクエストを異なるターゲット REST API にルーティングします。詳細については、「[例 4: ワイルドカードドメイン名のルーティングルール](rest-api-routing-rules-examples.md#rest-api-routing-rules-examples-rule-for-wildcard-domains)」を参照してください。
+ 異なるエンドポイントにルーティングするサブドメインのドメイン名を作成します。1 つの AWS アカウントで、`*.example.com` と `a.example.com` の両方を持つことができます。
コンテキスト変数 `$context.domainName` と `$context.domainPrefix` コンテキスト変数を使用して、クライアントが API を呼び出すために使用したドメイン名を判断できます。コンテキスト変数の詳細については、「[API Gateway のデータ変換の変数](api-gateway-mapping-template-reference.md)」を参照してください。
ワイルドカードカスタムドメイン名を作成するには、DNS または E メール検証方法を使用して検証された証明書を ACM から発行してもらう必要があります。
**注記**
別の AWS アカウントで作成済みのカスタムドメイン名と競合するようなワイルドカードカスタムドメイン名を作成することはできません。たとえば、アカウント A で `a.example.com` が作成済みである場合、アカウント B はワイルドカードカスタムドメイン名として `*.example.com` を作成できません。
アカウント A とアカウント B の所有者が同じである場合は、[AWS サポートセンター](https://console.aws.amazon.com/support/home#/)に連絡して例外をリクエストできます。
## カスタムドメイン名に関する次のステップ
カスタムドメイン名に関する次のステップは、以下のとおりです。
**次のステップ**
+ SSL/TLS 証明書を設定する方法については、「[AWS Certificate Manager で証明書を準備する](how-to-specify-certificate-for-custom-domain-name.md)」を参照してください。
+ リージョン別カスタムドメイン名の作成方法については、「[API Gateway でリージョン別カスタムドメイン名を設定する](apigateway-regional-api-custom-domain-create.md)」を参照してください。
+ エッジ最適化カスタムドメイン名を作成する方法については、「[API Gateway でエッジ最適化カスタムドメイン名を設定する](how-to-edge-optimized-custom-domain-name.md)」を参照してください。
+ リージョン別カスタムドメイン名とエッジ最適化カスタムドメイン名の間での移行方法については、「[API Gateway でカスタムドメイン名を別の API エンドポイントタイプに移行する](apigateway-regional-api-custom-domain-migrate.md)」を参照してください。
+ API ステージをカスタムドメイン名に接続する方法については、「[API Gateway のカスタムドメイン名を使用して API にトラフィックを送信します。](rest-api-routing-mode.md)」を参照してください。
+ カスタムドメイン名のセキュリティポリシーを選択する方法については、「[API Gateway でカスタムドメインのセキュリティポリシーを選択する](apigateway-custom-domain-tls-version.md)」を参照してください。
+ カスタムドメイン名のデフォルトエンドポイントを無効にする方法については、「[REST API のデフォルトのエンドポイントを無効にする](rest-api-disable-default-endpoint.md)」を参照してください。
+ Route 53 のヘルスチェックを使用して API Gateway API からの DNS フェイルオーバーを制御する方法については、「[API Gateway API の DNS フェイルオーバーのカスタムヘルスチェックの設定](dns-failover.md)」を参照してください。
カスタムドメイン名を初めて作成する場合は、「[AWS Certificate Manager で証明書を準備する](how-to-specify-certificate-for-custom-domain-name.md)」から始めて、証明書を指定し、次に「[API Gateway でリージョン別カスタムドメイン名を設定する](apigateway-regional-api-custom-domain-create.md)」に従ってリージョン別カスタムドメイン名を作成することをお勧めします。
# AWS Certificate Manager で証明書を準備する
API のカスタムドメイン名を設定する前に、AWS Certificate Managerで SSL/TLS 証明書を準備する必要があります。詳細については、[AWS Certificate Managerユーザーガイド](https://docs.aws.amazon.com/acm/latest/userguide/)を参照してください。
## 考慮事項
SSL/TLS 証明書に関する考慮事項は、以下のとおりです。
+ エッジ最適化カスタムドメイン名を作成すると、API Gateway は CloudFront を活用してカスタムドメイン名の証明書をサポートします。そのため、カスタムドメイン名の SSL/TLS 証明書の要件と制約は [CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-values-specify.html) によって指定されます。たとえば、パブリックキーの最大サイズは 2048 で、プライベートキーのサイズは 1024、2048、または 4096 とすることができます。パブリックキーのサイズは、使用している認証機関によって決まります。デフォルトの長さと異なるサイズのキーを返すよう認証機関に依頼します。詳細については、「[オブジェクトへのセキュアなアクセス](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-https.html)」および「[署名付き URL と署名付き Cookie](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-trusted-signers.html)」を参照してください。
+ リージョン別カスタムドメイン名を作成する場合、パブリックキーの最大サイズは 2048 です。
+ リージョン別カスタムドメイン名で ACM 証明書を使用するには、API と同じリージョンで証明書をリクエストまたはインポートする必要があります。証明書はカスタムドメイン名を対象としている必要があります。
+ エッジ最適化カスタムドメイン名で ACM 証明書を使用するには、米国東部 (バージニア北部) – `us-east-1` リージョンで証明書をリクエストまたはインポートする必要があります。
+ `example.com` などの登録済みドメイン名が必要です。[Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) または認定されているサードパーティーのドメインレジストラを使用できます。そのようなレジストラの一覧については、ICANN のウェブサイトの[認定レジストラディレクトリ](https://www.icann.org/en/accredited-registrars)を参照してください。
## SSL/TLS 証明書を作成または ACM にインポートするには
次の手順は、ドメイン名の SSL/TLS 証明書を作成またはインポートする方法を示しています。
------
#### [ To request a certificate provided by ACM for a domain name ]
1. [AWS Certificate Manager コンソール](https://console.aws.amazon.com/acm)にサインインします。
1. [**証明書のリクエスト**] を選択します。
1. **[証明書タイプ]** で、**[パブリック証明書をリクエスト]** を選択します。
1. [**次へ**] を選択します。
1. **[完全修飾ドメイン名]** に、API のカスタムドメイン名 (`api.example.com` など) を入力します。
1. 必要に応じて、[**この証明書に別の名前を追加**] を選択します。
1. **[検証方法]** で、ドメインの所有権を検証する方法を選択します。
1. **[キーアルゴリズム]** で、暗号化アルゴリズムを選択します。
1. **[リクエスト]** を選択します。
1. リクエストが有効であるためには、ACM が証明書を発行する前に、インターネットドメインの登録された所有者がリクエストに同意する必要があります。Route 53 を使用してパブリック DNS レコードを管理する場合は、ACM コンソールでレコードを直接更新できます。
------
#### [ To import into ACM a certificate for a domain name ]
1. 証明機関からカスタムドメイン名の PEM エンコード SSL/TLS 証明書を取得します。このような CA のリストの一部については、「[Mozilla の Included CA List](https://ccadb.my.salesforce-sites.com/mozilla/IncludedCACertificateReport)」を参照してください。
1. 証明書のプライベートキーを生成し、OpenSSL ウェブサイトの [OpenSSL](https://www.openssl.org) ツールキットを使用して出力をファイルに保存します。
```
openssl genrsa -out private-key-file 2048
```
1. OpenSSL を使用して、以前に作成されたプライベートキーで証明書署名リクエスト (CSR) を生成します。
```
openssl req -new -sha256 -key private-key-file -out CSR-file
```
1. CSR を認証機関に送信し、結果として生じる証明書を保存します。
1. 認証機関から証明書チェーンをダウンロードします。
**注記**
別の方法でプライベートキーを取得し、キーが暗号化されている場合は、次のコマンドを使用してキーを復号してから、カスタムドメイン名を設定するためにキーを API Gateway に送信できます。
```
openssl pkcs8 -topk8 -inform pem -in MyEncryptedKey.pem -outform pem -nocrypt -out MyDecryptedKey.pem
```
1. 証明書を AWS Certificate Manager へアップロードします
1. [AWS Certificate Manager コンソール](https://console.aws.amazon.com/acm)にサインインします。
1. [**Import a certificate**] を選択します。
1. **[証明書本文]** に、証明機関からの PEM 形式のサーバー証明書の本文を入力します。このような証明書の省略された例を次に示します。
```
-----BEGIN CERTIFICATE-----
EXAMPLECA+KgAwIBAgIQJ1XxJ8Pl++gOfQtj0IBoqDANBgkqhkiG9w0BAQUFADBB
...
az8Cg1aicxLBQ7EaWIhhgEXAMPLE
-----END CERTIFICATE-----
```
1. **[証明書のプライベートキー]** に、PEM 形式の証明書のプライベートキーを入力します。このようなキーの省略された例を次に示します。
```
-----BEGIN RSA PRIVATE KEY-----
EXAMPLEBAAKCAQEA2Qb3LDHD7StY7Wj6U2/opV6Xu37qUCCkeDWhwpZMYJ9/nETO
...
1qGvJ3u04vdnzaYN5WoyN5LFckrlA71+CszD1CGSqbVDWEXAMPLE
-----END RSA PRIVATE KEY-----
```
1. **[証明書チェーン]** に、PEM 形式の中間証明書を (必要に応じてルート証明書も) 空白行なしに連続して入力します。ルート証明書を含める場合は、証明書チェーンの先頭は中間証明書で、末尾がルート証明書である必要があります。証明機関によって提供された中間証明書を使用します。信頼パスのチェーン内に存在しない中間証明書は含めないでください。次の例で省略された例を示します。
```
-----BEGIN CERTIFICATE-----
EXAMPLECA4ugAwIBAgIQWrYdrB5NogYUx1U9Pamy3DANBgkqhkiG9w0BAQUFADCB
...
8/ifBlIK3se2e4/hEfcEejX/arxbx1BJCHBvlEPNnsdw8EXAMPLE
-----END CERTIFICATE-----
```
別の例を示します。
```
-----BEGIN CERTIFICATE-----
Intermediate certificate 2
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Intermediate certificate 1
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Optional: Root certificate
-----END CERTIFICATE-----
```
1. **[次へ]** を選択し、さらに **[次へ]** を選択します。
------
証明書が正常に作成またはインポートされた後、証明書の ARN をメモします。カスタムドメイン名を設定する際に必要になります。
# API Gateway でリージョン別カスタムドメイン名を設定する
リージョン別カスタムドメイン名を使用して、ユーザーフレンドリーな API ベース URL を作成します。リージョン別カスタムドメイン名を使用すると、HTTP API と REST API のステージを同じカスタムドメイン名にマッピングして相互 TLS 認証を使用できます。
## 考慮事項
リージョン別カスタムドメイン名に関する考慮事項は、以下のとおりです。
+ リージョン固有の ACM 証明書を指定する必要があります。この証明書は API と同じリージョンに存在する必要があります。カスタムドメイン名の証明書を作成またはアップロードする方法の詳細については、「[AWS Certificate Manager で証明書を準備する](how-to-specify-certificate-for-custom-domain-name.md)」を参照してください。
+ ACM 証明書を使用してリージョン別カスタムドメイン名を作成 (または移行) すると、API Gateway はサービスにリンクされたロールをアカウント内に作成します。サービスにリンクされたロールは、ACM 証明書をリージョン別エンドポイントにアタッチするのに必要です。ロールの名前は **AWSServiceRoleForAPIGateway** です。また、管理ポリシーの **APIGatewayServiceRolePolicy** がアタッチされます。サービスにリンクされたロールの詳細な使用方法については、「[サービスにリンクされたロールの使用](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html)」を参照してください。
+ リージョン別カスタムドメイン名の作成後、カスタムドメイン名をリージョン別ドメインに関連付ける DNS レコードを作成する必要があります。これにより、カスタムドメイン名にバインドされるトラフィックが、API のリージョン別ホスト名にルーティングされます。
DNS レコードには、CNAME または A エイリアスレコードを使用できます。Route 53 を DNS プロバイダーとして使用する場合は、A エイリアスレコードを作成します。サードパーティーの DNS プロバイダーを使用する場合は、CNAME レコードを使用します。CNAME レコードを使用し、プライベート API に対してプライベート DNS を有効にした API Gateway インターフェイス VPC エンドポイントを作成した場合、プライベート API をホストしている VPC 内でカスタムドメイン名を解決できなくなります。
## リージョン別カスタムドメイン名を作成する
次の手順では、リージョン別カスタムドメイン名を作成する方法を示します。この手順を完了したら、API のステージをカスタムドメイン名にルーティングするためのルーティングルールを作成します。
------
#### [ AWS マネジメントコンソール ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. メインのナビゲーションペインから [**Custom Domain Names (カスタムドメイン名)**] を選択します。
1. [**Create**] を選択します。
1. [**Domain name (ドメイン名)**] には、ドメイン名を入力します。
1. **[ルーティングモード]** では、**[ルーティングルールのみ]** を選択します。
このルーティングモードでは、ルーティングルールを使用して、カスタムドメイン名から API にのみトラフィックを送信できます。詳細については、「[API Gateway のカスタムドメイン名を使用して API にトラフィックを送信します。](rest-api-routing-mode.md)」を参照してください。
1. **[TLS の最小バージョン]** で、バージョンを選択します。
1. [**エンドポイント設定**] で、[**API エンドポイントタイプ**] として [**リージョン**] を選択します。
1. ACM 証明書を選択します。証明書は API と同じリージョンに存在する必要があります。
1. **[作成]** を選択します。
------
#### [ AWS CLI ]
次の [create-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-domain-name.html) コマンドは、カスタムドメイン名を作成します。
```
aws apigatewayv2 create-domain-name \
--domain-name 'regional.example.com' \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--routing-mode ROUTING_RULE_ONLY
```
出力は次のようになります。
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "regional.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-numh1z56v6.execute-api.us-west-2.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z2OJLYMUO9EFXC",
"SecurityPolicy": "TLS_1_2"
}
"RoutingMode": "ROUTING_RULE_ONLY"
]
}
```
`DomainNameConfigurations` プロパティ値は、リージョン別 API のホスト名を返します。DNS レコードを作成し、カスタムドメイン名をこのリージョン別ドメイン名にポイントする必要があります。これにより、カスタムドメイン名にバインドされるトラフィックが、このリージョン別 API のホスト名にルーティングされます。
------
## リージョン別カスタムドメイン名のルーティングルールを作成する
カスタムドメイン名を作成したら、カスタムドメイン名から API へのトラフィックのルーティング方法を設定します。ルーティングモードを `ROUTING_RULE_ONLY` に設定しているため、ルーティングルールを使用して、カスタムドメイン名への受信リクエストを API にルーティングします。
この例では、すべての受信リクエストをカスタムドメイン名にルーティングするキャッチオールルールを API の 1 つのステージに作成します。異なるヘッダーとパスの条件に基づいてルーティングルールを設定することもできます。詳細については、「[API ステージを REST API のカスタムドメイン名に接続するためのルーティングルール](rest-api-routing-rules.md)」を参照してください。
------
#### [ AWS マネジメントコンソール ]
1. API Gateway コンソール ([https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)) にサインインします。
1. カスタムドメイン名を選択します。
1. **[ルーティングの詳細]** タブで、**[ルーティングルールを追加]** を選択します。
1. **[新しい条件を追加]** を選択して、新しい条件を追加します。
1. このルールを条件なしで保持します。これにより、カスタムドメイン名へのすべてのリクエストがターゲット API とターゲットステージにルーティングされます。
1. **[アクション]** では、ドロップダウンを使用してターゲット API とターゲットステージを選択します。
1. [**次へ**] を選択します。
1. 優先度フィールドに、**100** と入力します。
API Gateway は最小値から最大値までの優先順位でルールを評価します。これはキャッチオールルールであるため、API Gateway が最初に作成した追加のルールを照合できるように、高い優先度を使用します。
1. **[ルーティングルールを作成]** を選択します。
------
#### [ AWS CLI ]
次の `create-routing-rule` コマンドは、キャッチオールルーティングルールを作成します。
```
aws apigatewayv2 create-routing-rule \
--domain-name 'regional.example.com' \
--priority 100 \
--conditions \
--actions '[{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod"
}
}]'
```
------
ルーティングモードはいつでも変更でき、新しいルールを作成できます。詳細については、「[API Gateway のカスタムドメイン名を使用して API にトラフィックを送信します。](rest-api-routing-mode.md)」を参照してください。
## リージョン別カスタムドメイン名の DNS レコードを作成する
カスタムドメイン名を作成し、ベースパスマッピングを作成した後、カスタムドメイン名を新しく作成したリージョン別ドメイン名に関連付ける DNS レコードを作成します。
------
#### [ AWS マネジメントコンソール ]
AWS マネジメントコンソールを使用するには、Route 53 のドキュメントで「[トラフィックを API Gateway にルーティングするように Route 53 を設定する](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html)」を参照してください。
------
#### [ AWS CLI ]
リージョン別カスタムドメイン名を特定のホストゾーン ID のホスト名にマッピングするように DNS レコードを設定するには、まずリージョン別ドメイン名の DNS レコードをセットアップするための設定を含む JSON ファイルを作成します。
次の `setup-dns-record.json` は、カスタムドメイン名の作成の一環としてプロビジョニングしたリージョン別ホスト名 (`d-numh1z56v6.execute-api.us-west-2.amazonaws.com`) にリージョン別カスタムドメイン名 (`regional.example.com`) をマッピングするための DNS レコードの作成方法を示しています。`DNSName` の `HostedZoneId` プロパティと `AliasTarget` プロパティは、カスタムドメイン名の `regionalDomainName` と `regionalHostedZoneId` の値をそれぞれ示しています。また、リージョン別 Route 53 ホストゾーン ID は、「[Amazon API Gateway エンドポイントとクォータ](https://docs.aws.amazon.com/general/latest/gr/apigateway.html)」でも取得できます。
```
{
"Changes": [
{
"Action": "CREATE",
"ResourceRecordSet": {
"Name": "regional.example.com",
"Type": "A",
"AliasTarget": {
"DNSName": "d-numh1z56v6.execute-api.us-west-2.amazonaws.com",
"HostedZoneId": "Z2OJLYMUO9EFXC",
"EvaluateTargetHealth": false
}
}
}
]
}
```
次の [change-resource-record-sets](https://docs.aws.amazon.com/cli/latest/reference/route53/change-resource-record-sets.html) は、リージョン別カスタムドメイン名の DNS レコードを作成します。
```
aws route53 change-resource-record-sets \
--hosted-zone-id Z2OJLYMUO9EFXC \
--change-batch file://path/to/your/setup-dns-record.json
```
`hosted-zone-id` は、アカウントに設定した DNS レコードの Route 53 ホストゾーン ID に置き換えます。`change-batch` パラメータ値は、フォルダ (*path/to/your*) 内の JSON ファイル (*setup-dns-record.json*) を指しています。
------
# API Gateway でエッジ最適化カスタムドメイン名を設定する
エッジ最適化 API のカスタムドメイン名を作成すると、API Gateway は、CloudFront ディストリビューションと DNS レコードを設定して API ドメイン名を CloudFront ディストリビューションドメイン名にマッピングします。API のリクエストは、マッピングされた CloudFront ディストリビューションを介して API Gateway にルーティングされます。このマッピングは、カスタムドメイン名宛ての API リクエストに使用され、そのリクエストは、マッピング先の CloudFront ディストリビューションを介して API Gateway にルーティングされます。
## 考慮事項
エッジ最適化カスタムドメイン名に関する考慮事項は、以下のとおりです。
+ エッジ最適化のカスタムドメイン名を設定したり、その証明書を更新したりするには、CloudFront ディストリビューションを更新するためのアクセス許可が必要です。
CloudFront ディストリビューションを更新するには、以下のアクセス許可が必要です。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowCloudFrontUpdateDistribution",
"Effect": "Allow",
"Action": [
"cloudfront:updateDistribution"
],
"Resource": [
"*"
]
}
]
}
```
------
+ エッジ最適化カスタムドメイン名の証明書は、米国東部 (バージニア北部) – `us-east-1` リージョンでリクエストまたはインポートする必要があります。
+ API Gateway によって作成された CloudFront ディストリビューションは、API Gateway と提携しているリージョン固有のアカウントによって所有されています。このような CloudFront ディストリビューションを作成および更新するオペレーションを CloudTrail でトレースするときは、この API Gateway アカウント ID を使用する必要があります。詳細については、「[CloudTrail におけるカスタムドメイン名の作成のログ記録](#how-to-custom-domain-log-cloudfront-distribution-update-in-cloudtrail)」を参照してください。
+ API Gateway は、CloudFront ディストリビューションで Server Name Indication (SNI) を利用することで、エッジ最適化のカスタムドメイン名をサポートしています。証明書の必須の形式や証明書の最大キー長など、CloudFront ディストリビューションでのカスタムドメイン名の使用の詳細については、「Amazon CloudFront 開発者ガイド」の「[代替ドメイン名と HTTPS を使用する](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-https-alternate-domain-names.html)」を参照してください。**
+ エッジ最適化カスタムドメイン名の準備には約 40 分かかります。
+ エッジ最適化カスタムドメイン名を作成したら、DNS レコードを作成して、カスタムドメイン名を CloudFront ディストリビューション名にマッピングする必要があります。
## エッジ最適化カスタムドメイン名を作成する
次の手順では、API のエッジ最適化カスタムドメイン名を作成する方法を示します。
------
#### [ AWS マネジメントコンソール ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. メインのナビゲーションペインから [**Custom Domain Names (カスタムドメイン名)**] を選択します。
1. **[ドメイン名の追加]** を選択します。
1. [**ドメイン名**] には、ドメイン名を入力します。
1. **[ルーティングモード]** では、**[API\$1MAPPING\$1ONLY]** を選択します。
1. **[エンドポイントタイプ]** で、**[エッジ最適化]** を選択します。
1. TLS の最小バージョンを選択します。
1. ACM 証明書を選択します。
1. **[ドメイン名の追加]** を選択します。
------
#### [ REST API ]
1. [domainname:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDomainName.html) を呼び出し、カスタムドメイン名と AWS Certificate Manager に保存してある証明書の ARN を指定します。
API コールが成功すると、証明書 ARN、および関連する CloudFront ディストリビューション名をペイロードに含む `201 Created` レスポンスを返します。
1. 出力に表示される CloudFront ディストリビューションドメイン名をメモしておきます。次のステップにおいて、DNS でカスタムドメインの A レコードのエイリアスターゲットを設定するために、これが必要になります。
この REST API コールのコード例については、「[domainname:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDomainName.html)」を参照してください。
------
エッジ最適化カスタムドメイン名の準備には約 40 分かかりますが、コンソールには、関連する CloudFront ディストリビューションドメイン名が、証明書 ARN と共に、`distribution-id.cloudfront.net` の形式ですぐに表示されます。その間に、ベースパスマッピングまたはルーティングルールを作成しておき、関連する CloudFront ディストリビューションドメイン名にカスタムドメイン名をマッピングするように DNS レコードエイリアスを設定できます。
## カスタムドメイン名をホスト名として API のベースパスマッピングを設定する
ルーティングモードを `API_MAPPING_ONLY` に設定しているため、ベースパスマッピングを通じて、単一のカスタムドメイン名を複数の API のホスト名として使用できます。これにより、カスタムドメイン名および関連するベースパスを組み合わせて API にアクセスできます。
例えば、API Gateway で、`PetStore` という名前の API と `Dogs` という名前の別の API を作成し、`api.example.com` のカスタムドメイン名を設定すると、`PetStore` API の URL を `https://api.example.com` として設定できます。
これにより、`PetStore` API は空の文字列のベースパスに関連付けられます。`PetStore` API の URL を `https://api.example.com/PetStore` として設定すると、`PetStore` API は `PetStore` のベースパスに関連付けられます。`MyDogList` API には、ベースパスとして `Dogs` を割り当てることができます。URL `https://api.example.com/MyDogList` は、`Dogs` API のルート URL となります。
複数のレベルで API マッピングを設定するには、リージョン別カスタムドメイン名のみを使用できます。エッジ最適化カスタムドメイン名はサポートされません。詳細については、「[API マッピングを使用して、API ステージを REST API のカスタムドメイン名に接続します。](rest-api-mappings.md)」を参照してください。
以下の手順では、カスタムドメイン名から API ステージにパスをマップするための API マッピングをセットアップします。
------
#### [ AWS マネジメントコンソール ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. API Gateway コンソールのナビゲーションペインから [**Custom Domain Names (カスタムドメイン名)**] を選択します。
1. カスタムドメイン名を選択します。
1. [**Configure API mappings (API マッピングの設定)**] を選択します。
1. [**Add new mapping (新しいマッピングを追加)**] を選択します。
1. マッピングの **API**、**ステージ**、**パス** (オプション) を指定します。
1. **[保存]** を選択します。
------
#### [ REST API ]
特定のカスタムドメイン名で [basepathmapping:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateBasePathMapping.html) を呼び出し、リクエストペイロードの `basePath`、`restApiId`、およびデプロイ `stage` プロパティを指定します。
API 呼び出しが成功すると、`201 Created` レスポンスを返します。
REST API コールのコード例については、[basepathmapping:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateBasePathMapping.html) を参照してください。
------
API へのトラフィックのルーティング方法をより柔軟にするために、ルーティングモードを `ROUTING_RULE_ONLY` または `ROUTING_RULE_THEN_API_MAPPING` に変更し、ルーティングルールを作成することができます。詳細については、「[API Gateway のカスタムドメイン名を使用して API にトラフィックを送信します。](rest-api-routing-mode.md)」を参照してください。
## エッジ最適化カスタムドメイン名の DNS レコードを作成する
エッジ最適化カスタムドメイン名の作成を開始したら、DNS レコードエイリアスを設定します。
Route 53 を使用してカスタムドメイン名の A レコードエイリアスを作成し、エイリアス先として CloudFront ディストリビューションドメイン名を指定することをお勧めします。その結果、カスタムドメイン名が Zone Apex であっても、Route 53 はカスタムドメイン名をルーティングすることができます。詳細については、*Amazon Route 53 デベロッパーガイド*の「[エイリアスリソースレコードセットと非エイリアスリソースレコードセットの選択](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-choosing-alias-non-alias.html)」を参照してください。
Amazon Route 53 の手順については、*Amazon Route 53 デベロッパーガイド*の「[ドメイン名を使用してトラフィックを Amazon API Gateway API にルーティングする](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html) 」を参照してください。
## CloudTrail におけるカスタムドメイン名の作成のログ記録
アカウントによる API Gateway コールのログ記録に CloudTrail が有効になっている場合、API Gateway は、API のカスタムドメイン名が作成または更新されたときに、関連付けられた CloudFront ディストリビューションの更新を記録します。これらのログは `us-east-1` にあります。これらの CloudFront ディストリビューションは API Gateway が所有しているため、報告された各 CloudFront ディストリビューションは、API 所有者のアカウント ID ではなく、次のいずれかのリージョン固有の API Gateway アカウント ID によって識別されます。
| **リージョン** | **アカウント ID** |
| --- | --- |
| us-east-1 | 392220576650 |
| us-east-2 | 718770453195 |
| us-west-1 | 968246515281 |
| us-west-2 | 109351309407 |
| ca-central-1 | 796887884028 |
| eu-west-1 | 631144002099 |
| eu-west-2 | 544388816663 |
| eu-west-3 | 061510835048 |
| eu-central-1 | 474240146802 |
| eu-central-2 | 166639821150 |
| eu-north-1 | 394634713161 |
| eu-south-1 | 753362059629 |
| eu-south-2 | 359345898052 |
| ap-northeast-1 | 969236854626 |
| ap-northeast-2 | 020402002396 |
| ap-northeast-3 | 360671645888 |
| ap-southeast-1 | 195145609632 |
| ap-southeast-2 | 798376113853 |
| ap-southeast-3 | 652364314486 |
| ap-southeast-4 | 849137399833 |
| ap-south-1 | 507069717855 |
| ap-south-2 | 644042651268 |
| ap-east-1 | 174803364771 |
| sa-east-1 | 287228555773 |
| me-south-1 | 855739686837 |
| me-central-1 | 614065512851 |
## ACM にインポートされた証明書を更新
ACM は使用する証明書の更新を自動的に処理します。カスタムドメイン名に ACM 使用の証明書を更新する必要はありません。CloudFront はユーザーに代わって処理します。
ただし、証明書を ACM にインポートし、カスタムドメイン名に使用すると、期限切れ前に証明書を更新する必要があります。これにはドメイン名に関する新しいサードパーティーの証明書のインポートも含まれ、既存の証明書は新規更新されます。期限切れの証明書を新しくインポートするときはそのプロセスを繰り返す必要があります。また、ACM にドメイン名に関する新しい証明書を発行するようリクエストもでき、既存のものを ACM 発行の新しい証明書に更新します。その後で、ACM と CloudFront により証明書の更新を自動的に処理するようにできます。新しい ACM 証明書を作成またはインポートするには、「[SSL/TLS 証明書を作成または ACM にインポートするには](how-to-specify-certificate-for-custom-domain-name.md#how-to-specify-certificate-for-custom-domain-name-setup)」の手順に従います。
次の手順では、ドメイン名の証明書をローテーションする方法を示します。
**注記**
ACM にインポートした証明書のローテーションには約 40 分かかります。
------
#### [ AWS マネジメントコンソール ]
1. ACM に証明書をリクエストするかインポートします。
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. API Gateway コンソールのナビゲーションペインから [**Custom Domain Names (カスタムドメイン名)**] を選択します。
1. エッジ最適化カスタムドメイン名を選択します。
1. **[エンドポイント設定]** で、**[編集]** を選択します。
1. **[ACM 証明書]** で、ドロップダウンリストから証明書を選択します。
1. **[変更を保存]** を選択し、カスタムドメイン名の証明書の更新を開始します。
------
#### [ REST API ]
[domainname:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDomainName.html) アクションを呼び出し、指定したドメイン名の新しい ACM 証明書の ARN を指定します。
------
#### [ AWS CLI ]
次の [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) は、エッジ最適化のドメイン名の ACM 証明書を更新します。
```
aws apigateway update-domain-name \
--domain-name edge.example.com \
--patch-operations "op='replace',path='/certificateArn',value='arn:aws:acm:us-east-2:111122223333:certificate/CERTEXAMPLE123EXAMPLE'"
```
次の [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) は、リージョンのドメイン名の ACM 証明書を更新します。
```
aws apigateway update-domain-name \
--domain-name regional.example.com \
--patch-operations "op='replace',path='/regionalCertificateArn',value='arn:aws:acm:us-east-2:111122223333:certificate/CERTEXAMPLE123EXAMPLE'"
```
------
## ベースパスマッピングを使用する場合にカスタムドメイン名を使用して API を呼び出す
カスタムドメイン名で API を呼び出すことは、正しい URL を使用する場合、デフォルトのドメイン名で API を呼び出すことと同じです。
次の例では、指定されたリージョン (`udxjef`) で、指定されたカスタムドメイン名 (`qf3duz`) の 2 つの API (`us-east-1` および `api.example.com`) のデフォルトの URL と対応するカスタム URL を比較し、違いを示します。
| API ID | ステージ | デフォルト URL | 基本パス | カスタム URL |
| --- | --- | --- | --- | --- |
| udxjef | prod | https://udxjef.execute-api.us-east-1.amazonaws.com/prod | /petstore | https://api.example.com/petstore |
| udxjef | tst | https://udxjef.execute-api.us-east-1.amazonaws.com/tst | /petdepot | https://api.example.com/petdepot |
| qf3duz | dev | https://qf3duz.execute-api.us-east-1.amazonaws.com/dev | /bookstore | https://api.example.com/bookstore |
| qf3duz | tst | https://qf3duz.execute-api.us-east-1.amazonaws.com/tst | /bookstand | https://api.example.com/bookstand |
API へのトラフィックのルーティング方法をより柔軟にするために、ルーティングルールを作成することができます。詳細については、「[API Gateway のカスタムドメイン名を使用して API にトラフィックを送信します。](rest-api-routing-mode.md)」を参照してください。
API Gateway では、[Server Name Indication (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) を使用した、API のカスタムドメイン名がサポートされています。SNI をサポートするブラウザまたはクライアントライブラリを使用して、カスタムドメイン名の API を呼び出すことができます。
API Gateway では、CloudFront ディストリビューションで SNI を実施します。CloudFront でのカスタムドメイン名の使用の詳細については、「[Amazon CloudFront カスタム SSL](https://aws.amazon.com/cloudfront/custom-ssl-domains/)」を参照してください。
# API Gateway でカスタムドメイン名を別の API エンドポイントタイプに移行する
エッジ最適化のエンドポイントとリージョン別エンドポイントの間で、カスタムドメイン名を移行できます。パブリックカスタムドメイン名をプライベートカスタムドメイン名に移行することはできません。まず、新しいエンドポイント設定タイプをカスタムドメイン名の既存の `endpointConfiguration.types` リストに追加します。次に、カスタムドメイン名が、新しくプロビジョンされたエンドポイントを参照するように、DNS レコードを設定します。最後に、古いカスタムドメイン名のエンドポイントを削除します。
## 考慮事項
リージョン別 API エンドポイントとエッジ最適化 API エンドポイントの間でカスタムドメインを移行する際の考慮事項は、以下のとおりです。
+ エッジ最適化カスタムドメイン名には、米国東部 (バージニア北部) – `us-east-1` リージョンの ACM が提供する証明書が必要です。この証明書はすべての地理的場所に配布されます。
+ リージョン別カスタムドメイン名には、API をホストしているのと同じリージョンで ACM が提供する証明書が必要です。`us-east-1` リージョンに存在しないエッジ最適化カスタムドメイン名をリージョン別カスタムドメイン名に移行するには、API のローカルリージョンに新しい ACM 証明書をリクエストできます。
+ エッジ最適化カスタムドメイン名とリージョン別カスタムドメイン名との間で移行が完了するまでに最大 60 秒かかることがあります。移行時間は、DNS レコードをいつ更新するかによっても異なります。
+ エンドポイントアクセスモードが `BASIC` に設定されている場合にのみ、追加のエンドポイント設定を追加できます。2 つのエンドポイント設定があると、エンドポイントアクセスモードを変更することはできません。詳細については、「[エンドポイントアクセスモード](apigateway-security-policies.md#apigateway-security-policies-endpoint-access-mode)」を参照してください。
+ カスタムドメイン名が `SecurityPolicy_` で始まるセキュリティポリシーを使用している場合、新しいエンドポイント設定タイプを追加すると、エンドポイントアクセスモードは両方のエンドポイントタイプで同じになり、新しいエンドポイント設定タイプで `SecurityPolicy_` で始まるセキュリティポリシーを選択する必要があります。
## カスタムドメイン名を移行する
**注記**
移行を完了するには、カスタムドメイン名から古いエンドポイントを削除してください。
次の手順では、エッジ最適化カスタムドメイン名をリージョン別カスタムドメイン名に移行する方法を示します。
------
#### [ AWS マネジメントコンソール ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. メインのナビゲーションペインから [**Custom Domain Names (カスタムドメイン名)**] を選択します。
1. エッジ最適化カスタムドメイン名を選択します。
1. **[エンドポイント設定]** で、**[編集]** を選択します。
1. **[リージョンエンドポイントを追加]** を選択します。
1. **[ACM 証明書]** で、証明書を選択します。
リージョン別証明書はリージョン別 API と同じリージョンである必要があります。
1. **[Save changes]** (変更の保存) をクリックします。
1. リージョン別カスタムドメイン名をこのリージョン別ホスト名にポイントするように DNS レコードを設定します。詳細については、「[API Gateway にトラフィックをルーティングするように Route 53 を設定する](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html)」を参照してください。
1. DNS 設定が正しいエンドポイントを使用していることを確認したら、エッジ最適化エンドポイント設定を削除します。カスタムドメイン名を選択し、**[エッジ最適化エンドポイント設定]** で **[削除]** を選択します。
1. 選択内容を確認し、エンドポイントを削除します。
------
#### [ AWS CLI ]
次の [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) コマンドは、エッジ最適化カスタムドメイン名をリージョン別カスタムドメイン名に移行します。
```
aws apigateway update-domain-name \
--domain-name 'api.example.com' \
--patch-operations '[
{ "op":"add", "path": "/endpointConfiguration/types","value": "REGIONAL" },
{ "op":"add", "path": "/regionalCertificateArn", "value": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149" }
]'
```
リージョン別証明書はリージョン別 API と同じリージョンである必要があります。
出力は次のようになります。
```
{
"certificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
"certificateName": "edge-cert",
"certificateUploadDate": "2017-10-16T23:22:57Z",
"distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
"domainName": "api.example.com",
"endpointConfiguration": {
"types": [
"EDGE",
"REGIONAL"
]
},
"regionalCertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149",
"regionalDomainName": "d-fdisjghyn6.execute-api.us-west-2.amazonaws.com"
}
```
移行されたリージョンのカスタムドメイン名の場合、リージョン別 API のホスト名が `regionalDomainName` プロパティとして返されます。リージョン別カスタムドメイン名がこのリージョン別ホスト名を参照するように DNS レコードを設定する必要があります。これにより、カスタムドメイン名宛てのトラフィックがリージョン別ホストにルーティングされるようになります。
DNS レコードを設定したら、エッジ最適化カスタムドメイン名を削除できます。次の [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) コマンドは、エッジ最適化カスタムドメイン名を削除します。
```
aws apigateway update-domain-name \
--domain-name api.example.com \
--patch-operations '[
{"op":"remove", "path":"/endpointConfiguration/types", "value":"EDGE"},
{"op":"remove", "path":"certificateName"},
{"op":"remove", "path":"certificateArn"}
]'
```
------
次の手順は、拡張セキュリティポリシーを使用するエッジ最適化カスタムドメイン名を、拡張セキュリティポリシーを使用するリージョン別カスタムドメイン名に移行する方法を示しています。
------
#### [ AWS マネジメントコンソール ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. メインのナビゲーションペインから [**Custom Domain Names (カスタムドメイン名)**] を選択します。
1. エッジ最適化カスタムドメイン名を選択します。
1. **[エンドポイント設定]** で、**[編集]** を選択します。
1. **[リージョンエンドポイントを追加]** を選択します。
1. **[ACM 証明書]** で、証明書を選択します。
リージョン別証明書はリージョン別 API と同じリージョンである必要があります。
1. **[セキュリティポリシー]** で、`SecurityPolicy_` で始まるセキュリティポリシーを選択します。
1. **[エンドポイントアクセスモード]** で、**[基本]** を選択します。
1. **[Save changes]** (変更の保存) をクリックします。
1. リージョン別カスタムドメイン名をこのリージョン別ホスト名にポイントするように DNS レコードを設定します。詳細については、「[API Gateway にトラフィックをルーティングするように Route 53 を設定する](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html)」を参照してください。
1. DNS 設定が正しいエンドポイントを使用していることを確認したら、エッジ最適化エンドポイント設定を削除します。カスタムドメイン名を選択し、**[エッジ最適化エンドポイント設定]** で **[削除]** を選択します。
1. 選択内容を確認し、エンドポイントを削除します。
------
#### [ AWS CLI ]
次の [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) コマンドは、エッジ最適化カスタムドメイン名をリージョン別カスタムドメイン名に移行します。
```
aws apigateway update-domain-name \
--domain-name 'api.example.com' \
--patch-operations '[
{ "op":"add", "path": "/endpointConfiguration/types","value": "REGIONAL" },
{ "op":"replace", "path": "/securityPolicy", "value":"SecurityPolicy_TLS13_1_3_2025_09"},
{ "op":"add", "path": "/regionalCertificateArn", "value": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149" }
]'
```
リージョン別証明書はリージョン別 API と同じリージョンである必要があります。
出力は次のようになります。
```
{
"certificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
"certificateName": "edge-cert",
"certificateUploadDate": "2017-10-16T23:22:57Z",
"distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
"domainName": "api.example.com",
"endpointConfiguration": {
"types": [
"EDGE",
"REGIONAL"
]
},
"securityPolicy": "SecurityPolicy_TLS13_1_3_2025_09",
"endpointAccessMode": "BASIC",
"regionalCertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149",
"regionalDomainName": "d-fdisjghyn6.execute-api.us-west-2.amazonaws.com"
}
```
移行されたリージョンのカスタムドメイン名の場合、リージョン別 API のホスト名が `regionalDomainName` プロパティとして返されます。リージョン別カスタムドメイン名がこのリージョン別ホスト名を参照するように DNS レコードを設定する必要があります。これにより、カスタムドメイン名宛てのトラフィックがリージョン別ホストにルーティングされるようになります。
DNS レコードを設定したら、エッジ最適化カスタムドメイン名を削除できます。次の [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) コマンドは、エッジ最適化カスタムドメイン名を削除します。
```
aws apigateway update-domain-name \
--domain-name api.example.com \
--patch-operations '[
{"op":"remove", "path":"/endpointConfiguration/types", "value":"EDGE"},
{"op":"remove", "path":"certificateName"},
{"op":"remove", "path":"certificateArn"}
]'
```
------
次の手順は、リージョン別カスタムドメイン名をエッジ最適化カスタムドメイン名に移行する方法を示しています。
------
#### [ AWS マネジメントコンソール ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. メインナビゲーションペインで、**[カスタムドメイン名]** を選択します。
1. リージョン別カスタムドメイン名を選択します。
1. **[エンドポイント設定]** で、**[編集]** を選択します。
1. **[エッジ最適化エンドポイントを追加]** を選択します。
1. **[ACM 証明書]** で、証明書を選択します。
エッジ最適化のドメイン証明書は、`us-east-1` リージョンに作成する必要があります。
1. **[保存]** を選択します。
1. エッジ最適化カスタムドメイン名をこのエッジ最適化ホスト名にポイントするように DNS レコードを設定します。詳細については、「[API Gateway にトラフィックをルーティングするように Route 53 を設定する](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html)」を参照してください。
1. DNS 設定が正しいエンドポイントを使用していることを確認したら、リージョンエンドポイント設定を削除します。カスタムドメイン名を選択し、**[リージョン別エンドポイント設定]** で **[削除]** を選択します。
1. 選択内容を確認し、エンドポイントを削除します。
------
#### [ AWS CLI ]
次の [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) コマンドは、リージョン別カスタムドメイン名をエッジ最適化カスタムドメイン名に移行します。
```
aws apigateway update-domain-name \
--domain-name 'api.example.com' \
--patch-operations '[
{ "op":"add", "path": "/endpointConfiguration/types","value": "EDGE" },
{ "op":"add", "path": "/certificateName", "value": "edge-cert" },
{"op":"add", "path": "/certificateArn", "value": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a"}
]'
```
エッジ最適化のドメイン証明書は、`us-east-1` リージョンに作成する必要があります。
出力は次のようになります。
```
{
"certificateArn": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
"certificateName": "edge-cert",
"certificateUploadDate": "2017-10-16T23:22:57Z",
"distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
"domainName": "api.example.com",
"endpointConfiguration": {
"types": [
"EDGE",
"REGIONAL"
]
},
"regionalCertificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/3d881b54-851a-478a-a887-f6502760461d",
"regionalDomainName": "d-cgkq2qwgzf.execute-api.us-east-1.amazonaws.com"
}
```
指定したカスタムドメイン名の場合、API Gateway はエッジ最適化 API のホスト名を `distributionDomainName` プロパティ値として返します。エッジ最適化のカスタムドメイン名がこのディストリビューションドメイン名を参照するように DNS レコードを設定する必要があります。これにより、エッジ最適化のカスタムドメイン名宛てのトラフィックがエッジ最適化の API ホスト名にルーティングされるようになります。
DNS レコードを設定したら、カスタムドメイン名の `REGION` エンドポイントタイプを削除できます。次の [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) コマンドは、リージョン別エンドポイントタイプを削除します。
```
aws apigateway update-domain-name \
--domain-name api.example.com \
--patch-operations '[
{"op":"remove", "path":"/endpointConfiguration/types", value:"REGIONAL"},
{"op":"remove", "path":"regionalCertificateArn"}
]'
```
出力は次のようになります。
```
{
"certificateArn": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
"certificateName": "edge-cert",
"certificateUploadDate": "2017-10-16T23:22:57Z",
"distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
"domainName": "api.example.com",
"endpointConfiguration": {
"types": "EDGE"
}
}
```
------
# API Gateway のカスタムドメイン名を使用して API にトラフィックを送信します。
カスタムドメイン名のルーティングモードを設定するときは、受信トラフィックを API に送信する方法を設定します。ルーティングルール、API マッピング、またはルーティングルールと API マッピングを使用して API にトラフィックを送信します。次のセクションでは、ルーティングルールを使用するタイミング、API マッピングを使用するタイミング、カスタムドメイン名のルーティングモードを設定する方法について説明します。
## ルーティングルールを使用するタイミング
ルーティングルールを使用すると、特定の条件に一致する受信リクエストを特定の REST API ステージに送信できます。例えば、ルールにヘッダー `version:v1` とベースパス `/users` が含まれている場合、ルールはリクエストを `users` REST API の `production` ステージにルーティングできます。ルーティングルールを使用して、A/B テストや API の新しいバージョンの使用量の増加などのユースケースをサポートする高度な動的ルーティングトポロジを作成します。
トラフィックを REST API に送信するときは、カスタムドメイン名のルーティングルールを使用することをお勧めします。ルーティングルールを使用して、任意の API マッピングを再作成できます。詳細については、「[ルーティングルールを使用して API マッピングを再作成する](rest-api-routing-rules-recreate-api-mapping.md)」を参照してください。
REST API では、ルーティングルールと API マッピングを一緒に使用することもできます。ルーティングルールと API マッピングを一緒に使用すると、API Gateway は API マッピングを評価する前に、常にルーティングルールを評価します。ルーティングルールと API マッピングを一緒に使用して、現在のカスタムドメイン名を移行したり、ルーティングルールを調べたりします。
### ルーティングルールに関する考慮事項
以下の考慮事項は、ルーティングルールの使用に影響する可能性があります。
+ WebSocket または HTTP API は、ルーティングルールのターゲット API としてサポートされていません。
+ カスタムドメイン名に REST API と HTTP API の両方への API マッピングがある場合、ルーティングルールはサポートされません。
+ プライベートカスタムドメインのルーティングルールをプライベート REST API に作成できます。リージョン別 API またはエッジ最適化 API へのパブリックカスタムドメインのルーティングルールを作成できます。
+ プライベート API へのパブリックカスタムドメインのルーティングルールを作成することはできません。パブリック API へのプライベートカスタムドメイン名のルーティングルールを作成することはできません。
## ルーティングルールまたは API マッピングのどちらかを選択する
可能な場合は、ルーティングルールを使用することをお勧めします。API マッピングのみを使用して、HTTP または WebSocket API にトラフィックを送信します。
# カスタムドメイン名のルーティングモードを設定する
API Gateway が API にトラフィックをルーティングするために使用するルーティングモードを選択できます。詳細については、「[API Gateway のカスタムドメイン名を使用して API にトラフィックを送信します。](rest-api-routing-mode.md)」を参照してください。このセクションでは、カスタムドメイン名のルーティングモードについて説明します。API にトラフィックをルーティングするには、カスタムドメイン名のルーティングモードを設定する必要があります。次のルーティングモードがサポートされています。
+ **ROUTING\$1RULE\$1THEN\$1API\$1MAPPING** – このモードを使用して、ルーティングルールと API マッピングの両方を使用してトラフィックを API に送信します。このモードでは、すべてのルーティングルールがすべての API マッピングよりも優先されます。このモードの例については、「[例 2: ルーティングルールと API マッピング](rest-api-routing-rules-examples.md#rest-api-routing-rules-examples-rule-and-mappings)」を参照してください。
+ **ROUTING\$1RULE\$1ONLY** – このモードを使用すると、ルーティングルールのみが API にトラフィックを送信できるようにします。カスタムドメイン名がこのモードを使用する場合、API マッピングを作成することはできませんが、[get-api-mappings](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-api-mappings.html) コマンドを使用して表示することはできます。API 発信者は、API マッピングを使用してこのドメイン名にアクセスすることはできません。
+ **API\$1MAPPING\$1ONLY** – このモードを使用すると、API マッピングのみが API にトラフィックを送信できるようにします。カスタムドメイン名がこのモードを使用する場合、ルーティングルールを作成することはできませんが、`list-routing-rules` コマンドを使用して表示できます。API 発信者は、ルーティングルールを使用してこのドメイン名にアクセスすることはできません。
これは、既存のすべてのドメイン名と、作成する新しいドメイン名のデフォルトのルーティングモードです。
`apigateway` を使用してカスタムドメイン名を作成すると、`API_MAPPING_ONLY` は `BASE_PATH_MAPPING_ONLY` と呼ばれ、`ROUTING_RULE_THEN_API_MAPPING` は `ROUTING_RULE_THEN_BASE_PATH_MAPPING` と呼ばれます。この動作は AWS CLI、CloudFormation、または任意の SDK にのみ表示され、AWS マネジメントコンソールには表示されません。
次の手順は、既存のカスタムドメイン名のルーティングモードを変更する方法を示しています。カスタムドメイン名のルーティングモードを変更すると、API 発信者はサポートされていないルーティングモードを使用してドメイン名にアクセスできなくなります。
------
#### [ AWS マネジメントコンソール ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. メインのナビゲーションペインから [**Custom Domain Names (カスタムドメイン名)**] を選択します。
1. カスタムドメイン名を選択します。
1. **[ドメインの詳細]** については、**[編集]** を選択します。
1. **[ルーティングモード]** については、**[ROUTING\$1RULE\$1THEN\$1API\$1MAPPING]** を選択します。
1. **[保存]** を選択します。
ルーティングモードを `ROUTING_RULE_ONLY` または `API_MAPPING_ONLY` に変更すると、作成した API マッピングまたはルーティングルールがコンソールのドメイン名の詳細ページから削除されます。ルーティングルールまたは API マッピングをサポートするようにルーティングモードを変更すると、これらのリソースが返されます。
------
#### [ AWS CLI - apigatewayv2 ]
次の [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) コマンドは、ルーティングモード `ROUTING_RULE_THEN_API_MAPPING` を使用するようにドメイン名を更新します。
```
aws apigatewayv2 update-domain-name \
--domain-name 'api.example.com' \
--routing-mode "ROUTING_RULE_THEN_API_MAPPING"
```
出力は次のようになります。
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "api.example.com",
"DomainNameArn": "arn:aws:apigateway:us-west-2::/domainnames/api.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcdefg.execute-api.us-west-2.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/abcdefg-123456-abcdefg",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z2OJLYMUO9EFXC",
"SecurityPolicy": "TLS_1_2"
}
],
"RoutingMode": "ROUTING_RULE_THEN_API_MAPPING",
"Tags": {}
}
```
------
#### [ AWS CLI - apigateway ]
次の [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) コマンドは、ルーティングモード `ROUTING_RULE_THEN_BASE_PATH_MAPPING` を使用するようにプライベートカスタムドメイン名を更新します。
```
aws apigateway update-domain-name \
--domain-name 'private.example.com' \
--patch-operations "op='replace',path='/routingMode',value='ROUTING_RULE_THEN_BASE_PATH_MAPPING'"
```
出力は次のようになります。
```
{
"domainName": "private.example.com",
"domainNameId": "abcd1234",
"domainNameArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234",
"certificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef",
"certificateUploadDate": "2024-09-10T10:31:20-07:00",
"endpointConfiguration": {
"types": [
"PRIVATE"
],
"ipAddressType": "dualstack"
},
"domainNameStatus": "AVAILABLE",
"securityPolicy": "TLS_1_2",
"policy": "...",
"routingMode" : "ROUTING_RULE_THEN_BASE_PATH_MAPPING"
}
```
------
# API ステージを REST API のカスタムドメイン名に接続するためのルーティングルール
ルーティングルールは、一致したときにアクションを呼び出す一連の条件です。例えば、ルールは、ヘッダー `Hello:World` を含み、REST API の `production` ステージへのベースパス `users` を含むカスタムドメイン名に受信リクエストをルーティングできます。
ルールは優先順位で評価され、ルーティングモードを `ROUTING_RULE_THEN_API_MAPPING` に設定すると、API Gateway は API マッピングを評価する前に常にすべてのルーティングルールを評価します。次のリストは、ルーティングルールが条件、アクション、優先順位をどのように使用するかを示しています。
**条件**
ルールの条件が満たされると、アクションが実行されます。API Gateway は、最大 2 つのヘッダー条件と 1 つのパス条件をサポートします。API Gateway は、ヘッダー条件とベースパス条件を一緒に評価します。
条件なしでルールを作成できます。API Gateway がこのルールを評価すると、アクションは常に実行されます。キャッチオールルールとして、条件なしでルールを作成できます。
ヘッダー条件の詳細については、「[ヘッダー条件の一致](#rest-api-routing-rules-condition-headers)」を参照してください。パス条件の詳細については、「[ベースパス条件の一致](#rest-api-routing-rules-condition-path)」を参照してください。
**アクション**
アクションは、ルーティングルールに条件が一致した結果です。現在サポートされているアクションは、REST API のステージを呼び出すことのみです。
各ルールには 1 つのアクションを含めることができます。
**Priority**
優先度により、ルールが評価される順序 (低い値から高い値の順) が決定します。ルールに同じ優先順位を設定することはできません。
優先度は 1～1,000,000 に設定できます。優先度が 1 のルールは、API Gateway によって最初に評価されます。ルールを作成するときは、優先順位にギャップを追加することをお勧めします。これにより、ルールの優先度を切り替え、新しいルールを追加することができます。詳細については、「[ルーティングルールの優先度を変更する](apigateway-routing-rules-use.md#rest-api-routing-rules-change-priority)」を参照してください。
API Gateway がルーティングルールを評価する方法の例については、「[API Gateway がルーティングルールを評価する方法の例](rest-api-routing-rules-examples.md)」を参照してください。
## API Gateway ルーティングルールの条件タイプ
次のセクションでは、ルーティングルールの条件タイプについて説明します。API Gateway は、すべての条件が true の場合にのみルールに一致します。
### ヘッダー条件の一致
ヘッダー条件を作成するときに、`Hello:World` などのヘッダー名とヘッダー glob 値を一致させることができます。API Gateway はリテラル一致を使用して、一致ヘッダー条件を検証します。条件は、それらの間で `AND` を使用して最大 2 つのヘッダーを使用できます。例えば、受信リクエストに `Hello:World` と `x-version:beta` が含まれている場合、条件は一致します。
ヘッダー名の一致では大文字と小文字は区別されませんが、ヘッダー glob 値は大文字と小文字が区別されます。`Hello:World` は `hello:World` と一致しますが、`Hello:world` とは一致しません。
制限されたヘッダー値のリストについては、「[制限事項](#rest-api-routing-rules-restrictions)」を参照してください。
#### ヘッダー条件でのワイルドカードの使用
ワイルドカードはヘッダー glob 値でのみ使用でき、ワイルドカードは `*prefix-match`、`suffix-match*`、または `*contains*` である必要があります。次の表は、ヘッダー条件の一致にワイルドカードを使用する方法の例を示しています。
| ヘッダー条件 | ルーティングルールと一致するリクエスト | ルーティングルールと一致しないリクエスト |
| --- | --- | --- |
| `x-version: a*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a*` および `x-version: *b*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: b*` および `x-version: *a` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/rest-api-routing-rules.html) | なし |
複数のヘッダー値の条件を作成する場合 (例: `Accept:application/json,text/xml`)、ヘッダー条件に `*contains*` を使用し、カンマ (`,`) 文字を使用して条件を作成しないようにすることをお勧めします。
API Gateway はヘッダー条件を文字通り一致させるため、セマンティック一致のルーティングが異なる場合があります。次の表は、ルーティングルールの結果の違いを示しています。
| ヘッダー条件 | ルーティングルールと一致するリクエスト | ルーティングルールと一致しないリクエスト |
| --- | --- | --- |
| `Accept: *json` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `Accept: *json*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/rest-api-routing-rules.html) | なし |
### ベースパス条件の一致
ベースパス条件を作成するときに、受信リクエストに指定したパスが含まれている場合、ルールは一致します。一致では大文字と小文字が区別されるため、パス `New/Users` は `new/users` と一致しません。
ベースパス条件は、1 つのベースパスに対してのみ作成できます。
制限されたベースパス条件のリストについては、「[制限事項](#rest-api-routing-rules-restrictions)」を参照してください。
#### ベースパス条件を使用してベースパスを削除する
ベースパス条件を作成するときに、ベースパスを削除することを選択できます。ベースパスを削除すると、API Gateway はターゲット API を呼び出すときに着信する一致したベースパスを削除します。これは、API マッピングを使用する場合と同じ動作です。ベースパスを削除しない場合、API Gateway はベースパス全体をターゲット API に転送します。API マッピングを再作成する場合にのみ、ベースパスを削除することをお勧めします。
次の表は、API Gateway がベースパス削除条件を評価する方法の例を示しています。
| 条件 | ベースパスを削除する | 受信リクエスト | 結果 |
| --- | --- | --- | --- |
| ベースパスに `PetStoreShopper/dogs` が含まれている場合 | 正 | `GET https://example.com/PetStoreShopper/dogs` | API Gateway は、`/` リソースの `GET` メソッドを呼び出します。 |
| ベースパスに `PetStoreShopper/dogs` が含まれている場合 | 誤 | `GET https://example.com/PetStoreShopper/dogs` | API Gateway は、`PetStoreShopper/dogs` リソースの `GET` メソッドを呼び出します。 |
| ベースパスに `PetStoreShopper` が含まれている場合 | 正 | `GET https://example.com/PetStoreShopper/dogs` | API Gateway は、`dogs` リソースの `GET` メソッドを呼び出します。 |
| ベースパスに `PetStoreShopper` が含まれている場合 | 誤 | `GET https://example.com/PetStoreShopper/dogs` | API Gateway は、`PetStoreShopper/dogs` リソースの `GET` メソッドを呼び出します。 |
| ベースパスに `PetStoreShopper` が含まれている場合 | 正 | `GET https://example.com/PetStoreShopper?birds=available` | API Gateway は、クエリ文字列パラメータ `birds=available` を使用して `/` リソースの `GET` メソッドを呼び出します。 |
| ベースパスに `PetStoreShopper` が含まれている場合 | 誤 | `GET https://example.com/PetStoreShopper?birds=available` | API Gateway は、クエリ文字列パラメータ `birds=available` を使用して `/PetStoreShopper` リソースの `GET` メソッドを呼び出します。 |
## 制限事項
+ ターゲット API とカスタムドメイン名は、同じ AWS アカウントに存在する必要があります。
+ 各ルールには、1 つのターゲット API を含めることができます。
+ プライベートカスタムドメイン名からプライベート API へのルーティングルールと、パブリックカスタムドメイン名からパブリック API へのルーティングルールのみを作成できます。パブリックリソースとプライベートリソースを混在させることはできません。
+ カスタムドメイン名に REST API と HTTP API の両方への API マッピングがある場合、ルーティングルールはサポートされていません。
+ 最大優先度数は 1,000,000 です。
+ ヘッダー制限:
+ 各 `anyOf` 条件に含めることができるヘッダー値は 1 つだけです。
+ ヘッダー名とヘッダー glob 値に使用できる文字は [RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230) で指定された `a-z`、`A-Z`、`0-9`、および次の特殊文字 `*?-!#$%&'.^_`|~` です。
+ ヘッダーの glob 値にワイルドカードを使用できますが、ワイルドカードは `*prefix-match`、`suffix-match*`、または `*contains*` である必要があります。ヘッダー glob 値の途中で `*` を使用することはできません。
+ ワイルドカードヘッダー名はサポートされていません。
+ ヘッダー名は 40 文字未満にする必要があります。
+ ヘッダー glob 値は 128 文字未満である必要があります。
+ インフィックス一致のヘッダー glob 値は 40 文字未満である必要があります。
+ 以下のヘッダーは条件としてサポートされていません。
+ `access-control-*`
+ `apigw-*`
+ `Authorization`
+ `Connection`
+ `Content-Encoding`
+ `Content-Length`
+ `Content-Location`
+ `Forwarded`
+ `Keep-Alive`
+ `Origin`
+ `Proxy-Authenticate`
+ `Proxy-Authorization`
+ `TE`
+ `Trailers`
+ `Transfer-Encoding`
+ `Upgrade`
+ `x-amz-*`
+ `x-amzn-*`
+ `x-apigw-api-id`
+ `X-Forwarded-For`
+ `X-Forwarded-Host`
+ `X-Forwarded-Proto`
+ `x-restAPI`
+ `Via`
+ ベースパスの制限:
+ ベースパスの長さは 128 文字未満にする必要があります。
+ ベースパスに含めることができるのは、文字、数字、および `$-_.+!*'()/` の文字だけです。
これらの文字は正規表現 (regex) ではサポートされていません。
+ ベースパスは、バックスラッシュ (`\`) 文字で開始または終了することはできません。
# API Gateway がルーティングルールを評価する方法の例
次のセクションでは、API Gateway がルーティングルールと API マッピングを評価する方法の 4 つの例を示します。
## 例 1: ルーティングルールのみ
この例では、カスタムドメイン名 `https://petstore.example.com` のルーティングモードは `ROUTING_RULE_ONLY` に設定され、次のルーティングルールと優先順位があります。
| ルール ID | Priority | 条件 | アクション |
| --- | --- | --- | --- |
| `abc123` | 10 | リクエストにヘッダー `Hello:World` が含まれている場合 | ターゲット API 1 |
| `zzz000` | 50 | リクエストにヘッダー `Accept:image/webp` と `Pet:Dog-*` が含まれている場合、およびベースパスに `PetStoreShopper` が含まれている場合 | ターゲット API 2 |
| `efg456` | 100 | なし | ターゲット API 3 |
次の表は、API Gateway が前のルーティングルールをリクエスト例に適用する方法を示しています。
| リクエスト | 選択した API | 説明 |
| --- | --- | --- |
| `https://petstore.example.com -h "Hello:World"` | ターゲット API 1 | リクエストはルーティングルール `abc123` と一致します。 |
| `https://petstore.example.com/PetStoreShopper -h "Hello:World", "Pet:Dog-Bella", "Accept:image/webp"` | ターゲット API 1 | API Gateway は、すべてのルーティングルールを優先度順に評価します。ルーティングルール `abc123` が優先され、条件が一致するため、API Gateway はターゲット API 1 を呼び出します。 リクエストの条件もルーティングルール `zzz000` と一致しますが、API Gateway は一致後に他のルーティングルールを評価しません。 |
| `https://petstore.example.com/PetStoreShopper -h "Pet:Dog-Bella", "Accept:image/webp"` | ターゲット API 2 | リクエストはルーティングルール `zzz000` と一致します。`Pet:Dog-Bella` が `Pet:Dog-*` に一致する文字列であったため、これは一致でした。 |
| `https://petstore.example.com/PetStoreShopper -h "Pet:Dog-Bella"` | ターゲット API 3 | リクエストがルーティングルール `abc123` と一致しません。必要なヘッダーがすべて存在しないため、リクエストがルーティングルール `zzz000` と一致しません。次の優先度ルールはすべての受信リクエストに一致するため、API Gateway はターゲット API 3 を呼び出します。 |
## 例 2: ルーティングルールと API マッピング
この例では、カスタムドメイン名 `https://petstore.diagram.example.com` のルーティングモードは `ROUTING_RULE_THEN_API_MAPPING` に設定され、次のルーティングルールと API マッピングがあります。
| ルール ID | Priority | 条件 | アクション |
| --- | --- | --- | --- |
| `abc123` | 1 | リクエストに `pets` が含まれている場合 | `PetStore` API の `Prod` ステージを呼び出します。 |
| `000zzz` | 5 | リクエストにヘッダー `Cookie`:`*ux=beta*` が含まれている場合、およびベースパスに `/refunds` が含まれている場合 | `Refunds` API の `Beta` ステージを呼び出します。 |
次の表は、`https://petstore.backup.example.com` の API マッピングを示しています。
| API マッピング | 選択した API |
| --- | --- |
| `/refunds` | `Refunds` API の `Prod` ステージを呼び出します。 |
| `(none)` | `Search` API の `Prod` ステージを呼び出します。 |
次の図は、API Gateway が前のルーティングルールと API マッピングをリクエスト例に適用する方法を示しています。リクエスト例は、この図の後に表にまとめられています。
![\[API Gateway が以前のルーティングルールと API マッピングを適用する方法の図。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/rr-diagram.png)
次の表は、API Gateway が前のルーティングルールと API マッピングをリクエスト例に適用する方法を示しています。
| リクエスト | 選択した API | 説明 |
| --- | --- | --- |
| `https://petstore.diagram.com/pets` | `PetStore` API の `Prod` ステージ。 | リクエストはルーティングルール `abc123` と一致します。 |
| `https://petstore.diagram.example.com/refunds -h "Cookie:lang=en-us;ux=beta"` | `Beta` API の `Refunds` ステージ。 | リクエストはルーティングルール `000zzz` と一致します。`Cookie` ヘッダーには、この条件の正しい `*contains*` 一致と基本パス一致が含まれています。 |
| `https://petstore.diagram.example.com/refunds` | `Prod` API の `Refunds` ステージ。 | リクエストには、ルーティングルール `zzz000` と一致するために必要なヘッダーがありません。API Gateway がルーティングルールに正常に一致できない場合、API マッピングにフォールバックします。API Gateway は、ベースパスを `Refunds` API の `Prod` ステージにマッピングできます。 |
| `https://petstore.diagram.example.com/` | `Prod` API の `Search` ステージ。 | リクエストは API マッピングを空のパス `(none)` に一致させます。 |
## 例 3: 複数のレベルでのルーティングルールと API マッピング
この例では、カスタムドメイン名 `https://petstore.backup.example.com` のルーティングモードは `ROUTING_RULE_THEN_API_MAPPING` に設定され、次のルーティングルールと API マッピングがあります。
次の表は、`https://petstore.backup.example.com` のルーティングルールを示しています。
| ルール ID | Priority | 条件 | アクション |
| --- | --- | --- | --- |
| `abc123` | 10 | リクエストにヘッダー `Hello:World` が含まれている場合 | ターゲット API 1 |
| `000zzz` | 50 | リクエストにヘッダー `Accept`:`image/webp` と `Pet:Dog-*` が含まれている場合、およびベースパスに `PetStoreShopper` が含まれている場合 | ターゲット API 2 |
次の表は、`https://petstore.backup.example.com` の API マッピングを示しています。
| API マッピング | 選択した API |
| --- | --- |
| `PetStoreShopper` | ターゲット API 3 |
| `PetStoreShopper/cats` | ターゲット API 4 |
次の表は、API Gateway が前のルーティングルールと API マッピングをリクエスト例に適用する方法を示しています。
| リクエスト | 選択した API | 説明 |
| --- | --- | --- |
| `https://petstore.example.com/PetStoreShopper -h "Accept:image/webp", "Pet:Cats" ` | ターゲット API 3 | リクエストには、ルーティングルール `zzz000` と一致するために必要なヘッダーがありません。API Gateway がルーティングルールに正常に一致できない場合、API マッピングにフォールバックします。API Gateway は、基本パスをターゲット API 3 にマッピングできます。 |
| `https://petstore.example.com/PetStoreShopper/cats -h "Hello:World"` | ターゲット API 1 | リクエストはルーティングルール `abc123` と一致します。ルーティングモードが `ROUTING_RULE_THEN_API_MAPPING` に設定されている場合、ルーティングルールは常に API マッピングよりも優先されます。 |
| `https://petstore.example.com/Admin -h "Pet:Dog-Bella"` | なし | リクエストがルーティングルールまたは API マッピングと一致しません。デフォルトのルーティングルールがないため、API Gateway は呼び出しを拒否し、発信者に `403 Forbidden` ステータスコードを送信します。 |
## 例 4: ワイルドカードドメイン名のルーティングルール
この例では、カスタムドメイン名 `https://*.example.com` はワイルドカードドメイン名です。ワイルドカードは、同じドメインにルーティングバックするすべてのサブドメインをサポートします。次のルーティングルールの例では、この動作を変更して、`Host` ヘッダーを使用してサブドメインを異なるターゲット API にルーティングできるようにします。
次の表は、`https://*.example.com` のルーティングルールを示しています。
| ルール ID | Priority | 条件 | アクション |
| --- | --- | --- | --- |
| `abc123` | 10 | リクエストにヘッダー `Host:a.example.com` が含まれている場合 | ターゲット API 1 |
| `000zzz` | 50 | リクエストにヘッダー `Host:b.example.com` が含まれている場合 | ターゲット API 2 |
| `efg456` | 500 | なし | ターゲット API 3 |
次の表は、API Gateway が前のルーティングルールをリクエスト例に適用する方法を示しています。
| リクエスト | 選択した API | 説明 |
| --- | --- | --- |
| `https://a.example.com` | ターゲット API 1 | `Host` ヘッダーは `a.example.com` です。このリクエストはルーティングルール `abc123` と一致します。 |
| `https://b.example.com` | ターゲット API 2 | `Host` ヘッダーは `b.example.com` です。このリクエストはルーティングルール `000zzz` と一致します。 |
| `https://testing.example.com` | ターゲット API 3 | これはキャッチオールルーティングルール `efg456` と一致します。 |
# ルーティングルールの使用方法
ルーティングルールは、AWS マネジメントコンソール、AWS CLI、または任意の AWS SDK を使用して作成できます。ルールを作成した後で、その優先度を変更できます。
## ルーティングルールを作成する
次の手順は、ルーティングモードが `ROUTING_RULE_THEN_API_MAPPING` または `ROUTING_RULE_ONLY` に設定されているカスタムドメイン名のルーティングルールを作成する方法を示しています。
------
#### [ AWS マネジメントコンソール ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. メインのナビゲーションペインから [**Custom Domain Names (カスタムドメイン名)**] を選択します。
1. カスタムドメイン名を選択します。
1. **[ルーティングの詳細]** タブで、**[ルーティングルールを追加]** を選択します。
1. **[新しい条件を追加]** を選択して、新しい条件を追加します。
ヘッダーまたはベースパス条件を追加できます。すべての受信リクエストをカスタムドメイン名に一致させるには、条件を追加しないでください。
1. **[アクション]** で、ドロップダウンを使用してターゲット API とターゲットステージを選択します。
1. [**次へ**] を選択します。
1. 優先度フィールドに、優先度の数値を入力します。
API Gateway は、ルールを優先度順 (低い値から高い値の順) に評価します。
条件なしでルールを作成する場合は、高い値の優先度を使用することをお勧めします。
1. **[ルーティングルールを作成]** を選択します。
------
#### [ AWS CLI ]
次の [create-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-routing-rule.html) コマンドは、優先度 50 のルーティングルールを作成します。この例では、API Gateway は、ヘッダー `Hello:World` と `x-version:beta` および ベースパス `PetStoreShopper` を持つ受信リクエストをターゲット API `a1b2c3` にルーティングします。
```
aws apigatewayv2 create-routing-rule \
--domain-name 'api.example.com' \
--priority 50 \
--conditions '[
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
]'\
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod"
}
}
]'
```
出力は次のようになります。
```
{
"Actions": [
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": false
}
}
],
"Conditions": [
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
],
"Priority": 50,
"RoutingRuleArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/api.example.com/routingrules/abc123",
"RoutingRuleId": "abc123"
}
```
------
## ルーティングルールの優先度を変更する
ルーティングルールの優先度は変更できます。これはすぐに有効になり、API コンシューマーがカスタムドメイン名を呼び出す方法に影響を与える可能性があります。ルーティングルールの優先順位を設定するときは、ルール間に間隔を空けておくことをお勧めします。
例えば、優先度が 50 のルール `abc123` と優先度が 150 のルール `zzz000` の 2 つのルーティングルールについて考えます。API Gateway が最初にルール `zzz000` を評価するようにルールの優先度を変更するには、ルール `zzz000` の優先度を 30 に変更できます。
------
#### [ AWS マネジメントコンソール ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. メインのナビゲーションペインから [**Custom Domain Names (カスタムドメイン名)**] を選択します。
1. カスタムドメイン名を選択します。
1. **[ルーティングの詳細]** タブで、ルーティングルールを選択し、**[編集]** を選択します。
1. [**次へ**] を選択します。
1. 優先度に、新しい優先度を入力します。
1. **[Save changes]** (変更の保存) をクリックします。
------
#### [ AWS CLI ]
次の [put-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/put-routing-rule.html) コマンドは、ルーティングルール `abc123` の優先度を変更します。
```
aws apigatewayv2 put-routing-rule \
--domain-name 'api.example.com' \
--priority 30 \
--routing-rule-id abc123 \
--conditions '[
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
]'\
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod"
}
}
]'
```
出力は次のようになります。
```
{
"Actions": [
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": false
}
}
],
"Conditions": [
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
],
"Priority": 38,
"RoutingRuleArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/api.example.com/routingrules/abc123",
"RoutingRuleId": "abc123"
}
```
------
# ルーティングルールを使用して API マッピングを再作成する
ルーティングルールを使用して API マッピングを再作成できます。API マッピングを再作成するには、必ずベースパスストライピングをオンにしてください。これにより、API マッピングの動作が保持されます。詳細については、「[ベースパス条件を使用してベースパスを削除する](rest-api-routing-rules.md#rest-api-routing-rules-condition-path-split)」を参照してください。
次のチュートリアルでは、API マッピング `https:// api.example.com/orders/v2/items/categories/5` をルーティングルールとして再作成する方法と、API Gateway が API にトラフィックを送信するために使用するルーティングルール ID をログに記録するようにアクセスログを更新する方法を示します。
------
#### [ AWS マネジメントコンソール ]
**ルーティングモードを ROUTING\$1RULE\$1THEN\$1API\$1MAPPING に設定するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. メインのナビゲーションペインから [**Custom Domain Names (カスタムドメイン名)**] を選択します。
1. カスタムドメイン名を選択します。
1. **[ドメインの詳細]** で、**[編集]** を選択します。
1. **[ルーティングモード]** で、**[ROUTING\$1RULE\$1THEN\$1API\$1MAPPING]** を選択します。
1. **[保存]** を選択します。
ルーティングモードを設定したら、ルーティングルールを作成します。
**ルーティングルールを作成するには**
1. **[ルーティングの詳細]** タブで、**[ルーティングルールを追加]** を選択します。
1. **[新しい条件を追加]** を選択してから、**[パス]** を選択します。
1. **[パス]** には、**orders/v2/items/categories/5** を入力します。
1. **[ベースパスをストリップ]** で、**[アクティブ]** を選択します。
1. **[ターゲット API]** で、ターゲット API を選択します。
1. **[ターゲットステージ]** で、ターゲットステージを選択します。
1. [**次へ**] を選択します。
1. 優先度には、優先度を入力します。
既存の API マッピングを保持していても、ルーティングルールは常に API マッピングよりも優先されるため、API Gateway は常に新しいルーティングルールを使用します。
1. **[Save changes]** (変更の保存) をクリックします。
ルーティングルールを作成したら、ステージのアクセスログ形式を更新するか、新しいログを作成して、API Gateway がルーティングルールを使用して API にトラフィックを送信することを確認します。
**アクセスログを更新するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. API を選択します。
1. メインナビゲーションペインで、**[ステージ]** を選択します。
1. **[ログとトレース]** で、**[編集]** を選択します。
ロググループがない場合は、「[API Gateway で REST API の CloudWatch ログ記録を設定する](set-up-logging.md)」を参照してください。
1. **\$1context.customDomain.routingRuleIdMatched** をログ形式に追加します。
このロググループは、API Gateway が API へのトラフィックの送信に使用したルーティングルール ID を記録します。詳細については、「[API Gateway が API にトラフィックを送信した方法がわからない](rest-api-routing-rules-troubleshoot.md#rest-api-routing-rules-logging)」を参照してください。
1. **[保存]** を選択します。
アクセスログを更新したら、カスタムドメイン名を呼び出します。以下は、ベースパス `orders/v2/items/categories/5` を使用してカスタムドメイン名 `https://api.example.com` を呼び出す curl コマンドの例です。
```
curl "https://api.example.com/orders/v2/items/categories/5"
```
カスタムドメイン名を正常に呼び出したら、CloudWatch Logs に `routingRuleIdMatched` が表示されていることを確認します。CloudWatch Logs コンソールを使用してロググループを表示する方法については、「[CloudWatch コンソールで API Gateway のログイベントを表示する](view-cloudwatch-log-events-in-cloudwatch-console.md)」を参照してください。
------
#### [ AWS CLI ]
1. 次の [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) コマンドを使用して、ルーティングモード `ROUTING_RULE_THEN_API_MAPPING` を使用するようにドメイン名 `api.example.com` を更新します。
```
aws apigatewayv2 update-domain-name \
--domain-name 'api.example.com' \
--routing-mode ROUTING_RULE_THEN_API_MAPPING
```
1. 次の [create-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-routing-rule.html) コマンドを使用して、API マッピング `https://api.example.com/orders/v2/items/categories/5` を再作成する新しいルーティングルールを作成します。
```
aws apigatewayv2 create-routing-rule \
--domain-name 'api.example.com' \
--priority 50 \
--conditions '[
{
"MatchBasePaths": {
"AnyOf": [
"orders/v2/items/categories/5"
]
}
}
]' \
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": true
}
}
]'
```
1. 次の [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) コマンドを使用して、`$context.customDomain.routingRuleIdMatched` 変数を含めるようにアクセスログ形式を更新します。この変数は、API Gateway が API へのトラフィックの送信に使用したルーティングルール ID を記録します。このログを使用して、API Gateway がルーティングルールを使用して API にトラフィックを送信することを確認します。詳細については、「[API Gateway が API にトラフィックを送信した方法がわからない](rest-api-routing-rules-troubleshoot.md#rest-api-routing-rules-logging)」を参照してください。
```
aws apigateway update-stage \
--rest-api-id a1bc2c3 \
--stage-name prod \
--patch-operations "op=replace,path=/accessLogSettings/format,value='\$context.path \$context.customDomain.routingRuleIdMatched \$context.requestId \$context.extendedRequestId'"
```
ロググループがない場合は、「[API Gateway で REST API の CloudWatch ログ記録を設定する](set-up-logging.md)」を参照してください。
1. 次の curl コマンドの例を使用して、ベースパス `orders/v2/items/categories/5` でカスタムドメイン名を呼び出します。
```
curl "https://api.example.com/orders/v2/items/categories/5
```
1. 次の [filter-log-events](https://docs.aws.amazon.com/cli/latest/reference/logs/filter-log-events.html) コマンドを使用して、ルーティングルール ID `abc123` を含むロググループ `access-log-group-orders` からログイベントを取得します。
```
aws logs filter-log-events --log-group-name access-log-group-orders --filter-pattern abc123
```
これにより、API Gateway がルーティングルールを使用して API にトラフィックを送信したことを確認します。
------
# ルーティングルールに関する問題のトラブルシューティング
次のトラブルシューティングガイダンスは、ルーティングルールの問題を解決するのに役立ちます。
## API Gateway が API にトラフィックを送信した方法がわからない
REST API ステージのアクセスログを使用して、ルーティングルールのログ記録とトラブルシューティングを行うことができます。`$context.customDomain.routingRuleIdMatched` 変数を使用して、API Gateway が API へのトラフィックの送信に使用したルーティングルール ID を表示できます。API Gateway が API へのトラフィックの送信に使用した API マッピングを表示するには、`$context.customDomain.basePathMatched` 変数を使用します。
ルーティングルールをログに記録するには、アカウントに[適切な CloudWatch Logs ロール](set-up-logging.md#set-up-access-logging-permissions) ARN を設定し、ロググループを作成する必要があります。
次のアクセスロググループの例では、ルーティングルールと API マッピングのトラブルシューティングに関連する情報を取得できます。API Gateway は、使用したルーティングメカニズムのコンテキスト変数のみを入力します。それ以外の場合、コンテキスト変数は `-` です。
------
#### [ CLF ]
```
$context.path $context.customDomain.routingRuleIdMatched $context.customDomain.basePathMatched $context.requestId $context.extendedRequestId
```
------
#### [ JSON ]
```
{"requestPath": "$context.path", "routingRuleId" : "$context.customDomain.routingRuleIdMatched", "API mapping" : "$context.customDomain.basePathMatched", "requestId":"$context.requestId", "extendedRequestId":"$context.extendedRequestId"}
```
------
#### [ XML ]
```
$context.path $context.customDomain.routingRuleIdMatched $context.customDomain.basePathMatched $context.extendedRequestId
```
------
#### [ CSV ]
```
$context.path,$context.customDomain.routingRuleIdMatched,$context.customDomain.basePathMatched,$context.requestId,$context.extendedRequestId
```
------
また、カスタムドメイン名のルーティングモードを確認することをお勧めします。詳細については、「[カスタムドメイン名のルーティングモードを設定する](set-routing-mode.md)」を参照してください。
## カスタムドメイン名でルーティングルールを有効にできない
API Gateway から次のエラーが表示される場合があります。
```
Your account doesn’t have permission to use RoutingRules.
This might be caused by an IAM policy in your account with a deny statement on BasePathMapping or ApiMapping.
To grant permission for this account to use RoutingRules, use the UpdateAccount API.
This will impact any existing IAM policies that deny access to BasePathMapping or ApiMapping.
See API Gateway documentation for further details.
```
[BasePathMapping](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonapigatewaymanagement.html#amazonapigatewaymanagement-resources-for-iam-policies) または [ApiMapping](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonapigatewaymanagementv2.html#amazonapigatewaymanagementv2-resources-for-iam-policies) へのアクセスを拒否する IAM ポリシーがある場合、このエラーが発生します。カスタムドメイン名のルーティングルールを有効にすると、ポリシーは `BasePathMapping` または `ApiMapping` へのアクセスを拒否し続けますが、同じポリシーを使用して `RoutingRule` にアクセスできます。これにより、ユーザーはカスタムドメイン名のルーティング動作を変更できます。
例えば、次のようなポリシーがある場合です。
```
{
"Sid": "DenyCreatingApiMappings",
"Effect": "Deny",
"Action": "apigateway:POST",
"Resource": [
"arn:aws:apigateway:us-west-2::/domainnames/example.com/apimappings"
]
}
```
`example.com` のルーティングルールを有効にすると、このポリシーは `ApiMapping` の作成へのアクセスを拒否し続けますが、`RoutingRule` の作成へのアクセスを拒否しません。
アカウントの IAM ポリシーを監査することをお勧めします。次のポリシー例では、`ApiMapping`、`BasePathMapping`、および `RoutingRule` の作成へのアクセスを拒否します。
```
{
"Sid": "DenyCreatingBasePathMappingsApiMappings",
"Effect": "Deny",
"Action": "apigateway:POST",
"Resource": [
"arn:aws:apigateway:us-west-2::/domainnames/example.com/basepathmappings",
"arn:aws:apigateway:us-west-2::/domainnames/example.com/apimappings"
]
},
{
"Sid": "DenyCreatingRoutingRules",
"Effect": "Deny",
"Action": "apigateway:CreateRoutingRule",
"Resource": [
"arn:aws:apigateway:us-west-2:111122223333:/domainnames/example.com/routingrules/*"
]
}
```
すべてのポリシーが更新されたことが確認されたら、API のアカウントレベルの設定を更新して、リージョンのルーティングルールを有効にできます。
次の [update-account](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html) コマンドを使用して、リージョンの API のアカウントレベル設定を更新します。
```
aws apigateway update-account --patch-operations 'op=remove,path=/features,value=BlockedForRoutingRules' --region us-west-2
```
API のアカウントレベルの設定を更新したら、カスタムドメイン名のルーティングモードを変更できます。IAM ポリシーを引き続き使用して、`RoutingRules`、`ApiMapping`、または `BasePathMapping` へのアクセスを拒否することもできます。
# API マッピングを使用して、API ステージを REST API のカスタムドメイン名に接続します。
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)」を参照してください。
## カスタムドメイン名への受信リクエスト
カスタムドメイン名を 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 リクエストのマッピング
以下に、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` を選択します。 |
## 制限事項
+ 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 マッピングを作成する
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
```
------
# API Gateway のカスタムドメイン名の IP アドレスタイプ
カスタムドメイン名を作成する場合、ドメインを呼び出すことができる 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 アドレスタイプに関する考慮事項
以下の考慮事項は、IP アドレスタイプの使用に影響する可能性があります。
+ パブリック API の API Gateway カスタムドメイン名のデフォルトの IP アドレスタイプは IPv4 です。
+ プライベートカスタムドメイン名は、デュアルスタック IP アドレスタイプのみを指定できます。
+ カスタムドメイン名には、マッピングされたすべての API で同じ IP アドレスタイプを使用する必要はありません。デフォルトの 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/apigateway/update-domain-name.html) コマンドは、IP アドレスタイプがデュアルスタックになるように API を更新します。
```
aws apigateway update-domain-name \
--domain-name dualstack.example.com \
--patch-operations "op='replace',path='/endpointConfiguration/ipAddressType',value='dualstack'"
```
出力は次のようになります。
```
{
"domainName": "dualstack.example.com",
"certificateUploadDate": "2025-02-04T14:46:10-08:00",
"regionalDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com",
"regionalHostedZoneId": "Z3LQWSYCGH4ADY",
"regionalCertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/a1b2c3d4-5678-90ab-cdef",
"endpointConfiguration": {
"types": [
"REGIONAL"
],
"ipAddressType": "dualstack"
},
"domainNameStatus": "AVAILABLE",
"securityPolicy": "TLS_1_2",
"tags": {}
}
```
------
# API Gateway でカスタムドメインのセキュリティポリシーを選択する
*セキュリティポリシー*は、API Gateway が提供する TLS の最小バージョンと暗号スイートの事前定義された組み合わせです。クライアントが API またはカスタムドメイン名への TLS ハンドシェイクを確立すると、セキュリティポリシーにより、API Gateway で受け入れられる TLS バージョンと暗号スイートが適用されます。セキュリティポリシーは、クライアントとサーバー間の改ざんや盗聴などのセキュリティの問題から API とカスタムドメイン名を保護します。
API Gateway は、レガシーセキュリティポリシーと拡張セキュリティポリシーをサポートしています。`TLS_1_0` および `TLS_1_2` はレガシーセキュリティポリシーです。これらのセキュリティポリシーを一般化されたワークロードに使用するか、API の作成を開始します。`SecurityPolicy_` で始まるポリシーは、拡張セキュリティポリシーです。これらのポリシーは、規制対象のワークロード、高度なガバナンス、またはポスト量子暗号化に使用します。拡張セキュリティポリシーを使用する場合は、追加のガバナンスのためにエンドポイントアクセスモードも設定する必要があります。詳細については、「[エンドポイントアクセスモード](apigateway-security-policies.md#apigateway-security-policies-endpoint-access-mode)」を参照してください。
## 考慮事項
API Gateway の REST API のカスタムドメイン名のセキュリティポリシーに関する考慮事項を次に示します。
+ 拡張セキュリティポリシーを使用するドメイン名で相互 TLS を有効にすることはできません。
+ 拡張セキュリティポリシーを使用するドメイン名に HTTP API をマッピングすることはできません。
+ 拡張セキュリティポリシーを使用する REST API へのマルチレベルベースパスマッピングを有効にすると、同じドメイン名の HTTP API へのベースパスマッピングを作成することはできません。
+ API は、その API とは異なるセキュリティポリシーのカスタムドメイン名にマッピングできます。そのカスタムドメイン名を呼び出すと、API Gateway は API のセキュリティポリシーを使用して TLS ハンドシェイクをネゴシエートします。デフォルトの API エンドポイントを無効にすると、発信者が API を呼び出す方法が影響を受ける可能性があります。
+ API Gateway は、すべての API でセキュリティポリシーをサポートしています。ただし、REST API のセキュリティポリシーのみを選択できます。API Gateway は、HTTP または WebSocket API の `TLS_1_2` セキュリティポリシーのみをサポートします。
+ API Gateway は、複数のエンドポイントタイプを持つドメイン名のセキュリティポリシーの更新をサポートしていません。ドメイン名に複数のエンドポイントタイプがある場合は、そのうちの 1 つを削除してセキュリティポリシーを更新します。
## API Gateway がセキュリティポリシーを適用する方法
次の例は、API Gateway が `SecurityPolicy_TLS13_1_3_2025_09` セキュリティポリシーを例として使用してセキュリティポリシーを適用する方法を示しています。
`SecurityPolicy_TLS13_1_3_2025_09` セキュリティポリシーは、TLS 1.3 トラフィックを受け入れ、TLS 1.2 および TLS 1.0 トラフィックを拒否します。TLS 1.3 トラフィックの場合、セキュリティポリシーは次の暗号スイートを受け入れます。
+ `TLS_AES_128_GCM_SHA256`
+ `TLS_AES_256_GCM_SHA384`
+ `TLS_CHACHA20_POLY1305_SHA256`
API Gateway は、他の暗号スイートを受け付けません。例えば、セキュリティポリシーは、`AES128-SHA` 暗号スイートを使用する TLS 1.3 トラフィックを拒否します。
API Gateway へのアクセスに使用した TLS プロトコルと暗号クライアントをモニタリングするには、アクセスログで `$context.tlsVersion` および `$context.cipherSuite` コンテキスト変数を使用できます。詳細については、「[API Gateway で REST API をモニタリングする](rest-api-monitor.md)」を参照してください。
すべての REST API およびカスタムドメイン名のデフォルトのセキュリティポリシーを確認するには、「[デフォルトのセキュリティポリシー](apigateway-security-policies-list.md#apigateway-security-policies-default)」を参照してください。すべての REST API およびカスタムドメイン名でサポートされているセキュリティポリシーを確認するには、「[Supported security policies](apigateway-security-policies-list.md)」を参照してください。
## カスタムドメイン名のセキュリティポリシーを変更する
セキュリティポリシーを変更すると、更新が完了するまでに約 15 分かかります。カスタムドメイン名の `lastUpdateStatus` をモニタリングできます。カスタムドメイン名が更新されると、`lastUpdateStatus` は `PENDING` になり、完了すると `AVAILABLE` になります。
`SecurityPolicy_` で始まるセキュリティポリシーを使用する場合は、エンドポイントアクセスモードもオンにする必要があります。詳細については、「[エンドポイントアクセスモード](apigateway-security-policies.md#apigateway-security-policies-endpoint-access-mode)」を参照してください。
------
#### [ AWS マネジメントコンソール ]
**カスタムドメイン名のセキュリティポリシーを変更するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. REST API にトラフィックを送信するカスタムドメイン名を選択します。
カスタムドメイン名に関連付けられているエンドポイントタイプが 1 つだけであることを確認します。
1. **[カスタムドメイン名設定]** を選択し、**[編集]** を選択します。
1. **[セキュリティポリシー]** で、新しいポリシーを選択します。
1. **[エンドポイントアクセスモード]** で、**[厳格]** を選択します。
1. **[Save changes]** (変更の保存) をクリックします。
------
#### [ AWS CLI ]
次の [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) コマンドは、`SecurityPolicy_TLS13_1_3_2025_09` セキュリティポリシーを使用するようにドメイン名を更新します。
```
aws apigateway update-domain-name \
--domain-name example.com \
--patch-operations '[
{
"op": "replace",
"path": "/securityPolicy",
"value": "SecurityPolicy_TLS13_1_3_2025_09"
},
{
"op": "replace",
"path": "/endpointAccessMode",
"value": "STRICT"
}
]'
```
出力は次のようになります。
```
{
"domainName": "example.com",
"endpointConfiguration": {
"types": [ "REGIONAL" ],
"ipAddressType": "dualstack"
},
"regionalCertificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef",
"securityPolicy": "SecurityPolicy_TLS13_1_3_2025_09",
"endpointAccessMode": "STRICT"
}
```
------
## HTTP API と WebSocket API に関する情報
HTTP API と WebSocket API の詳細については、「[API Gateway での HTTP API のセキュリティポリシー](http-api-ciphers.md)」と「[API Gateway での WebSocket API のセキュリティポリシー](websocket-api-ciphers.md)」を参照してください。
# REST API のデフォルトのエンドポイントを無効にする
デフォルトでは、クライアントは、API Gateway が API 用に生成する `execute-api` エンドポイントを使用して API を呼び出すことができます。クライアントがカスタムドメイン名を使用した場合のみ API にアクセスできるようにするには、デフォルトの `execute-api` エンドポイントを無効にします。クライアントは引き続きデフォルトのエンドポイントに接続できますが、`403 Forbidden` ステータスコードを受け取ります。デフォルトのエンドポイントを無効にすると、API のすべてのステージに影響します。この設定は、ステージでのデプロイの更新など、ステージの設定を更新するときに有効になります。
次の手順では、REST API のデフォルトのエンドポイントを無効にする方法を示します。
------
#### [ AWS マネジメントコンソール ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. REST API を選択します。
1. メインナビゲーションペインで、**[API の設定]** を選択します。
1. APIを選択します。
1. **[API の詳細]** で、**[編集]** を選択します。
1. **[デフォルトのエンドポイント]** で、**[非アクティブ]** を選択します。
1. **[Save changes]** (変更の保存) をクリックします。
1. メインナビゲーションペインで、**[リソース]** を選択します。
1. [**API のデプロイ**] を選択します。
1. API をステージに再デプロイするか、ステージの設定を更新して更新を有効にします。
------
#### [ AWS CLI ]
次の [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) コマンドは、デフォルトのエンドポイントを無効にします。
```
aws apigateway update-rest-api \
--rest-api-id abcdef123 \
--patch-operations op=replace,path=/disableExecuteApiEndpoint,value='True'
```
デフォルトのエンドポイントを無効にした後で、変更を有効にするには、API をデプロイする必要があります。
次の [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) コマンドは、新しいデプロイを作成し、それを以下のステージに関連付けます。
```
aws apigateway create-deployment \
--rest-api-id abcdef123 \
--stage-name dev
```
------
# API Gateway API の DNS フェイルオーバーのカスタムヘルスチェックの設定
Amazon Route 53 ヘルスチェックを使用して、プライマリ AWS リージョンの API Gateway API からセカンダリリージョンの API Gateway API への DNS フェイルオーバーを制御できます。これは、リージョンの問題が発生した場合の影響を軽減するのに役立ちます。カスタムドメインを使用すると、クライアントが API エンドポイントを変更しなくてもフェイルオーバーを実行できます。
エイリアスレコードに対して [[ターゲットのヘルスの評価](https://docs.aws.amazon.com/Route53/latest/APIReference/API_AliasTarget.html#Route53-Type-AliasTarget-EvaluateTargetHealth>Evaluate Target Health)] を選択した場合、それらのレコードが失敗するのは API Gateway サービスがリージョンで利用できない場合だけです。場合によっては、その時間より前に独自の API Gateway API で中断が発生する可能性があります。DNS フェイルオーバーを直接制御するには、API Gateway API のカスタム Route 53 ヘルスチェックを設定します。この例では、オペレーターが DNS フェイルオーバーを制御するのに役立つ CloudWatch アラームを使用します。フェイルオーバーを設定する際のその他の例や考慮事項については、「[Route 53 を使用したディザスタリカバリメカニズムの作成](https://aws.amazon.com/blogs/networking-and-content-delivery/creating-disaster-recovery-mechanisms-using-amazon-route-53/)」と「[AWS Lambdaと CloudWatch を使用して VPC 内のプライベートリソースで Route 53 のヘルスチェックを実行する](https://aws.amazon.com/blogs/networking-and-content-delivery/performing-route-53-health-checks-on-private-resources-in-a-vpc-with-aws-lambda-and-amazon-cloudwatch/)」を参照してください。
**Topics**
+ [前提条件](#dns-failover-prereqs)
+ [ステップ 1 : リソースを設定する](#dns-failover-intial-setup)
+ [ステップ 2: セカンダリリージョンへのフェイルオーバーを開始する](#dns-failover-initiate)
+ [ステップ 3: フェイルオーバーをテストする](#dns-failover-test)
+ [ステップ 4: プライマリリージョンに戻る](#dns-failover-return)
+ [次のステップ: 定期的にカスタマイズしてテストする](#dns-failover-next-steps)
## 前提条件
この手順を完了するには、次のリソースを作成して設定する必要があります。
+ 所有するドメイン名。
+ 2 つの AWS リージョンにある、そのドメイン名の ACM 証明書。詳細については、[カスタムドメイン名の前提条件](how-to-custom-domains.md#how-to-custom-domains-prerequisites) を参照してください。
+ ドメイン名の Route 53 ホストゾーン。詳細については、Amazon Route 53 デベロッパーガイドの「[ホストゾーンの使用](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-working-with.html)」を参照してください。
ドメイン名の Route 53 フェイルオーバー DNS レコードを作成する方法の詳細については、「Amazon Route 53 デベロッパーガイド」の「[ルーティングポリシーの選択](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html)」を参照してください。CloudWatch アラームをモニタリングする方法の詳細については、「Amazon Route 53 デベロッパーガイド」の「[CloudWatch アラームのモニタリング](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/health-checks-creating-values.html#health-checks-creating-values-cloudwatch)」を参照してください。
## ステップ 1 : リソースを設定する
この例では、以下のリソースを作成して、ドメイン名の DNS フェイルオーバーを設定します。
+ 2 つの AWS リージョンにある API Gateway API
+ 2 つの AWS リージョンで同じ名前を持つ API Gateway カスタムドメイン名
+ API Gateway API をカスタムドメイン名に接続する API Gateway API マッピング
+ ドメイン名の Route 53 フェイルオーバー DNS レコード
+ セカンダリリージョンの CloudWatch アラーム
+ セカンダリリージョンの CloudWatch アラームに基づく Route 53 ヘルスチェック
まず、プライマリおよびセカンダリリージョンで、必要なすべてのリソースがあることを確認します。セカンダリリージョンにはアラームとヘルスチェックが含まれている必要があります。これにより、フェイルオーバーの実行についてプライマリリージョンに依存する必要がなくなります。これらのリソースを作成する CloudFormation テンプレートの例については、「[samples/primary.zip](samples/primary.zip)」と「[samples/secondary.zip](samples/secondary.zip)」を参照してください。
**重要**
セカンダリリージョンにフェイルオーバーする前に、必要なリソースがすべて利用可能であることを確認してください。利用可能でない場合、API はセカンダリリージョンのトラフィックに対応することができません。
## ステップ 2: セカンダリリージョンへのフェイルオーバーを開始する
次の例では、スタンバイリージョンが CloudWatch メトリクスを受け取り、フェイルオーバーを開始します。フェイルオーバーを開始するにはオペレーターの介入を必要とするカスタムメトリクスを使用します。
```
aws cloudwatch put-metric-data \
--metric-name Failover \
--namespace HealthCheck \
--unit Count \
--value 1 \
--region us-west-1
```
メトリクスデータを、設定した CloudWatch アラームの対応するデータに置き換えます。
## ステップ 3: フェイルオーバーをテストする
API を呼び出し、セカンダリリージョンからレスポンスがあることを確認します。ステップ 1 でサンプルテンプレートを使用した場合、レスポンスはフェイルオーバー後に `{"message": "Hello from the primary Region!"}` から `{"message": "Hello from the secondary Region!"}` に変わります。
```
curl https://my-api.example.com
{"message": "Hello from the secondary Region!"}
```
## ステップ 4: プライマリリージョンに戻る
プライマリリージョンに戻るには、ヘルスチェックに合格する CloudWatch メトリクスを送信します。
```
aws cloudwatch put-metric-data \
--metric-name Failover \
--namespace HealthCheck \
--unit Count \
--value 0 \
--region us-west-1
```
メトリクスデータを、設定した CloudWatch アラームの対応するデータに置き換えます。
API を呼び出し、プライマリリージョンからレスポンスがあることを確認します。ステップ 1 でサンプルテンプレートを使用した場合、レスポンスは `{"message": "Hello from the secondary Region!"}` から `{"message": "Hello from the primary Region!"}` に変わります。
```
curl https://my-api.example.com
{"message": "Hello from the primary Region!"}
```
## 次のステップ: 定期的にカスタマイズしてテストする
この例は、DNS フェイルオーバーを設定する 1 つの方法を示しています。フェイルオーバーを管理するヘルスチェックには、さまざまな CloudWatch メトリクスまたは HTTP エンドポイントを使用できます。フェイルオーバーメカニズムを定期的にテストして、期待どおりに機能すること、およびオペレーターがフェイルオーバー手順に精通していることを確認します。