URL マップの概要

Google Cloud アプリケーションロードバランサと Cloud Service Mesh は、URL マップと呼ばれる Google Cloud構成リソースを使用して、HTTP(S) リクエストをバックエンドサービスまたはバックエンドバケットに転送します。

たとえば、外部アプリケーションロードバランサでは、1 つの URL マップを使用して、URL マップで構成されたルールに基づいてリクエストを異なる宛先に転送できます。

https://example.com/video のリクエストは 1 つのバックエンドサービスに送信されます。
https://example.com/audio のリクエストは別のバックエンドサービスに送信されます。

https://example.com/images のリクエストは Cloud Storage バックエンドバケットに送信されます。

他のホストとパスの組み合わせに対するリクエストは、デフォルトのバックエンドサービスに送信されます。

URL マップは、次の Google Cloud プロダクトで使用されます。

外部アプリケーションロードバランサ（グローバル、リージョン、従来）
内部アプリケーションロードバランサ（クロスリージョンモードとリージョンモード）
Cloud Service Mesh（Cloud Service Mesh がロードバランシング API を使用してデプロイされている場合）

URL マップリソースには、グローバルとリージョンの 2 種類があります。

グローバル urlMaps は、グローバル外部アプリケーションロードバランサ、従来のアプリケーションロードバランサ、クロスリージョン内部アプリケーションロードバランサ、Cloud Service Mesh で使用されます。
regionUrlMaps は、リージョン外部アプリケーションロードバランサ、リージョン内部アプリケーションロードバランサ、Cloud Service Mesh で使用されます。

使用するリソースのタイプは、プロダクトのロードバランシングスキームによって異なります。

プロダクト	負荷分散スキーム	URL マップのリソースタイプ	選択できる宛先
グローバル外部アプリケーションロードバランサ	`EXTERNAL_MANAGED`	グローバル	バックエンドサービス、バックエンドバケット
従来のアプリケーションロードバランサ	`EXTERNAL`	グローバル	バックエンドサービス、バックエンドバケット
リージョン外部アプリケーションロードバランサ	`EXTERNAL_MANAGED`	リージョン	バックエンドサービス
クロスリージョン内部アプリケーションロードバランサ	`INTERNAL_MANAGED`	グローバル	バックエンドサービス
リージョン内部アプリケーションロードバランサ	`INTERNAL_MANAGED`	リージョン	バックエンドサービス
Cloud Service Mesh	`INTERNAL_SELF_MANAGED`	グローバル	バックエンドサービス
Cloud Service Mesh	`INTERNAL_SELF_MANAGED`	リージョン	バックエンドサービス

すべてのプロダクトで、すべての URL マップ機能が利用できるわけではありません。グローバル外部アプリケーションロードバランサ、リージョン外部アプリケーションロードバランサ、内部アプリケーションロードバランサ、Cloud Service Mesh で使用される URL マップは、いくつかの高度なトラフィック管理機能もサポートしています。これらの違いの詳細については、ロードバランサの機能比較: ルーティングとトラフィック管理をご覧ください。また、リージョン URL マップは、App Hub アプリケーションでサービスとして指定されているリソースにすることもできます。

URL マップの仕組み

リクエストを受信すると、ロードバランサは URL マップで定義されたルールに基づいて特定のバックエンドサービスまたはバックエンドバケットにリクエストをルーティングします。

バックエンドサービスは、アプリケーションまたはマイクロサービスのインスタンスであるバックエンドのコレクションを表します。バックエンドバケットは、Cloud Storage バケットであり、一般的に画像などの静的コンテンツをホストするために使用されます。

リージョン外部アプリケーションロードバランサ、内部アプリケーションロードバランサ、Cloud Service Mesh の場合、宛先は次のようになります。

デフォルトのバックエンドサービス
デフォルト以外のバックエンドサービス

また、グローバル外部アプリケーションロードバランサは、以下をサポートします。

デフォルトのバックエンドバケット
デフォルト以外のバックエンドバケット

たとえば、次のような設定があるとします。

1 つの IP アドレス
- 組織へのリクエストはすべて同じ IP アドレスと同じロードバランサに転送されます。
- トラフィックは、リクエストの URL に基づいてさまざまなバックエンドサービスに転送されます。
2 つのドメイン
- example.net（トレーニング動画をホスト）
- example.org（組織のウェブサイトをホスト）
4 つのサーバーセット
- 組織のウェブサイトをホスト（バックエンドサービス: org-site）
- トレーニング動画のウェブサイト全体をホスト（バックエンドサービス: video-site）
- 高画質（HD）のトレーニング動画をホスト（バックエンドサービス: video-hd）
- 標準画質（SD）のトレーニング動画をホスト（バックエンドサービス: video-sd）

次の処理を行うとしています。

example.org（または、example.net 以外のドメイン）へのリクエストが org-site バックエンドサービスに送信される。
より具体的なパスと一致しない example.net へのリクエストが video-site バックエンドサービスに送信される。
example.net/video/hd/* へのリクエストが video-hd バックエンドサービスに送信される。
example.net/video/sd/* へのリクエストが video-sd バックエンドサービスに送信される。

/video/* の --path-rule は、/video/test1 や /video/test2 などの URI と一致します。パス /video とは一致しません。

ロードバランサが URL に /../ が含まれるリクエストを受信すると、ロードバランサは .. の前のパスセグメントを削除して URL を変換し、変換された URL を使用して応答します。たとえば、http://example.net/video/../abc に対するリクエストが送信されると、ロードバランサは http://example.net/abc への 302 リダイレクトを返します。ほとんどのクライアントは、ロードバランサによって返された URL（この場合は http://example.net/abc）にリクエストを発行して対応します。この 302 リダイレクトは Cloud Logging に記録されません。

URL マップでは、このタイプのホストとパスベースのルーティングを設定できます。

バックエンドサービスの設定例。 — バックエンドサービスの設定例（クリックして拡大）

ロードバランサの命名

アプリケーションロードバランサの場合、ロードバランサの名前は常に URL マップの名前と同じです。各 Google Cloud インターフェースの動作は次のとおりです。

Google Cloud コンソール。Google Cloud コンソールを使用してアプリケーションロードバランサを作成すると、ロードバランサ名として入力した名前と同じ名前が URL マップに自動的に割り当てられます。
Google Cloud CLI または API。gcloud CLI または API を使用してアプリケーションロードバランサを作成する場合は、URL マップの作成時に任意の名前を入力します。この URL マップの名前がGoogle Cloud コンソールでロードバランサの名前として反映されます。

プロキシネットワークロードバランサとパススルーネットワークロードバランサの命名の仕組みについては、バックエンドサービスの概要: ロードバランサの命名をご覧ください。

URL マップのコンポーネント

URL マップは、URL のリクエストをバックエンドサービスまたはバックエンドバケットに転送する一連の Google Cloud 構成リソースです。URL マップは、処理する URL ごとにホスト名とパスの部分を使用します。

ホスト名は URL のうちのドメイン名の部分です。たとえば、http://example.net/video/hd という URL のホスト名の部分は example.net です。
パスは、ホスト名とポート番号（省略可能）に続く URL の一部です。たとえば、http://example.net/video/hd という URL のパス部分は /video/hd です。

基本的な URL マップを使用したロードバランサの構成。 — 基本的な URL マップによるロードバランサ構成（クリックして拡大）

この図は、ロードバランシング構成オブジェクト同士の関係を示しています。

受信リクエストを転送するバックエンドサービスまたはバックエンドバケットは、次の URL マップ構成パラメータで制御します。

デフォルトのバックエンドサービスまたはデフォルトのバックエンドバケット。URL マップを作成する際には、デフォルトのバックエンドサービスまたはデフォルトのバックエンドバケットのどちらか一方のみを指定する必要があります。このデフォルトは、該当するホストルールがない場合に、 Google Cloud が任意のホスト名を含む URL のリクエストを転送する宛先のバックエンドサービスまたはバックエンドバケットを表します。

注: バックエンドバケットは、内部アプリケーションロードバランサと Cloud Service Mesh ではサポートされていません。
ホストルール（hostRules）。ホストルールは、1 つ以上の関連付けられたホスト名に送信されたリクエストを単一のパスマッチャー（pathMatchers）に送ります。URL のホスト名の部分は、ホストルールに構成されたホスト名のセットと正確に照合されるか、正規表現を使用して照合されます。URL マップのホストおよびパスルールでホストを省略すると、そのルールはリクエストされたすべてのホストと一致します。http://example.net/video/hd へのリクエストをパスマッチャーに送るには、少なくとも example.net というホスト名を含むホストルールが必要です。この同じホストルールで他のホスト名へのリクエストを処理することもできますが、それらのリクエストは同じパスマッチャーに送られます。

リクエストを別のパスマッチャーに送る場合は、別のホストルールを使用する必要があります。URL マップ内の 2 つのホストルールに同じホスト名を含めることはできません。

ホストルールでワイルドカード文字 * を指定すると、すべてのホスト名と一致するようにできます。たとえば、http://example.org、http://example.net/video/hd、http://example.com/audio という URL の場合は、ホストルールに * を指定すると、example.org、example.net、example.com の 3 つのホスト名すべてに一致します。ワイルドカード文字 * を指定して、ホスト名との部分的な一致を検出することもできます。たとえば、ホストルール *.example.net は news.example.net と finance.example.net の両方のホスト名に一致します。

ポート番号。アプリケーションロードバランサの種類によってポート番号の処理が異なります。内部アプリケーションロードバランサの場合、ホストルール パラメータを使用してポート番号を指定できます。たとえば、ポート 8080 に対する example.net リクエストを転送するには、ホストルールを example.net:8080 に設定します。従来のアプリケーションロードバランサの場合、ホストルールとの一致では URL のホスト名のみが考慮されます。たとえば、ポート 8080 とポート 80 に対する example.net リクエストは、ホストルール example.net と一致します。

注: ロードバランサは、URL のホスト名の値を検証しません。クライアントは、Host ヘッダーを設定するなどして、ホスト名に任意の値を設定できます。アプリケーションのアクセス制御を実装するためには、ホスト名フィールドを使用しないでください。
パスマッチャー（pathMatchers）。パスマッチャーは、ホストルールで参照される構成パラメータです。URL のパス部分と、リクエストを処理するバックエンドサービスまたはバックエンドバケットとの関係を定義します。パスマッチャーは、次の 2 つの要素で構成されます。
- パスマッチャーのデフォルトバックエンドサービスまたはパスマッチャーのデフォルトバックエンドバケット。各パスマッチャーには、少なくともデフォルトのバックエンドサービスまたはデフォルトのバックエンドバケットのどちらか一方のみを指定する必要があります。このデフォルトは、ホスト名がパスマッチャーに関連付けられたホストルールに一致し、かつ、URL パスがパスマッチャーのいずれのパスルールにも一致しない URL のリクエストをGoogle Cloud が転送するバックエンドサービスまたはバックエンドバケットを表します。
- パスルール。パスマッチャーごとに、1 つ以上のパスルールを指定できます。パスルールとは、ある特定の URL パスを単一のバックエンドサービスまたはバックエンドバケットにマッピングする Key-Value ペアです。
  
  柔軟なパターンマッチング演算子により、ワイルドカード構文を使用して URL パスの複数の部分（部分的な URL や接尾辞、ファイル拡張子など）を照合できます。これらの演算子は、複雑な URL パスに基づいてトラフィックのルーティングや書き換えを行う場合に役立ちます。1 つ以上のパスコンポーネントを名前付き変数に関連付けて、URL を書き換える際にそれらの変数を参照することもできます。名前付き変数を使用すると、リクエストがバックエンドに送信される前に、URL コンポーネントを並べ替えたり削除したりできます。詳細については、パスルールにおけるワイルドカード、正規表現、動的 URL をご覧ください。
  
  一意の URL のトラフィックを複数のサービスに転送する場合など、より高度なルーティング機能が必要な場合は、パスルールの代わりにルートルールを使用できます。
- ルートルール。ルートルールは、URL パス、HTTP ヘッダー、クエリパラメータに基づくトラフィックのルーティングのような高度なトラフィックルーティング機能が必要な場合に、パスルールの代わりに使用できます。
  
  ルートルールは、柔軟なパターンマッチング演算子と名前付き変数を使用して構成できます。これらの演算子は、複雑な URL パスに基づいてトラフィックのルーティングや書き換えを行う場合に役立ちます。詳細については、ルートルールのパステンプレートでのワイルドカードとパターンマッチング演算子をご覧ください。
  
  ルートルールを、受信リクエストに含まれるパス、クエリパラメータ、またはヘッダーに一致する正規表現と照合するように構成することもできます。詳細については、ルートルールにおける正規表現をご覧ください。

ホスト名とホストルールの関係

ホスト名は 1 つのホストルールのみを参照できます。
1 つのホストルールで複数のホスト名を処理できます。

ホストルールとパスマッチャーの関係

複数のホストルールで 1 つのパスマッチャーを参照できます。
ホストルールは 1 つのパスマッチャーのみを参照できます。

URL とバックエンドの関係

各 URL は 1 つのバックエンドサービスまたはバックエンドバケットにのみ転送されます。したがって、次のようになります。

Google Cloud は、URL のホスト名部分を使用して、1 つのホストルールと関連するパスマッチャーを選択できます。
パスマッチャーでパスルールを使用する場合、同じパスに対して複数のパスルールを作成することはできません。たとえば、/videos/hd へのリクエストを複数のバックエンドサービスまたはバックエンドバケットに転送することはできません。バックエンドサービスは、異なるゾーンやリージョンにバックエンドインスタンスグループまたはバックエンドネットワークエンドポイントグループ（NEG）を持つことができます。Multi-Regional Storage クラスを使用するバックエンドバケットを作成することもできます。

一意の URL のトラフィックを複数のサービスに転送するには、パスルールの代わりにルートルールを使用します。ヘッダーまたはパラメータと一致するルートルールを使用してパスマッチャーを構成すると、URL のヘッダーまたはクエリパラメータの内容に基づいて、一意の URL を複数のバックエンドサービスまたはバケットに転送できます。

同様に、リージョン外部アプリケーションロードバランサと Cloud Service Mesh の場合、ルートアクションの重み付けされたバックエンドサービスは、そのバックエンドサービスに設定された重みに応じて、同じ URL を複数のバックエンドサービスまたはバケットに転送できます。

URL マップとプロトコル

ターゲット HTTP プロキシとターゲット HTTPS プロキシの両方が URL マップを参照する場合、同じ URL マップ、ホストルール、パスマッチャーツールを使用して、クライアントから送信された HTTP リクエストと HTTPS リクエストを処理できます。

最も簡単な URL マップ

最も単純な URL マップは、デフォルトのバックエンドサービスまたはデフォルトのバックエンドバケットだけで構成されています。ホストルールもパスマッチャーもありません。リクエストされた URL はすべて、デフォルトのバックエンドサービスまたはデフォルトのバックエンドバケット（いずれか定義したほう）で処理されます。

デフォルトのバックエンドサービスを定義すると、 Google Cloud はバックエンドサービスの構成に従って、バックエンドインスタンスグループまたはバックエンド NEG にリクエストを転送します。

デフォルト以外のルールがない URL マップ。 — デフォルト以外のルールがない URL マップ（クリックして拡大）

オペレーションの順序

リクエストされた URL の特定のホスト名とパスについて、 Google Cloud は次の手順に沿って、URL マップで構成された正しいバックエンドサービスまたはバックエンドバケットにリクエストを転送します。

URL マップに URL のホスト名のホストルールが含まれていない場合、Google Cloud は、URL マップのデフォルトバックエンドサービスまたはデフォルトバックエンドバケット（いずれか定義したほう）にリクエストを転送します。
URL マップに URL のホスト名を含むホストルールが含まれている場合、そのホストルールで参照されるパスマッチャーが使用されます。
- パスマッチャーに URL のパスと完全に一致するパスルールが含まれている場合、 Google Cloud は、そのパスルールのバックエンドサービスまたはバックエンドバケットにリクエストを転送します。
- パスマッチャーに URL のパスと完全に一致するパスルールが含まれていないものの、/* で終わるパスルールが含まれていて、その接頭辞が URL のパスの最長部分と一致する場合、 Google Cloudは、そのパスルールのバックエンドサービスまたはバックエンドバケットにリクエストを転送します。たとえば、2 つのパスマッチャールール /video/hd/movie1 と /video/hd/* を含む URL マップの場合、完全に一致するパス /video/hd/movie1 が URL に含まれている場合、そのパスルールと照合されます。
- 上記のどちらの条件にも該当しない場合、 Google Cloud は、パスマッチャーのデフォルトのバックエンドサービスまたはデフォルトのバックエンドバケット（いずれか定義したほう）にリクエストを転送します。

URL マップの構成の制約

以下のセクションでは、URL マップコンポーネントの構成に関する制約について説明します。

ホストルールとルートルールにおける正規表現マッチャー

ホストルールでは、URL のホスト名の部分をホストルールに構成されたホスト名のセットと照合できます。hostRules[].hosts[] フィールドに特定のホスト名またはワイルドカード * のいずれかを指定して、それを受信リクエストのホスト名と照合できます。

ルートルールでは、パス、クエリ文字列、または受信リクエストのヘッダーのいずれかで正規表現を照合する照合ルールを定義できます。正規表現は、ルートルールの以下の URL マップフィールドで使用できます。

pathMatchers[].routeRules[].matchRules[].regexMatch: 受信リクエストのパスとの照合に使用される正規表現。
pathMatchers[].routeRules[].matchRules[].headerMatches[].regexMatch: 受信リクエストのヘッダーと照合する述語を含む正規表現。
pathMatchers[].routeRules[].matchRules[].queryParameterMatches[].regexMatch: 受信リクエストのクエリパラメータと照合する述語を含む正規表現。

matchRule のいずれかが満たされた場合、そのリクエストは routeRule と一致したとみなされます。ただし、特定の matchRule 内の述語には AND セマンティクスがあります。つまり、リクエストがルールに一致するには、いずれかの matchRule 内のすべての述語が一致する必要があります。

その他にも、以下のような使用上の注意があります。

正規表現は、次のプロダクトでのみサポートされています。
- リージョン内部アプリケーションロードバランサ
- クロスリージョン内部アプリケーションロードバランサ
- リージョン外部アプリケーションロードバランサ
グローバルアプリケーションロードバランサと従来のアプリケーションロードバランサでは、正規表現はサポートされていません。
正規表現は、RE2 構文を使用して作成する必要があります。制限事項と、URL マップで使用可能な演算子の一覧については、URL マップの RE2 仕様をご覧ください。
正規表現照合は、メモリ消費量とリクエスト処理のレイテンシという点でコストが高くなります。正規表現照合を使用する場合は、デプロイの計画時にパフォーマンスの低下を考慮に入れる必要があります。たとえば、単一の正規表現を含む URL マップがある場合、リクエストごとにロードバランサのレイテンシが 100 マイクロ秒増加すると予想されます。照合する正規表現が URL マップに 5 つ含まれている場合、リクエストごとにレイテンシが 200 マイクロ秒増加すると予想されます。

例 1: 正規表現を使用してパスを照合する

元の URL で指定されたクエリパラメータとアンカーを削除した後、regexMatch で指定された正規表現と一致する場合、そのパスは一致とみなされます。たとえば、次のサンプル URL マップでは、ルートルールの正規表現 /videos/hd.* が、/videos/hd-abcd?key=245 というパスを含む URL に適用されます。

defaultService: projects/example-project/global/backendServices/org-site
name: rule-match-url-map
hostRules:
- hosts:
  - '*' # Match any host
  pathMatcher: video-matcher
- hosts:
  - example.net
  pathMatcher: video-matcher
pathMatchers:
- name: video-matcher
  # Optional: default service for this path matcher if no routeRules match
  defaultService: projects/example-project/global/backendServices/video-site
  routeRules:
  - priority: 100000
    matchRules:
    - regexMatch: /videos/hd.*
    routeAction:
      weightedBackendServices:
      - backendService: projects/example-project/global/backendServices/video-hd
        weight: 100

上記のサンプル URL マップの各フィールドの説明は次のとおりです。

defaultService: URL マップ内の他のルールが受信リクエストと一致しない場合に使用するデフォルトのバックエンドサービスを指定します。
name: この URL マップ構成に rule-match-url-map という名前を割り当てます。
hostRules: 受信リクエストのホストヘッダーと照合するルールのリストを定義します。最初のルールは任意のホスト（*）に一致し、video-matcher という pathMatcher にトラフィックを送ります。2 つ目のルールはホスト example.net に一致し、これも video-matcher というパスマッチャーにトラフィックを送ります。
pathMatchers: 名前付きパスマッチャーのリストを定義します。
name: video-matcher というパスマッチャーを定義します。
defaultService: このパスマッチャーのデフォルトサービスを設定します。このサービスは、リクエストが video-matcher を指すホストルールに一致するものの、その中のいずれの routeRules にも一致しない場合に使用されます。
routeRules: URL パスと照合するルールのリストが含まれます。
priority: このルールの優先度を 100000 に設定します。ルールは優先度の低いものから順に評価されます。
matchRules: このルートルールの、照合する条件が含まれます。
regexMatch: URL パスが正規表現 /videos/hd.*（「/videos/hd」や「/videos/hd-caching」など）と一致するかどうかを確認します。
routeAction: matchRules のすべての条件が満たされた場合に実行するアクションを指定します。
weightedBackendServices: 重みに基づいて、バックエンドサービスのリストの間でトラフィックを分配します。
backendService: トラフィックの転送先となるバックエンドサービスを指定します。
weight: このバックエンドサービスに重み 100 を割り当てます。リスト内のサービスはこれだけなので、この routeRule に一致するトラフィックの 100% がこのサービスに転送されます。

次の URL マップの例は、routeAction を指定しない場合を示しています。

defaultService: projects/example-project/global/backendServices/video-site
name: path-matcher-videos
routeRules:
  matchRules:
  - regexMatch: /videos/hd.*
  priority: 100000
  service: projects/example-project/global/backendServices/video-hd

例 2: 正規表現を使用してヘッダーを照合する

ヘッダーの値が regexMatch で指定された正規表現と一致する場合、そのヘッダーは一致とみなされます。たとえば、次のサンプル URL マップでは、ヘッダー名の正規表現 .*Android.*-hd が、User-Agent:123Androidabc-hd というヘッダーを含むリクエストに適用されます。

defaultService: projects/example-project/regions/us-central1/backendServices/default-backend-service
name: header-match-url-map
hostRules:
- hosts:
  - '*'  # Match any host
  pathMatcher: header-matcher
pathMatchers:
- name: header-matcher
  # Optional: default service for this path matcher if no routeRules match
  defaultService: projects/example-project/regions/us-central1/backendServices/default-backend-service
  routeRules:
  - priority: 1
    matchRules:
    - headerMatches:
      - headerName: User-Agent
        regexMatch: .*Android.*-hd
    # This prefix match applies to the path part of the URL
    - prefixMatch: /video/
    # service: can be used instead of routeAction if no other actions are needed
    service: projects/example-project/regions/us-central1/backendServices/video-backend-service
    # Alternatively, use routeAction to specify the service:
    # routeAction:
    #   weightedBackendServices:
    #   - backendService: projects/example-project/regions/us-central1/backendServices/video-backend-service
    #     weight: 100

上記のサンプル URL マップの各フィールドの説明は次のとおりです。

defaultService: URL マップ内の他のルールが受信リクエストと一致しない場合に使用するデフォルトのバックエンドサービスを指定します。
name: この URL マップ構成に header-match-url-map という名前を割り当てます。
hostRules: 受信リクエストのホストヘッダーと照合するルールのリストを定義します。このルールは任意のホスト（*）に一致し、pathMatcher という header-matcher にトラフィックを送ります。
pathMatchers: 名前付きパスマッチャーのリストを定義します。
name: header-matcher というパスマッチャーを定義します。
defaultService: このパスマッチャーのデフォルトサービスを設定します。このサービスは、リクエストがホストルールに一致するものの、このパスマッチャー内のいずれの routeRules にも一致しない場合に使用されます。
routeRules: ヘッダーとパスに基づいて受信リクエストと照合するルールのリストが含まれます。
priority: このルールの優先度を 1 に設定します。ルールは優先度の低いものから順に評価されます。
matchRules: ルールが一致とみなされるためにすべて true でなければならない条件のリストが含まれます。
headerMatches: リクエストヘッダーに基づく条件を指定します。
headerName: User-Agent ヘッダーを対象とします。
regexMatch: User-Agent ヘッダーの値が正規表現 .*Android.*-hd と一致するかどうかを確認します。この正規表現は、Android デバイスを示す User-Agent に「-hd」を含む文字列が付加されたものと一致します。
prefixMatch: /video/ に設定します。この条件は、URL パスが「/video/」で始まるかどうかを確認します。
service: すべての matchRules 条件が満たされている場合、トラフィックはこのバックエンドサービスに転送されます。
コメントアウトされた routeAction セクションは、バックエンドサービスを指定する別の方法を示しています。これは、URL の書き換え、ヘッダー変換、重み付けされたバックエンドサービスなどの他のルートアクションを構成する場合に必要となります。

例 3: 正規表現を使用してクエリパラメータを照合する

クエリパラメータを含むパスの値が regexMatch で指定された正規表現と一致する場合、そのクエリパラメータは一致とみなされます。たとえば、次のサンプル URL マップでは、クエリパラメータの正規表現 /im.*/.*.html が、/images/random_page.html?param1=param_value_123abc-hd などのクエリパラメータを含む URL に適用されます。

defaultService: projects/example-project/regions/us-central1/backendServices/sample-bs
name: query-match-url-map
hostRules:
- hosts:
  - '*'  # Match any host
  pathMatcher: query-matcher
pathMatchers:
- name: query-matcher
  # Optional: default service for this path matcher if no routeRules match
  defaultService: projects/example-project/regions/us-central1/backendServices/sample-bs
  routeRules:
  - priority: 1
    matchRules:
    - queryParameterMatches:
      - name: param1   #parameter name in query
        regexMatch: param_value_.*-hd
    # This regexMatch applies to the path part of the URL
    - regexMatch: /im.*/.*.html
    # Directs traffic to this service if all conditions in matchRules are met
    service: projects/example-project/regions/us-central1/backendServices/sample-images-bs

上記のサンプル URL マップの各フィールドの説明は次のとおりです。

hostRules: すべてのホスト（*）に一致するルールを追加し、query-matcher という pathMatcher にトラフィックを送ります。
pathMatchers: query-matcher というパスマッチャーを定義します。
routeRules: 指定された routeRules ブロックを query-matcher 内に配置します。
priority: このルールの優先度を 1 に設定します。ルールは優先度の低いものから順に評価されます。
matchRules: routeRules の条件が含まれます。
queryParameterMatches: 「param1」というクエリパラメータが正規表現 param_value_.*-hd と一致するかどうかを確認します。
regexMatch: 正規表現 /im.*/.*.html が、URL パスのクエリ文字列より前の部分（/images/random_page.html など）に適用されます。
service: matchRules 内のすべての条件が true の場合に使用するバックエンドサービスを指定します。

パスルールと接頭辞照合におけるワイルドカード、正規表現、動的 URL

パスルール（pathMatchers[].pathRules[]）では、スラッシュ文字（/）の後にのみワイルドカード文字（*）を使用できます。たとえば、/videos/* や /videos/hd/* は有効なパスルールですが、/videos* や /videos/hd* は無効です。
パスルールでは、正規表現または部分文字列の照合は使用されません。PathTemplateMatch では、簡素化されたパス照合演算子を使用できます。たとえば、/videos/hd または /videos/hd/* パスルールは、パスが /video/hd-abcd の URL には適用されません。ただし、そのパスには /video/* のパスルールが適用されます。
接頭辞照合（pathMatchers[].routeRules[].matchRules[].prefixMatch）では、* はワイルドカード文字ではなく、リテラル文字として扱われます。
パスマッチャーと一般的な URL マップには、Apache の <LocationMatch> ディレクティブのような機能はありません。共通の接頭辞を持つ動的 URL パス（たとえば /videos/hd-abcd や /videos/hd-pqrs）を生成するアプリケーションがあり、これらのパスへのリクエストを異なるバックエンドサービスに送信する必要がある場合、URL マップではそのようなことはできません。動的 URL の非常に少ないケースでは、限定的なパスルールのセットを使用してパスマッチャーの作成が可能な場合もあります。より複雑なケースでは、バックエンドで正規表現を使用してパスの照合を行います。

ルートルールのパステンプレートでのワイルドカードとパターンマッチング演算子

柔軟なパターンマッチング演算子により、ワイルドカード構文を使用して URL パスの複数の部分（部分的な URL や接尾辞、ファイル拡張子など）を照合できます。これらの演算子は、複雑な URL パスに基づいてトラフィックのルーティングや書き換えを行う場合に役立ちます。1 つ以上のパスコンポーネントを名前付き変数に関連付けて、URL を書き換える際にそれらの変数を参照することもできます。名前付き変数を使用すると、リクエストがバックエンドに送信される前に、URL コンポーネントを並べ替えたり削除したりできます。

ワイルドカードを使用したパターンマッチングは、次のサービスでのみサポートされています。

グローバル外部アプリケーションロードバランサ

リージョン外部アプリケーションロードバランサ
リージョン内部アプリケーションロードバランサ

クロスリージョン内部アプリケーションロードバランサ
Cloud Service Mesh

次の例では、カート情報とユーザー情報に別々のサービスを使用する e コマースアプリケーションのトラフィックをルーティングします。柔軟なパターンマッチング演算子と名前付き変数を使用すると、URL の書き換え後、ユーザーの一意の ID とカート情報をカート処理サービスに送信するように routeRules を構成できます。

  pathMatchers:
    - name: cart-matcher
      routeRules:
        - description: CartService
          matchRules:
            - pathTemplateMatch: '/xyzwebservices/v2/xyz/users/{username=*}/carts/{cartid=**}'
          service: cart-backend
          priority: 1
          routeAction:
            urlRewrite:
              pathTemplateRewrite: '/{username}-{cartid}/'
    - name: user-matcher
      routeRules:
        - description: UserService
          matchRules:
            - pathTemplateMatch: '/xyzwebservices/v2/xyz/users/*/accountinfo/*'
          service: user-backend
          priority: 1

クライアントが /xyzwebservices/v2/xyz/users/abc@xyz.com/carts/FL0001090004/entries/SJFI38u3401nms?fields=FULL&client_type=WEB をリクエストし、ユーザー情報とカート情報の両方がある場合は次のようになります。

リクエストパスは、cart-matcher pathMatcher 内の pathTemplateMatch と一致します。{username=*} 変数は abc@xyz.com に一致し、{cartid=**} 変数は FL0001090004/entries/SJFI38u3401nms と一致します。
クエリパラメータはパスから分割され、pathTemplateRewrite に基づいてパスが書き換えられます。さらに、書き換えられたパスにクエリパラメータが付加されます。pathTemplateRewrite で pathTemplateMatch の定義に使用した同じ変数を使用する必要があります。
書き換えられたリクエストは、書き換えられた URL パス /abc@xyz.com-FL0001090004/entries/SJFI38u3401nms?fields=FULL&client_type=WEB を使用して cart-backend に送信されます。

クライアントがユーザーとアカウント情報のみを含む /xyzwebservices/v2/xyz/users/abc%40xyz.com/accountinfo/abc-1234 をリクエストすると、次のようになります。

リクエストパスは、user-matcher pathMatcher 内の pathTemplateMatch と一致します。最初の * は abc%40xyz.com に一致し、2 番目の * は abc-1234 と一致します。
リクエストが user-backend に送信されます。

次の表に、パステンプレートパターンの構文の概要を示します。

演算子	一致
*``**	1 つのパスセグメント。周囲のパス区切り文字 `/` は含まれません。
``**	0 個以上の文字に一致します。複数のパスセグメントを区切る `/` 文字も含まれます。他の演算子を含める場合は、`**` 演算子を最後にする必要があります。
*`{name}` または `{name=}`**	1 つのパスセグメントに一致する名前付き変数。1 つのパスセグメントと一致します。周囲のパス区切り文字 `/` は含みません。
*`{name=news/}`**	`news` と `*` の 2 つのパスセグメントに明示的に一致する名前付き変数。
*`{name=/news/}`*	3 つのパスセグメントに一致する名前付き変数。
`{name=}`**	0 個以上の文字が一致する名前付き変数。存在する場合は、最後の演算子にする必要があります。

これらの演算子を柔軟なパターンマッチングに使用する場合は、次の点に注意してください。

複数の演算子を 1 つのパターンに組み合わせることができます。
クエリパラメータはパスから分割され、pathTemplateRewrite に基づいてパスが書き換えられます。さらに、書き換えられたパスにクエリパラメータが付加されます。
リクエストはパーセントエンコードで正規化されません。たとえば、パーセントスラッシュ（%2F）エンコードを含む URL の場合、エンコードされていない形式にデコードされません。
各変数名（{segment} や {region} など）は、同じパターンで 1 回だけ使用できます。同じ名前の複数の変数は無効であり、拒否されます。
変数名では大文字と小文字が区別され、有効な識別子である必要があります。変数名が有効かどうかを確認するには、正規表現 ^[a-zA-Z][a-zA-Z0-9_]*$ と一致することを確認します。
- {API}、{api}、{api_v1} はすべて有効な識別子です。3 つの異なる変数を識別します。
- {1}、{_api}、{10alpha} は有効な識別子ではありません。
1 つのテンプレートパターンにつき 5 つまでの演算子を使用できます。

リクエストが送信元に送信される前に、オプションの URL 書き換えを実行するには、定義した変数を使用してパスをキャプチャします。たとえば、urlRewrite を定義するときに、pathTemplateRewrite フィールドの変数を参照、並べ替え、省略できます。

URL 書き換え用の柔軟なパターンマッチングに変数と演算子を使用する場合は、次の点に注意してください。

URL を書き換える際に、書き換えられた URL の一部として不要な変数は省略できます。
書き換えを行う前に、レスポンスヘッダーを調べることで、送信元でクライアントから送信された URL を特定できます。元のクライアント URL には、x-client-request-url ヘッダーと x-envoy-original-path ヘッダーが挿入されます。

外部アプリケーションロードバランサを使用した URL マップワークフローの例

次の例は、URL マップのオペレーションの順序を示しています。この例では、既存の従来のアプリケーションロードバランサの URL マップのみを構成します。説明を簡単にするため、ここでは、バックエンドサービスのみを使用します。バックエンドバケットを代用することも可能です。ロードバランサの他のコンポーネントを作成する方法については、従来のアプリケーションロードバランサーを作成するをご覧ください。

パスマッチャーとホストルールを使用した URL マップの作成と構成の詳細については、gcloud compute url-maps create のドキュメントをご覧ください。

ロードバランサの URL マップを作成し、デフォルトのバックエンドサービスを指定します。この例では、org-site という既存のバックエンドサービスを参照する video-org-url-map という URL マップを作成します。
```
gcloud compute url-maps create video-org-url-map \
    --default-service=org-site
```
次の特性を持つ video-matcher という名前のパスマッチャーを作成します。
- デフォルトのバックエンドサービスは、video-site という既存のバックエンドサービスになります。
- 正確な URL パス /video/hd または URL パスのプリフィックス /video/hd/* のリクエストを video-hd という名前の既存のバックエンドサービスに転送するパスルールを追加します。
- 正確な URL パス /video/sd または URL パスのプレフィックス /video/sd/* のリクエストを video-sd という名前の既存のバックエンドサービスに転送するパスルールを追加します。
```
gcloud compute url-maps add-path-matcher video-org-url-map \
    --path-matcher-name=video-matcher \
    --default-service=video-site \
    --path-rules=/video/hd=video-hd,/video/hd/*=video-hd,/video/sd=video-sd,/video/sd/*=video-sd
```

video-matcher パスマッチャーを参照する example.net というホスト名のホストルールを作成します。

gcloud compute url-maps add-host-rule video-org-url-map \
    --hosts=example.net \
    --path-matcher-name=video-matcher

video-org-url-map URL マップは次のようになります。

gcloud compute url-maps describe video-org-url-map

creationTimestamp: '2021-03-05T13:34:15.833-08:00'
defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/org-site
fingerprint: mfyJIT7Zurs=
hostRules:
- hosts:
  - '*'
  pathMatcher: video-matcher
- hosts:
  - example.net
  pathMatcher: video-matcher
id: '8886405179645041976'
kind: compute#urlMap
name: video-org-url-map
pathMatchers:
- defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-site
  name: video-matcher
  pathRules:
  - paths:
    - /video/hd
    - /video/hd/*
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-hd
  - paths:
    - /video/sd
    - /video/sd/*
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-sd
selfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/video-org-url-map

video-org-url-map URL マップは、リクエストされた URL を次の方法でバックエンドに送信します。

パスルール、パスマッチャー、ホストルールを含む URL マップ。 — パスルール、パスマッチャー、ホストルールを含む URL マップ（クリックして拡大）

次のテーブルに、前の図で表示されたリクエスト処理を示します。

ホスト名	URL パス	選択されたバックエンドサービス	選択の理由
ホスト名: `example.org`。また、 `example.net`と異なるその他のホスト名。	すべてのパス	`org-site`	ホスト名が URL マップのホストルールにないため、リクエストは URL マップのデフォルトのバックエンドサービスに転送されます。
ホスト名: `example.net`	`/video` `/video/examples`	`video-site`	`/video/` または `/video/*` のパスルールがないため、リクエストはデフォルトのバックエンドサービスに移動します。`example.net` のホストルールはパスマッチャーを参照しますが、これらのパスに適用されるパスルールはありません。
ホスト名: `example.net`	`/video/hd` `/video/hd/movie1` `/video/hd/movies/movie2` 先頭が `/video/hd/*` のその他の URL	`video-hd`	`example.net` のホストルールはパスルールのパスマッチャーを参照しています。このパスルールにより、`/video/hd` と完全に一致する URL パスか、`/video/hd/*` で始まる URL パスへのリクエストを `video-hd` バックエンドサービスに送信します。
ホスト名: `example.net`	`/video/sd` `/video/sd/show1` `/video/sd/shows/show2` 先頭が `/video/sd/*` のその他の URL	`video-sd`	`example.net` のホストルールはパスルールのパスマッチャーを参照しています。このパスルールにより、`/video/sd` と完全に一致する URL パスか、`/video/sd/*` で始まる URL パスへのリクエストを `video-sd` バックエンドサービスに送信します。

URL リダイレクト

URL リダイレクトは、同じ URL から別の URL にドメインの訪問者をリダイレクトします。

受信リクエスト内の特定のパターンに一致する場合も、デフォルトの URL リダイレクトは条件付けされません。たとえば、デフォルトの URL リダイレクトを使用して、任意のホスト名を任意のホスト名にリダイレクトできます。

次の表に示すように、URL リダイレクトを作成するにはいくつかの方法があります。

方法	構成
URL マップのデフォルトの URL リダイレクト	最上位 `defaultUrlRedirect`
パスマッチャーのデフォルトの URL リダイレクト	`pathMatchers[].defaultUrlRedirect[]`
パスマッチャーのパスルールの URL リダイレクト	`pathMatchers[].pathRules[].urlRedirect`
パスマッチャーのルートルールの URL リダイレクト	`pathMatchers[].routeRules[].urlRedirect`

defaultUrlRedirect または urlRedirect 内では、pathRedirect は常に次のように動作します。

リクエストパス全体が、指定したパスで置き換えられます。

defaultUrlRedirect または urlRedirect 内での prefixRedirect の動作は使用方法によって異なります。

defaultUrlRedirect を使用する場合、一致するパスは常に / であるため、prefixRedirect は事実上プレフィックスの先頭になります。
パスマッチャーのルートルールまたはパスルール内で urlRedirect を使用する場合、prefixRedirect は、パスルールまたはルートルールで定義されているように、リクエストされたパスがどのように一致したかに基づくプレフィックス置換になります。

リダイレクトの例

次の表は、リダイレクト構成の例を示しています。右側の列は、デフォルトの URL リダイレクトの API 構成を示しています。

目的	デフォルトの URL リダイレクトを使用した結果
HTTP から HTTPS へのリダイレクトリダイレクト http://host.name/path から https://host.name/path	kind: compute#urlMap name: web-map-http defaultUrlRedirect: httpsRedirect: True
HTTP から HTTPS + ホストリダイレクトリダイレクト http://any-host-name/path から https://www.example.com/path	kind: compute#urlMap name: web-map-http defaultUrlRedirect: httpsRedirect: True hostRedirect: "www.example.com"
HTTP から HTTPS + ホストリダイレクト + フルパスリダイレクトリダイレクト http://any-host-name/path から https://www.example.com/newPath	kind: compute#urlMap name: web-map-http defaultUrlRedirect: httpsRedirect: True hostRedirect: "www.example.com" pathRedirect: "/newPath"
HTTP から HTTPS + ホストリダイレクト + プレフィックスリダイレクトリダイレクト http://any-host-name/originalPath から https://www.example.com/newPrefix/originalPath	kind: compute#urlMap name: web-map-http defaultUrlRedirect: httpsRedirect: True hostRedirect: "www.example.com" prefixRedirect: "/newPrefix"

次のスニペットは、各 API リソースにアノテーションを追加します。

defaultUrlRedirect:
   redirectResponseCode: MOVED_PERMANENTLY_DEFAULT
   httpsRedirect: True # True if you want https://, false if you want http://
   hostRedirect: "new-host-name.com" # Omit to keep the requested host
   pathRedirect: "/new-path" # Omit to keep the requested path; mutually exclusive to prefixRedirect
   prefixRedirect: "/newPrefix" # Omit to keep the requested path; mutually exclusive to pathRedirect
   stripQuery: False # True to omit everything in the URL after ?
   ...

次のステップ

URL マップの追加、検証、テスト、一覧取得、削除について、URL マップを使用するで確認する。
Cloud Service Mesh を使用したルーティングルールマップについては、Cloud Service Mesh のルーティングルールマップの概要をご覧ください。

URL マップの概要 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

URL マップの仕組み

ロードバランサの命名

URL マップのコンポーネント

ホスト名とホストルールの関係

ホストルールとパスマッチャーの関係

URL とバックエンドの関係

URL マップとプロトコル

最も簡単な URL マップ

オペレーションの順序

URL マップの構成の制約

ホストルールとルートルールにおける正規表現マッチャー

例 1: 正規表現を使用してパスを照合する

例 2: 正規表現を使用してヘッダーを照合する

例 3: 正規表現を使用してクエリ パラメータを照合する

パスルールと接頭辞照合におけるワイルドカード、正規表現、動的 URL

ルートルールのパス テンプレートでのワイルドカードとパターン マッチング演算子

外部アプリケーション ロードバランサを使用した URL マップ ワークフローの例

URL リダイレクト

リダイレクトの例

次のステップ

URL マップの概要

例 3: 正規表現を使用してクエリパラメータを照合する

ルートルールのパステンプレートでのワイルドカードとパターンマッチング演算子

外部アプリケーションロードバランサを使用した URL マップワークフローの例