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