リクエストのルーティング方法

リージョン ID

REGION_ID は、アプリを作成するときに選択するリージョンに基づいて Google が割り当てるコードです。既存のアプリでは省略可能でしたが、新しいアプリでは App Engine の URL に REGION_ID.r を含めることが必須になります。

移行がスムーズに行われるように、リージョン ID を使用するよう App Engine を徐々に更新しています。Google Cloud プロジェクトがまだ更新されていない場合、アプリにリージョン ID が表示されません。ID は既存のアプリでは省略可能なため、リージョン ID が既存のアプリで使用可能になったときに、URL を更新する、またはその他の変更を行う必要はありません。

詳しくは、リージョン ID をご覧ください。

このページでは、ユーザーからの HTTP リクエストが、適切なバージョンのサービスにどのように到達するかについて説明します。リクエストは、次の 2 つの方法でルーティングできます。

  • App Engine のデフォルトのルーティング ルールを、ドメインレベルで終わる URL のリクエストに適用します。

  • または、独自のルールに従って特定の URL パターンをルーティングするディスパッチ ファイルを使用することもできます。

ローカルの開発用サーバーを使用してアプリをテストする場合は、利用できるルーティングとディスパッチの機能が多少異なります。本番環境サーバーと開発用サーバーの両方で機能する URL をプログラムで作成するには、ModulesService.getVersionHostname メソッドを使用します。

詳しくは、開発サーバーでのルーティングをご覧ください。

リクエストとドメイン

アプリが App Engine で実行されたら、次の URL を使用して HTTP リクエストをアプリに送信できます。
https://PROJECT_ID.REGION_ID.r.appspot.com

PROJECT_ID は、アプリを含む Google Cloud プロジェクトの ID です。

この URL では、トラフィックの受信を構成したアプリのバージョンにリクエストを送信します。

アプリの各バージョンには専用の URL も割り当てられるので、新しいバージョンをデプロイしてテストしてから、トラフィックを受信するようにそのバージョンを構成できます。バージョン固有の URL では、プロジェクト ID、リージョン ID、appspot.com ドメイン名に加え、特定のバージョンの ID を使用します。次に例を示します。 https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com

サブドメイン

appspot.com ドメインは、SUBDOMAIN-dot-PROJECT_ID.REGION_ID.r.appspot.com という形式のサブドメインもサポートしています。SUBDOMAIN は、ドメイン名の一部に使用できる任意の文字列です。ただし、. 文字は使用できません。このようにしていずれかのサブドメインに送信されたリクエストは、アプリにルーティングされます。

次のように、バージョン固有の URL のサブドメインを使用することもできます。
https://SUBDOMAIN-dot-VERSION_ID-dot-PROJECT_ID.REGION_ID.r.appspot.com

詳細と例については、URL 経由のルーティングをご覧ください。

カスタム ドメイン

G Suite を使用してカスタム トップレベル ドメインを設定したうえで、そのサブドメインをさまざまなアプリ(Gmail や Google サイトなど)に割り当てることができます。また、App Engine アプリをサブドメインに関連付けることもできます。カスタム ドメインとアプリをマッピングする方法については、SSL によるカスタム ドメインの保護をご覧ください。

リクエスト データに含まれるドメイン名

リクエストに使用されるドメイン名は、アプリに渡されるリクエスト データに含まれています。したがって、リクエスト データを使用すると、リクエストのドメイン名に応じてアプリの応答を制御できます。たとえば、正式なドメインにリダイレクトする場合には、Host リクエスト ヘッダーを確認してドメイン名に応じて応答するようにアプリをコーディングします。

リージョン ID

REGION_ID は、アプリを作成するときに選択するリージョンに基づいて Google が割り当てるコードです。既存のアプリでは省略可能でしたが、新しいアプリでは App Engine の URL に REGION_ID.r を含めることが必須になります。

移行がスムーズに行われるように、リージョン ID を使用するよう App Engine を徐々に更新しています。Google Cloud プロジェクトがまだ更新されていない場合、アプリにリージョン ID が表示されません。ID は既存のアプリでは省略可能なため、リージョン ID が既存のアプリで使用可能になったときに、URL を更新する、またはその他の変更を行う必要はありません。

アプリのリージョン ID は次のツールで確認できます。

Console

Cloud Console では、アプリのインスタンスサービスバージョンで URL を確認できます。

これらの URL にはリージョン ID が含まれます。

gcloud

アプリまたはサービスのデプロイに成功した後に、gcloud app deploy コマンドを実行すると、URL が表示されます。この URL にはリージョン ID が含まれます。

デプロイされているサービスの URL を表示するには:

  1. gcloud app versions list コマンドを入力して、特定のサービスのバージョンの一覧を取得します。たとえば、デフォルトのサービスのバージョンを表示するには、gcloud app versions list --service=default を入力します。

  2. gcloud app versions describe コマンドを入力します。このコマンドの出力には、バージョンの URL とアプリのリージョン ID が含まれます。たとえば、デフォルト サービスのバージョン 20191023t101741 を指定するには、gcloud app versions describe 20191023t101741 --service=default を入力します。

URL 経由のルーティング

さまざまな特性レベルを指定して HTTP リクエストをターゲットにできます。アプリのカスタム ドメインがある場合は、次の例で REGION_ID.r.appspot.com をそのカスタム ドメインで置き換えることができます。URL の部分文字列 VERSION_IDSERVICE_IDPROJECT_ID はそれぞれ、アプリのリソース ID を表します。

アプリのリソース ID を取得するには、次のツールを使用します。

Console

Cloud Console で、対応するインスタンスサービスバージョンのページを表示できます。

gcloud

特定の Cloud プロジェクト内のリソース ID の一覧を表示するには、gcloud app instances list コマンドを実行します。

API

リソース ID をプログラムで取得する方法については、Admin API の list メソッドをご覧ください。

デフォルトのルーティング

次の URL パターンには、デフォルトのルーティング動作があります。ディスパッチ ファイルに一致パターンが定義されている場合、デフォルトのルーティングは上書きされます。

  • default サービスの使用可能なインスタンスにリクエストを送信する場合:
    
    https://PROJECT_ID.REGION_ID.r.appspot.com
    https://CUSTOM_DOMAIN

    default サービスの中で、このトラフィック用に構成されている任意のバージョンがトラフィックを受信します。

  • 特定のサービスの使用可能なインスタンスにリクエストを送信する場合:
    
    https://SERVICE_ID-dot-PROJECT_ID.REGION_ID.r.appspot.com
    https://SERVICE_ID.CUSTOM_DOMAIN

    対象のサービスの中で、このトラフィック用に構成されている任意のバージョンがリクエストを受信します。対象のサービスが存在しない場合、リクエストはソフト ルーティングされます。

  • 特定のバージョンの
    default サービスの使用可能なインスタンスにリクエストを送信する場合:
    
    https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com
    https://VERSION_ID.CUSTOM_DOMAIN

    対象のサービスが存在しない場合、リクエストは default サービスに送信されます。

ソフト ルーティング

リクエストがホスト名の PROJECT_ID.REGION_ID.r.appspot.com 部分と一致するものの、存在しないサービス、バージョン、インスタンス名が含まれている場合、リクエストは default サービスにルーティングされます。ソフト ルーティングは、カスタム ドメインには適用されません。ホスト名が無効な場合、カスタム ドメインへのリクエストは HTTP 404 ステータス コードを返します。

ターゲット ルーティング

次の URL パターンは、そのターゲットに到達することが保証されています(ターゲットが存在する場合)。これらのリクエストは傍受されず、ディスパッチ ファイルに定義されているパターンで再ルーティングされません。

  • 特定のサービスとバージョンの使用可能なインスタンスにリクエストを送信する場合:
    
    https://VERSION_ID-dot-SERVICE_ID-dot-PROJECT_ID.REGION_ID.r.appspot.com
    https://VERSION_ID.SERVICE_ID.PROJECT_ID.CUSTOM_DOMAIN
  • 手動でスケーリングするサービスを使用する場合、特定のインスタンスをターゲットに送信するには、リクエストにインスタンス ID を組み込みます。インスタンス ID は、0 から実行中のインスタンスの合計数までの範囲の整数であり、次のように指定できます。

    特定のインスタンス内の特定のサービスとバージョンにリクエストを送信する場合:

    https://INSTANCE_ID-dot-VERSION_ID-dot-SERVICE_ID-dot-PROJECT_ID.REGION_ID.r.appspot.com
    https://INSTANCE_ID.VERSION_ID.SERVICE_ID.CUSTOM_DOMAIN

デフォルト サービス

App Engine にアプリの最初のバージョンをデプロイするときに、default サービスが作成されます。サービスが指定されていないリクエストや無効なサービスが指定されているリクエストは、default サービスにルーティングされます。これらのリクエストは、default サービス内でトラフィックを受信するように構成されているバージョンで処理されます。トラフィックに構成済みのバージョンは、Cloud Console の [バージョン] ページで確認できます。

サービスへのアクセスを制限する

すべてのサービスが、デフォルトで一般公開に設定されます。サービスへのアクセスを制限する場合は、<role-name>admin</role-name> 要素をそのセキュリティ制約に追加します。

URL パターンを説明するために、サンプルの Cloud プロジェクトを使用します。このプロジェクトの ID は requestsProject であり、2 つのサービスとバージョンを実行するアプリが含まれています。このサンプルアプリの default サービスにはバージョン vFrontend が含まれ、2 番目のサービス service2 にはバージョン vBackend が含まれます。Google は、リージョン ID として両方のアプリに uc を割り当てます。

特定のサービスとバージョンをターゲットに設定するには、次の URL パターンを使用します。

  1. HTTPS を使用して default サービスのバージョンをターゲットに設定するには、次のパターンを使用します。

        https://vFrontend-dot-default-dot-requestsProject.uc.r.appspot.com
        https://vFrontend-dot-requestsProject.uc.r.appspot.com
    

  2. カスタム ドメインを使用して vBackend バージョンをターゲットに設定するには、次のパターンを使用します。

    https://vBackend.service2.example.net
    https://vBackend.example.net
    

    requestsProject.uc.r.appspot.comexample.net ドメインにマッピングされます。

ディスパッチ ファイルを使用してルーティングする

上記のパターンを使用する URL の場合、App Engine のルーティング ルールを上書きするディスパッチ ファイルを作成し、独自のカスタム ルーティング ルールを定義できます。ディスパッチ ファイルを使用すると、リクエスト URL のパスまたはホスト名に基づいて受信リクエストを特定のサービスに送信できます。

ディスパッチ ファイルの作成方法については、dispatch.yaml リファレンスをご覧ください。

ディスパッチ ファイルの作成

ディスパッチ ファイルは、app.yaml などの他の構成ファイルに使用するディレクトリと同じディレクトリに配置されている必要があります。 ディスパッチ ファイルでは最大 20 個のルーティング ルールを定義できます。各ルールは service 要素と url 要素から構成されます。

たとえば、https://simple-sample.uc.r.appspot.com/mobile/ などのモバイル リクエストはモバイル フロントエンドにルーティングし、https://simple-sample.uc.r.appspot.com/work/ などのワーカー リクエストは静的バックエンドにルーティングするためのディスパッチ ファイルを作成できます。

dispatch:
  # Send all mobile traffic to the mobile frontend.
  - url: "*/mobile/*"
    service: mobile-frontend

  # Send all work to the one static backend.
  - url: "*/work/*"
    service: static-backend

dispatch.yaml の定義方法について詳しくは、dispatch.yaml リファレンス ドキュメントをご覧ください。

ディスパッチ ファイルのデプロイ

dispatch.yaml ファイルはソースコードのどこに配置してもかまいません。

現在使用中のバージョンを変更せずにディスパッチ構成ファイルをデプロイするには、お使いの環境に応じて、ディスパッチ ファイルを含むディレクトリで次のいずれかのコマンドを使用します。

gcloud

gcloud app deploy dispatch.yaml

Maven

mvn appengine:deployDispatch dispatch.yaml

Gradle

gradle appengineDeployDispatch dispatch.yaml

IDE

IntelliJ または Eclipse を使用する場合、デプロイメント フォームを使用して、デプロイ対象の個々の構成ファイルを選択します。

開発用サーバーでのルーティング

インスタンス アドレスを検索する

ローカルの開発用サーバーでは、起動時にすべてのインスタンスを作成します。このとき、開発用サーバーでは基本スケーリング インスタンスがサポートされていないことに注意してください。 作成されるインスタンスごとに個別のポートが割り当てられます。 ポート割り当ては、サーバーのログメッセージ ストリームに表示されます。 ウェブ クライアントは、このポートをターゲットに指定することで、特定のインスタンスと通信できます。 1 つのインスタンス(とポート)のみが自動スケーリング サービス用に作成されます。サーバーログには次のように記録されます(サービスは以前はモジュールと呼ばれていたことに注意してください)。

INFO: Module instance service-auto is running at http://localhost:37251/

手動スケーリング サービスの各インスタンスに、一意のポートが割り当てられます。

INFO: Module instance service-manual instance 0 is running at http://localhost:43190/
INFO: Module instance service-manual instance 1 is running at http://localhost:52642/

さらに、それぞれの手動スケーリング サービスに追加ポートが 1 つ割り当てられるため、クライアントは特定のインスタンスを指定することなくサービスにアクセスできます。このポートへのリクエストは、構成されたいずれかのインスタンスに自動的にルーティングされます。

INFO: Module instance service-manual is running at http://localhost:12361/

次の表に、開発用サーバーと App Engine 環境でこれらのサービスを呼び出す方法を示しています。

サービス インスタンス 開発用サーバー アドレス App Engine アドレス
service-auto (未使用) http://localhost:37251/ https://v1-dot-service-auto-dot-PROJECT_ID.REGION_ID.r.appspot.com/
service-manual 0 http://localhost:43190/ https://0-dot-v1-dot-service-manual-dot-PROJECT_ID.REGION_ID.r.appspot.com/
service-manual 1 http://localhost:52642/ https://1-dot-v1-dot-service-manual-dot-PROJECT_ID.REGION_ID.r.appspot.com/
service-manual (未使用) http://localhost:12361/ https://v1-dot-service-manual-dot-PROJECT_ID.REGION_ID.r.appspot.com/

Maven または Gradle プラグインを使用している場合には、ローカル開発用サーバーで使用されるポート番号を割り当てることができます。詳細については、Apache MavenApache Maven(Cloud SDK ベース)または Gradle をご覧ください。

ディスパッチ ファイル

ローカルの開発用サーバーを起動している場合、ディスパッチ ファイルはすべて無視されます。インスタンスをターゲットに指定する唯一の方法は、インスタンスのポートを使用することです。