本記事は
ネットワークウィーク
7日目の記事です。
💻
6日目
▶▶ 本記事 ▶▶
8日目
🌐
はじめに
こんにちは、井手です。
外はすっかり秋の空気ですが、私のデスク周りだけは常夏です。
モニターとPCが放つ熱気で、今日もひとりサウナ状態。私の席だけは南国仕様です。
最近はAI関連の登壇やブログが続いていましたが、今回は少し趣向を変えて、Amazon API Gateway (以下、API Gateway) について書いてみようと思います。
API Gatewayは、Webアプリケーションなどからのリクエストを受け付け、バックエンドサービスへルーティングするための「入り口」を提供します。その中でも「どのリクエストをどのサービスに送るか」を決めるルーティングルールは、APIの運用において非常に重要です。
このブログでは、API Gatewayのルーティングルールについて、基本的な考え方から具体的な設定例までを整理して紹介します。
前提知識
早速本題！！といきたいところですが、その前に、API Gateway の「ステージ」と「カスタムドメイン」について、おさらいをしておきたいと思います。 これらの概念は、ルーティングの仕組みを理解するうえで非常に重要なポイントです。
まずは、「ステージ」と「カスタムドメイン」がそれぞれどのような役割を持っているのか、順を追って解説していきます。
ステージ
たとえば、「APIに新しい機能を追加したい！」と考えたとします。その際、まず考えるのは、「既存の環境に影響を与えず、安全に開発を進めたい」という点ではないでしょうか。
そこで活躍するのが「ステージ」という仕組みです。
ステージとは、ざっくり言うと、APIを環境やバージョンごとに分けて管理できる仕組みのことを指します。
- devステージ → 開発中の機能を試す環境
- testステージ → テスト用の環境で動作確認
- prodステージ → 実際にユーザーが使う本番環境
このようにステージを分けておくことで、既存環境に影響を与えることなく、安全に開発や検証ができるようになります。
ちなみにですが、API Gatewayでは、バックエンド（Lambdaなど）の設定だけでなく、
- ログ出力の有無
- キャッシュの有効/無効化
- スロットリング（リクエスト制限）
といった項目も、ステージごとに個別に設定することが可能です。
Gitでは、mainブランチをベースにして feature/xxx ブランチを切り、そこに新しい機能の追加や修正をしますよね？
API Gatewayでも同じように、既存のステージ（例：v1）をベースにして、新しいステージ（例：v1-dev）を作成して開発を進めていきます。
カスタムドメイン
ステージでAPIのバージョン管理ができたら、次に考えたいのが 「APIの見せ方」 です。 デフォルトで、API Gatewayは以下のような形式のURLが発行されます。
https://{api-id}.execute-api.{region}.amazonaws.com/{stage}
……うん、AWSらしさ全開のURL構造です。とはいえ、クライアントアプリや外部パートナーに公開するAPIとしては、少しわかりづらく、ブランド性にも欠けるのが正直なところです。
そこで登場するのが、API Gatewayのカスタムドメイン機能です。
ただし、ここでひとつ重要なポイントがあります。
発行したカスタムドメインはAPI Gatewayの「ステージ」ではなく、「API Gateway自体」に対して発行されるという点です。
このステージとの紐づけ作業が、まさに今回取り上げたい「ルーティング」の話です。
ルーティングのモード
さて、前置きが長くなりましたが、ようやく本題です。ここからは、API Gateway に用意されているルーティングのモードについて解説していきます。
API マッピング
まず1つ目はAPIマッピングです。APIマッピングでは、以下のようにURLのパスに基づいて、リクエストを特定のAPIやステージへ振り分けることができます。
- パス : /images/apiv1 ⇒ API : image-api , ステージ: dev-2
- パス : /images/apiv2 ⇒ API : image-api , ステージ : test-2
- パス : /movies ⇒ API : movie-api , ステージ: dev-1
例えば、image-api の test-2 ステージ、test-r-ide リソースにリクエストを送りたいときは、
https://{発行したカスタムドメイン}/images/apiv2/test-r-ideでGet メソッドを実行することができます。
ルーティングルール
次にご紹介するのは、「ルーティングルール」です。こちらは2025 年6月に発表された割と新しめの機能となっています。
このルールは、先ほど紹介したAPIマッピングのパスのルーティングに加え、ヘッダー情報に応じたルーティングも可能になっています。 より柔軟な条件分岐ができるようになったため、APIマッピングよりも高度なルーティング制御を実現できるのが特徴です。
ルーティングルールは、「条件」「アクション」「優先度」の3つの要素で構成されます。
🔹条件（Condition）
ルールが適用されるための判定基準です。 最大で2つのHTTPヘッダー条件と1つのパス条件を組み合わせることができ、これらがすべて一致した場合にルールが発動します。ルールに関しては以下のようなことが設定可能です。
- HTTP ヘッダーはワイルドカード(*)を使用した条件設定ができる
*tst、tst*、*tst*といった部分一致の条件も指定可能- 例. ヘッダーのルールで
*tst*を指定する。
ヘッダーにtstを付与した場合
1. curl -X GET https://{your-custom-domain}/images/test-r-ide \ -H "UserType:tst" >>> { "statusCode": 200, "body": { { "report_id": 5, "report_title": "Hello, World" }, { "report_id": 7, "report_title": "私は井手です。井出じゃないです" } } }
ヘッダーにryota-tstを付与した場合
2. curl -X GET https://{your-custom-domain}/images/test-r-ide \ -H "UserType:ryota-tst" >>> { "statusCode": 200, "body": { { "report_id": 5, "report_title": "Hello, World" }, { "report_id": 7, "report_title": "私は井手です。井出じゃないです" } } }
同じAPI、ステージにルーティングされていることが分かります。
条件なし(ヘッダー、パスの指定なし)のルールを作成できる
- このルールはすべてのリクエストに一致するため、デフォルトのルーティング先として機能します。
パスルールに、ワイルドカードは指定できない
/images-*などの部分一致の指定はできません。
curl -X GET https://{your-custom-domain}/images-ryota/test-r-ide \
-H "UserType:ryota-tst"
>>> {"message":"Missing Authentication Token"}
images-ryotaだと、エラーが発生しています。
curl -X GET https://{your-custom-domain}/images*/test-r-ide \
-H "UserType:ryota-tst"
>>>
{
"statusCode": 200,
"body": {
{
"report_id": 5,
"report_title": "Hello, World"
},
{
"report_id": 7,
"report_title": "私は井手です。井出じゃないです"
}
}
}
images*だと正常なレスポンスが返されています。パスルールにおける*は、単なる文字列として判定されるようです。
🔹アクション（Action）
条件が一致した際に実行される処理です。 リクエストを、どのAPI、どのステージにルーティングするのかをここで設定します。
🔹優先度（Priority）
複数のルールが同時に一致した場合、どのルールを優先するかを決定する数値です。 1〜1,000,000の範囲で設定し、数値が小さいほど優先度が高く、先に評価されます。
ルーティングの活用場面
ここまで、API Gatewayのルーティングルールについて解説してきました。
ヘッダーやパスなどの条件によって、リクエストの振り分けを柔軟に制御できることはご理解いただけましたでしょうか。
こうした条件付きルーティングは、CanaryリリースやBlue/Greenデプロイ、A/Bテストなど、ユーザーごとに異なる環境を用意する必要があるときに、よく活用されます。
次章では、これらの中でも Canaryリリース に焦点を当て、各ルーティングモード（APIマッピング／ルーティングルール）での具体的な実装シナリオを紹介していきたいと思います。
Canary リリース ver API マッピング
- クライアント側のアプリケーションでは、テストユーザーに関連するAPI呼び出しを
ryota-sample.com/dev-2に変更する - 新機能が問題ないか見る
- 新機能が問題なければ、その後、一般ユーザー向けのAPI呼び出しも順次
ryota-sample.com/dev-2に切り替える
この手法では、APIのバージョンが更新されるたび、あるいはAPIの移行が発生するたびに、新たなエンドポイントの指定・発行が必要になることには注意が必要です。そのため、エンドポイントの管理が煩雑になり、運用負荷が高まる可能性があります。
将来的な変更を見越したパス設計を行い、柔軟かつ一貫性のあるパス戦略を策定することが重要と言えるでしょう。
Canary リリース ver ルーティングルール
では、「ルーティングルール」を使用した Canary リリースの実装例を見ていきます。
※ 通常のアクセスは、条件なしルール（優先度は10に設定）によって処理されているとします。
- テストユーザーに、カスタムヘッダー
UserType : Testを付与する - API Gateway側で、
UserType : Testをv2ステージにルーティングするルール(以下、Testルール)を作成する。優先度は、条件なしルールより小さい値に設定する。
→ 優先度の値を低くして、Test ルールを先に評価されるように設定
4. 新機能が問題なければ、条件なしルールの優先度をTestルールより小さい値に、ルーティング先ステージをv2 に変更する
→ 優先度の値を低くして、条件なしルールを先に評価されるように設定
API マッピングと比較して、
- ユーザーごとに専用のエンドポイントを作成する必要がない
- API の移行時にもエンドポイントを変更せずに済む
点が大きな違いでしょうか。
ただし、柔軟なルーティングルールを定義できる反面、ルールの重複や競合が発生しやすくなるリスクもあります。意図しないルーティングを防ぐためにも、ルールの優先順位や条件を明確にし、整理された構成を保つことが重要です。
(番外編) ルーティングルール、その後にAPI マッピング
最後に、これまでの2つの方式を組み合わせた、「ルーティングルール、その後にAPI マッピング」について紹介していきます。 このモードは、既存のルーティング手法から新しい方式へ移行する際に、段階的かつ安全に切り替えを進めたい場合に特に有効です。
例えば、ルーティング手法を「API マッピング」から「ルーティングルール」に変更したいケースを考えていきます。まず、 ルーティングルール＋API マッピングを使用しないケースについて確認していきましょう。
手順としては、
- ルーティングモードを変更
ルーティングモード変更 - その後にルールの詳細条件を指定する
ルーティングのルールを追加する
という流れになります。ただ、注意したいのは、ルーティングモードを変更した時点で、既存のAPI マッピングは無効になるという点です。つまり、ルーティングルール内では、APIマッピングを切り戻し用として設定しておくことは出来ないのです。
切り戻しを行いたい場合は、元のAPI マッピングに戻すことで対応可能です。が、困ったことに「Too Many Requests」エラーが発生することもあり、すぐに切り戻せないケースもあります。
一方でルーティングルール＋ API マッピングを使用すると、既存のAPI マッピングを保持したまま、ルーティングルールを設定することが可能です。
まとめ
今回は、API Gatewayのルーティングに関する3つの手法（APIマッピング、ルーティングルール、ハイブリッド構成）について、それぞれの特徴や注意点、Canaryリリースの実装例を交えてご紹介しました。
特に、ルーティングルールの登場によって、より柔軟で安全なAPI運用が可能になったことは、API開発者にとって大きな助けになるかもしれません。
今後、API Gatewayの構成を見直す際や、新しいルーティング方式への移行を検討する際には、今回の内容が少しでも参考になれば嬉しいです。
執筆者：井手 亮太
職種：インフラエンジニア
推しのサッカー選手：ケビン・デブライネ
執筆記事一覧：https://tech.nri-net.com/archive/author/r-ide-ryota
