こんにちは😸
カスタマーサクセス部の山本です。
少し前、2025年6月3日 に API Gateway のREST API で、ルーティングルールが導入されたということです。
こちらが少し気になったので、内容を調べてみることにしました。
概要
この機能を使うと、従来よりも柔軟に、リクエストのパスやヘッダー情報に基づいて、1つのカスタムドメインへのアクセスを複数のAPIステージへ動的に振り分けることができます。
この記事では、新機能「ルーティングルール」の基本的な使い方から、従来の「APIマッピング」との違い、具体的な設定方法までを検証します。
- パスの条件 (
/v1,/v2など) に応じてステージを切り替える方法 - ヘッダーの条件 (
Host:v1.karukozaka46.clickなど) を使ってステージを切り替える方法 - 既存のAPIマッピングからダウンタイムを抑えて新機能へ移行する手順
- 「ベースパスをストリップ」機能の解説
「検証準備」の概要
後の比較検証のため、まずは1つのAPIに「dev-v1」「dev-v2」という2つのステージを作成します。ステージ変数という機能を利用して、アクセスしたステージに応じて、レスポンスに dev-v1 または dev-v2 という文字が表示されるように設定しました。これにより、どちらのステージが呼び出されたかを明確に判別できる環境を準備します。
新機能と比較するため、まず従来の「APIマッピング」機能でルーティングを設定します。ここでは、dev.karukozaka46.click という1つのカスタムドメインに対し、以下のようにパスに基づいてアクセス先を振り分ける設定を行いました。
- パスなし (
/) の場合 →dev-v1ステージ - パスが
/v2の場合 →dev-v2ステージ
検証準備1：API を 1 つ作成し複数のステージを準備する。
サンプルの REST API PetStore を 1つ作成します。
PetStore のリソースを参照し / の GET メソッドの「統合レスポンス」を編集します。 
「マッピングテンプレート」を編集しタイトルの後ろに ${stageVariables.version} を追加します。
ステージ dev-v1 を新規作成しデプロイします。
ステージ dev-v1 にステージ変数を追加します。
キー：version
値：dev-v1
としました。 
ステージの URL にアクセスしてみます。
dev-v1 が表示されます。
次にステージ dev-v2 を新規作成しデプロイします。
ステージ dev-v2 にステージ変数を追加します。
キー：version
値：dev-v2
としました。 
URL にアクセスするとdev-v2 が表示されます。
ステージを複数作成し、ステージ変数によって表示するバージョンを変えるようにできました。
検証準備2：カスタムドメインで API にアクセスできるようにし、従来の 「API マッピング」を試してみる
カスタムドメインを使って API にアクセスできるようにしましょう。
ドメイン名は dev.karukozaka46.click としました。私が Route53 のレジストラに登録しているサンプル用ドメインです。会社所在地の軽子坂が由来です。
「ルーティングモード」に「API マッピングのみ」だけを選択できたのが従来です。まずは従来の構成を検証してみましょう。
Amazon Certificate Manager (ACM) に登録した証明書を選択し、ドメインを追加します。
API の各ステージの URL とは異なる、d- で始まる1 つの URL が発行されました。
Amazon Route 53 のホストゾーンに、レコードを追加しましょう。
| レコード名 | 種別 | 値 |
|---|---|---|
dev.karukozaka46.click |
A(エイリアス) | d-xxxx.execute-api.ap-northeast-1.amazonaws.com |
API マッピングを設定しましょう。
作成した API を選択し、dev-v1 をプルダウンから選択しました。
dev.karukozaka46.click にアクセスすると、ステージ dev-v1 の URL (https://xxxx.execute-api.ap-northeast-1.amazonaws.com/dev-v1) と同じ結果を得られます。
さて、用意したもう一つのステージにも、同じドメインでアクセスできるようにしてみましょう。
API マッピングを追加しましょう。 dev.karukozaka46.click にアクセスすると、dev-v1 のステージを呼び出すようになっているため、同じ設定はできません。 
dev-v2 の方は パス v2 でアクセスするように設定しました。
dev.karukozaka46.click/v2 にアクセスすると、ステージ dev-v2 の URL (https://xxxx.execute-api.ap-northeast-1.amazonaws.com/dev-v2) と同じ結果を得られます。 /v2 がベースパスになるということですね。
ここまでが従来のカスタムドメインの設定になります。
検証：新しい「ルーティングルール」を試してみる パス条件のルール
既存のカスタムドメイン dev.karukozaka46.click を編集して、「API マッピング」ではなく「ルーティングルール」を使用してみましょう。
運用環境での変更時の注意点も見つけながら簡単に試してみました
「ルーティングルールのみ (推奨)」と「ルーティングルール、その後に API マッピング」があります。
後者は少し複雑なので、まずは AWS も推奨の「ルーティングルールのみ (推奨)」を試しました。
変更時には「ルーティングルール」を追加はできず、かつ変更直後はルーティングルールがありません。そして、既存の API マッピングは削除されています。
これにより、カスタムドメインへのアクセスはエラーになりました。
エラー： 
なお、もとに戻そうと思ってすぐに修正すると、Too many requests とエラーになることもあるため、2-3 分待つ必要がありました。
回避策
「ルーティングルール、その後に API マッピング」に変更する場合は、先に設定した 「API マッピング」の内容を保持しています。
運用中に「APIマッピング」から「ルーティングルール」に変更する際に影響を最小限にしたい場合は以下のフローが良いかと思います。
- 「ルーティングルール、その後に API マッピング」に変更して API マッピングを保持
- ルーティングルールを追加。API マッピングよりも ルーティングルールが優先になります。
- 「ルーティングルールのみ（推奨）」に変更し API マッピングを削除。このとき 2 で設定したルーティングルールが保持されています。
1 の画面です。
設定後は最初に設定した API マッピングが保持されています。
したがって、変更後も元のコンテンツを返却します。
2 (ルーティングルールを追加) の画面です。
ルーティングルールを追加し、パス version2 にリクエストすると dev-v2 にアクセスするようにします。「ベースパスをストリップ」を選択すると、バックエンドへのリクエスト時に /version2 を削除してくれます。詳細は後述します。 
優先度を設定します。ルールが複数ある場合、ここで優先度を設定できます。なお、既存の 「API マッピング」は一番最後に評価されます。
パス version2 にリクエストすると dev-v2 にアクセスできました。
3 (「ルーティングルール」に変更し API マッピングを削除) の画面です。
変更したため、/version2 宛の通信しか受け付けなくなりました。
API マッピングの設定ではアクセスできなくなっています。
「ルーティングルール」で設定した/version2 宛のアクセスは可能なままです。
このような形で、影響を最小限にしつつ、「API マッピング」から「ルーティングルール」に移行できそうです。
「ベースパスをストリップ」
- 有効の場合 (
true): マッチしたベースパスを削除して、残りのパスだけをバックエンドに送ります。 - 無効の場合 (
false): ベースパスを含んだまま、URL全体をバックエンドに送ります。
例：ベースパスをストリップが無効のとき
パス /version2 へのリクエストが ステージ dev-v2 を呼び出すようにします。
「ベースパスをストリップ」は無効（チェックなし）にします。
無効（チェックなし）のときは、ステージ dev-v2 のリソース /version2 にあるメソッドが呼び出されます。
以下部分のメソッドが呼ばれます。
ステージ dev-v2 の /version2 の GET メソッドでは Lambda 関数を呼び出しています。
例：ベースパスをストリップが有効のとき
「ベースパスをストリップ」は有効（チェックあり）に変更します。
有効（チェックあり）のときは、ステージ dev-v2 のリソース / にあるメソッドが呼び出されます。
以下部分のメソッドが呼ばれます。
ステージ dev-v2 の / の GET メソッドは本記事の準備段階で設定したものです。
API マッピングではベースパスはデフォルトでストリップされる
API マッピングを検証した章で以下のように述べた通り、ベースパスはストリップされます。
dev.karukozaka46.click/v2 にアクセスすると、ステージ dev-v2 の URL (https://xxxx.execute-api.ap-northeast-1.amazonaws.com/dev-v2) と同じ結果を得られます。 /v2 がベースパスになるということですね。
新しい「ルーティングルール」の基本
ルーティングルールは、「条件」「アクション」「優先度」の3つの要素で構成されます。
- 条件: ルールが適用されるための基準です。最大2つのヘッダー条件と1つのパス条件を組み合わせることができます。条件がないルールも作成でき、これはすべてのリクエストに一致する「包括的なルール」として機能します。
- アクション: 条件が一致した場合に実行される処理です。現在は「REST APIのステージを呼び出す」ことのみがサポートされています。
- 優先度: ルールが評価される順序を1から1,000,000の数値で決定します。数値が小さいほど優先度が高く、先に評価されます。
条件の詳細
- ヘッダー条件:
Hello:Worldのように、リクエストヘッダーの名前と値を指定します。ヘッダー名の大文字/小文字は区別されませんが、値は区別されます。値にはワイルドカード（*）を使用して、前方一致、後方一致、部分一致を指定できます。 - ベースパス条件:
/usersのように、リクエストURLのパスを指定します。大文字/小文字は区別されます。パスを一致させた後、そのパス部分を削除してターゲットAPIにリクエストを転送するオプションもあります。
ルールの評価方法
API Gatewayは、設定されたモードに応じてルールを評価します。
ROUTING_RULE_ONLYモード（マネジメントコンソールでは「ルーティングルールのみ (推奨)」）: ルーティングルールのみを評価します。ROUTING_RULE_THEN_API_MAPPINGモード（マネジメントコンソールでは「ルーティングルール、その後に API マッピング」）:- まず、優先度の高い（数値が小さい）順にすべてのルーティングルールを評価します。
- 一致するルールが見つかった時点で、そのルールのアクションを実行し、評価を終了します。
- どのルーティングルールにも一致しなかった場合、次にAPIマッピングを評価します。
- どちらにも一致しない場合、リクエストは拒否されます（403 Forbidden）。
ヘッダー条件のルールを試してみる。
カスタムドメインにワイルドカードドメインを設定し、ルーティングルールでホストヘッダにより宛先となるステージを変える
- ワイルドカード証明書の準備
- API Gatewayでワイルドカードカスタムドメインを作成
Hostヘッダーを条件にしたルーティングルールを作成
1. 証明書の準備
まず、*.karukozaka46.click をカバーするSSL/TLS証明書が必要です。
2. ワイルドカードカスタムドメインの作成
次に、API Gatewayのコンソールでカスタムドメイン名を作成します。
- ドメイン名:
*.karukozaka46.clickと入力します。 - ACM証明書: ステップ1で準備した
*.karukozaka46.clickの証明書を選択します。
作成後、API Gatewayから割り当てられたドメイン名（例: d-abcdef123.execute-api.ap-northeast-1.amazonaws.com）を、お使いのDNSサービス（Amazon Route 53など）で *.karukozaka46.click の Aレコード（エイリアス）として登録します。
3. ルーティングルールの作成
作成したカスタムドメインの「APIマッピング」タブで、APIへのルーティングルールを設定します。
v1.karukozaka46.click と v2.karukozaka46.click で別々のAPIにルーティングするためのルールを以下のように作成します。
ルール1: v1.karukozaka46.click を dev-v1 へ
- 優先度:
10（小さいほど優先） - 条件:
- タイプ: ヘッダー
- ヘッダー名:
Host - 値:
v1.karukozaka46.click
- アクション (ターゲット): dev-v1 ステージ
ルール2: v2.karukozaka46.click を dev-v2 へ
- 優先度:
20（小さいほど優先） - 条件:
- タイプ: ヘッダー
- ヘッダー名:
Host - 値:
v2.karukozaka46.click
- アクション (ターゲット): dev-v2 ステージ
（推奨）ルール3: それ以外をデフォルトAPIへ
- 優先度:
100（一番最後） - 条件: なし（すべてのリクエストに一致）
- アクション (ターゲット): デフォルトのステージ
動作確認
v1.karukozaka46.click
v2.karukozaka46.click
まとめ
本記事では、2025年6月にリリースされたAPI GatewayのREST APIにおける新機能「ルーティングルール」について、その概要から具体的な設定方法、そして従来の「APIマッピング」との違いまでを詳しく検証しました。
この新機能の最大の特長は、リクエストのパスやヘッダー情報を柔軟に組み合わせた条件で、単一のカスタムドメインへのアクセスを複数のAPIステージへ動的にルーティングできる点にあります。
今回の検証を通して、以下のことが確認できました。
- パス条件によるルーティング:
/v1や/v2といったパスに基づいて、簡単に異なるバージョンのステージへ振り分けることができました。 - ヘッダー条件による高度なルーティング:
Hostヘッダーを利用したサブドメインごとの振り分けに加え、例えば「Hostヘッダーがv1.karukozaka46.clickで、かつカスタムヘッダーX-Env-Typeにdevという値が含まれる場合は開発ステージに送る」といった、複数の条件を組み合わせたさらに高度なルーティングも可能です。 - 安全な移行手順: 既存の「APIマッピング」を利用している環境から、ダウンタイムを最小限に抑えながら新機能へ移行するための具体的なステップも確認できました。
- 便利な「ベースパスをストリップ」機能: このオプションを活用することで、バックエンドのAPI実装をシンプルに保てる点も大きなメリットです。
「ルーティングルール」は、APIのバージョン管理、Blue/Greenデプロイメント、あるいは特定の利用者向けの新機能を先行リリースするカナリアテストなど、これまで複雑な設定が必要だった様々なユースケースを、よりシンプルかつ強力に実現する機能です。API Gatewayをご利用の際は、ぜひこの新しいルーティング機能を活用してみてください。
余談
そろそろ紅葉ですね。好きな仙ノ倉山です。
コメント