リージョン ID
REGION_ID は、アプリの作成時に選択したリージョンに基づいて Google が割り当てる省略形のコードです。一部のリージョン ID は、一般的に使用されている国や州のコードと類似しているように見える場合がありますが、このコードは国または州に対応するものではありません。2020 年 2 月以降に作成されたアプリの場合、REGION_ID.r は App Engine の URL に含まれています。この日付より前に作成されたアプリの場合、URL のリージョン ID は省略可能です。
詳しくは、リージョン ID をご覧ください。
既存のアプリを App Engine Java 8 ランタイムからサポートされている最新バージョンの Java に移行し、以前のバンドル サービスを使用する場合に限り、appengine-web.xml ファイルを使用してアプリを構成する必要があります。プロジェクトで appengine-web.xml を使用している場合、app.yaml はデプロイ時に自動的に生成されます。
App Engine Java アプリケーションでは、appengine-web.xml という名前の構成ファイルを使用してアプリに関する情報を指定します。また、このファイルを使用して、アプリの WAR ファイル内にあるどのファイルが静的ファイル（画像など）で、どのファイルがアプリケーションによって使用されるリソース ファイルを識別します。
構文
App Engine Java アプリでは、WAR 内のディレクトリ WEB-INF/ に appengine-web.xml というファイルを含める必要があります。この XML ファイルのルート要素は <appengine-web-app> です。
appengine-web.xml のドキュメント タイプ定義とスキーマの仕様は、SDK の docs/ ディレクトリにあります。
| 要素 | 説明 |
|---|---|
<application> |
|
|
省略可。第 2 世代ランタイムに App Engine の以前のバンドル サービスを使用する場合は、このフィールドを |
|
省略可。第 2 世代ランタイムのみ。デフォルトのエントリポイント（Java アプリケーションを起動するプロセス コマンドライン）をオーバーライドします。デフォルトでは、F4 インスタンス クラス用に生成されるエントリ ポイント（メモリ設定はインスタンス クラスから算出されます）は、次の構成と同等です。 <appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <entrypoint> java -showversion -Xms32M -Xmx819M -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:+PrintCommandLineFlags --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio.charset=ALL-UNNAMED --add-opens java.logging/java.util.logging=ALL-UNNAMED --add-opens java.base/java.util.concurrent=ALL-UNNAMED -Dclasspath.runtimebase=/base/java_runtime -Djava.class.path=/base/java_runtime/runtime-main.jar -Djava.library.path=/base/java_runtime: com/google/apphosting/runtime/JavaRuntimeMainWithDefaults --fixed_application_path=/workspace /base/java_runtime </entrypoint> </appengine-web-app>
構成を変更して、JVM プロセスフラグを追加したり、独自のプロセスを定義できます。アプリケーションは |
<async-session-persistence> |
省略可。HTTP セッション データをデータストアに非同期に書き込むようにアプリケーションを構成すると、リクエストのレイテンシを短縮できます。 <async-session-persistence enabled="true" /> 非同期のセッションの永続化を有効にすると、App Engine は、memcache にデータを書き込む前に、セッション データをデータストアに書き込むために、タスクキューのタスクを送信します。デフォルトでは、このタスクは default キューに送信されます。別のキューを使用するには、queue-name 属性を追加します。 <async-session-persistence enabled="true" queue-name="myqueue"/> セッション データは常に同期的に memcache に書き込まれます。memcache が利用できないとき（またはセッション データがフラッシュされたとき）に、セッション データを読み込むリクエストが試行されると、Datastore にフェイルオーバーされますが、ここには最新のセッション データが保存されていない場合があります。つまり、非同期のセッションの永続化を有効にすると、アプリケーションで最新のセッション データを取得できないことがあります。大半のアプリケーションでは、このリスクよりもレイテンシの短縮によるメリットが大きいと言えます。 |
<auto-id-policy> |
省略可。エンティティ ID を自動的に設定している場合、自動 ID ポリシーを設定すると、使用するメソッドを変更できます。有効なオプションは次のとおりです。
|
<automatic-scaling> |
省略可。詳細については、自動スケーリングをご覧ください。 |
<basic-scaling> |
省略可。詳細については、基本スケーリングをご覧ください。 |
<env-variables> |
省略可。 <env-variables> <env-var name="DEFAULT_ENCODING" value="UTF-8" /> </env-variables> ローカル環境での競合を避けるため、開発用サーバーでは、このファイルに基づいて環境変数を設定していません。ローカル環境では、これらの変数に一致値が設定されている必要があります。 export DEFAULT_ENCODING="UTF-8" dev_appserver war App Engine にデプロイされている場合、これらの変数は環境ですでに設定されています。 |
<inbound-services> |
省略可。アプリケーションでメール メッセージを受信するには、このサービスを有効にするようにアプリケーションを構成しておく必要があります。このサービスを Java アプリで有効にするには、 以下のインバウンド サービスが使用できます。
|
<instance-class> |
省略可。このモジュールのインスタンス クラスのサイズ。 異なるスケーリング オプションを指定するときに、次のインスタンス クラスを使用できます。
|
<manual-scaling> |
省略可。詳細については、手動スケーリングをご覧ください。 |
<precompilation-enabled> |
省略可。App Engine では、Java Runtime Environment でのアプリのパフォーマンスを向上させるために、アプリの Java バイトコードで「プリコンパイル」処理を行います。プリコンパイルされたコードは、元のバイトコードとまったく同じように機能します。
アプリでプリコンパイルを行わない場合、次の行を <precompilation-enabled>false</precompilation-enabled> |
<module> |
注: モジュールはサービスという名前に変わりましたが、 サービスを作成する場合は必須です。デフォルトのサービスでは省略できます。サービスとバージョンには名前を付ける必要があります。名前には、数字、文字、ハイフンを使用できます。名前は 63 文字以下にする必要があります。また、名前の先頭にも最後にもハイフンは使用できず、文字列「-dot」を含めることもできません。各サービスとバージョンには一意の名前を付ける必要があります。サービスとバージョンに同じ名前を使うことはできません。 サービスもご覧ください。 |
<public-root> |
省略可。
デフォルトの
たとえば、次の例では URL パス <public-root>/static</public-root> |
<resource-files> |
省略可。
App Engine リソース ファイルの読み取りには、 |
<runtime> |
サポートされている最新バージョンの Java を使用するには、このエントリを値 <runtime>java21</runtime> |
<service> |
サービスは、モジュールと呼ばれていました。 現在、サービスを |
<service-account> |
省略可。 <service-account>[SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com</service-account> |
<sessions-enabled> |
省略可。App Engine には、サーブレット セッション インターフェースを使用して実装されるセッションがあります。この実装では、永続性のためにセッション データが Datastore に保存されるだけでなく、高速化を図るために memcache も使用されます。他のほとんどのサーブレット コンテナと同様、リクエスト時に session.setAttribute() で設定されるセッション属性が、リクエストの終了時に永続化されます。
この機能はデフォルトで無効になっています。有効にするには次の行を <sessions-enabled>true</sessions-enabled>
この実装では、種類が
注: App Engine はセッション データを Datastore と memcache に保存するため、セッションで保存されるすべての値で
セッション データの保存でレイテンシを短縮する方法については、 |
<ssl-enabled> |
省略可。デフォルトでは、どのユーザーも HTTP または HTTPS を使用して任意の URL にアクセスできます。デプロイ記述子の特定の URL には HTTPS を必須とするように、アプリを構成できます。詳細については、デプロイ記述子: 保護された URL をご覧ください。
アプリケーションで HTTPS の使用を禁止する場合は、 <ssl-enabled>false</ssl-enabled> Java Runtime Environment の一部の URL パスのみで HTTPS を禁止する方法はありません。 |
<static-error-handlers> |
省略可。特定のエラーの発生時に、App Engine によって汎用的なエラーページが表示されます。このような汎用的なエラーページではなくカスタムの静的ファイルを表示するようにアプリを構成できます。ただし、カスタム エラーデータは 10 KB 未満にする必要があります。サポート対象のエラーコードごとに異なる静的ファイルが表示されるように設定するには、アプリの <static-error-handlers> <handler file="default_error.html" /> <handler file="over_quota.html" error-code="over_quota" /> </static-error-handlers> 警告: エラー レスポンス ファイルのパスが静的ファイル ハンドラのパスと重ならないようにしてください。
カスタムエラーの処理時に使用する |
<static-files> |
省略可。
<static-files> <include path="/my_static-files" > <http-header name="Access-Control-Allow-Origin" value="http://example.org" /> </include> </static-files> |
<system-properties> |
省略可。 <system-properties> <property name="myapp.maximum-message-length" value="140" /> <property name="myapp.notify-every-n-signups" value="1000" /> <property name="myapp.notify-url" value="http://www.example.com/signupnotify" /> </system-properties> <env-variables> <env-var name="DEFAULT_ENCODING" value="UTF-8" /> </env-variables> 省略可。CPU とメモリの使用率を改善するために HTTP コネクタを構成できます。 <system-properties> <property name="appengine.use.httpconnector" value="true"/> </system-properties> Java 21 以降では、仮想スレッドを使用するように Java ウェブサーバーを構成できます。次に例を示します。 <system-properties> <property name="appengine.use.virtualthreads" value="true"/> </system-properties> |
<url-stream-handler> |
省略可。有効な値は デフォルト値は
<url-stream-handler>urlfetch</url-stream-handler> |
<version> |
バージョン名は、常に番号で指定される数値インスタンスと区別するために、英字で始まる必要があります。これにより、 |
<warmup-requests-enabled> |
省略可。デフォルトは true です。Java アプリケーションの場合、ウォームアップ リクエストはデフォルトで有効になっています。
ウォームアップ リクエストを有効にすると、App Engine インフラストラクチャは
ウォームアップ リクエストを無効にするには、この要素に <warmup-requests-enabled>false</warmup-requests-enabled> |
<vpc-access-connector> |
省略可。サーバーレス VPC アクセス コネクタを使用するようにアプリケーションを構成して、アプリケーションが VPC ネットワークの内部リソースにリクエストを送信できるようにします。 <vpc-access-connector>
<name>projects/[PROJECT_ID]/locations/[REGION]/connectors/[CONNECTOR_NAME]</name>
</vpc-access-connector>詳細については、VPC ネットワークの内部リソースへの接続をご覧ください。 |
スケーリングの要素
次の表では、アプリケーションのスケーリングを指定する場合のオプションについて説明します。
スケーリング タイプのパフォーマンス機能の比較については、動的インスタンスのスケーリングをご覧ください。
| 要素 | 説明 |
|---|---|
<automatic-scaling> |
省略可。特に指定のない限り、自動スケーリングが適用され、デフォルトのインスタンス クラス
この要素には次の要素を設定できます。
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <application>simple-app</application> <module>default</module> <version>uno</version> <instance-class>F2</instance-class> <automatic-scaling> <target-cpu-utilization>0.65</target-cpu-utilization> <min-instances>5</min-instances> <max-instances>100</max-instances> <max-concurrent-requests>50</max-concurrent-requests> </automatic-scaling> </appengine-web-app> |
<basic-scaling> |
省略可。 この要素には次の要素を設定できます。
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <application>simple-app</application> <module>default</module> <version>uno</version> <instance-class>B8</instance-class> <basic-scaling> <max-instances>11</max-instances> <idle-timeout>10m</idle-timeout> </basic-scaling> </appengine-web-app> |
<manual-scaling> |
省略可。 この要素には次の要素を設定できます。
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <application>simple-app</application> <module>default</module> <version>uno</version> <instance-class>B8</instance-class> <manual-scaling> <instances>5</instances> </manual-scaling> </appengine-web-app> |
ステージング要素
JAR ファイルのアセンブルや、JSP のコンパイルなど、デプロイ中に行われる作業の多くは、ステージングと呼ばれる準備段階でローカルに実行されます。アプリケーション構成ファイル内のステージング要素を使用して、ステージング動作の特定の部分を構成することもできます。ほとんどのアプリケーションは、ステージング動作を手動で構成しなくてもデプロイできます。お使いのアプリがデプロイできない場合は、以下のオプションを使用してステージングを構成する必要があります。
| 要素 | 説明 |
|---|---|
<staging> |
省略可。ほとんどのアプリケーションでは、デフォルト動作を変更する必要がありません。 ステージング要素により、デプロイに必要な特定のステージング構成を指定できます。 この要素には次の要素を設定できます。
例:
<staging>
<delete-jsps>false</delete-jsps>
</staging>
|
ステージング オプションのデフォルト値
ステージング オプションのデフォルト値は、gcloud CLI などの Google Cloud SDK ベースのツールを使用するか、Google Cloud SDK ベースの Maven、Gradle、Eclipse、IntelliJ の各プラグインを使用するかによって異なります。
| ステージング要素 | App Engine SDK ベースのデフォルト値 - | Google Cloud SDK ベースのデフォルト値 |
|---|---|---|
enable-jar-splitting |
false |
true |
jar-splitting-excludes |
なし | なし |
disable-jar-jsps |
false |
false |
enable-jar-classes |
false |
true。クラスの読み込み順序に影響を与えることがあります。そのため、アプリが以前の false デフォルト値を使用する特定の順序に依存する場合は、これを false に設定しても構いません。 |
delete-jsps |
false |
true |
compile-encoding |
utf-8 |
utf-8 |
include と exclude
パスのパターンを指定するときに、0 個以上の <include> と <exclude> 要素を使用できます。パターン内で、'*' はファイル名またはディレクトリ名内の 0 個以上の任意の文字を表し、** はパス内の 0 個以上のディレクトリを表します。<exclude> パターンに一致するファイルとディレクトリは、アプリを App Engine にデプロイする際にアップロードされません。ただし、ローカルの開発用サーバーでアプリケーションを実行する場合には、これらのファイルやディレクトリにアクセスできます。
<include> 要素はデフォルトの動作をオーバーライドします（デフォルトでは、すべてのファイルが対象になります）。<exclude> 要素は、すべての <include> パターン（<include> が明示的に指定されていない場合のデフォルトも含む）の後に適用されます。
次の例では、data/ ディレクトリとそのすべてのサブディレクトリ内のファイルを除くすべての .png ファイルを静的ファイルとして指定しています。
<static-files>
<include path="/**.png" />
<exclude path="/data/**.png" />
</static-files>
静的リソースのリクエストに対するレスポンスで使用する HTTP ヘッダーも設定できます。
<static-files>
<include path="/my_static-files" >
<http-header name="Access-Control-Allow-Origin"
value="http://example.org" />
</include>
</static-files>
静的ファイルの MIME タイプ
デフォルトでは、静的ファイルはファイル名の拡張子に基づいて選択される MIME タイプで提供されます。web.xml で mime-mapping 要素を使用すると、静的ファイルのファイル名拡張子にカスタム MIME タイプを関連付けることができます。
URLFetch タイムアウト
URLFetch リクエストの期限を設定できます。デフォルトの取得期限は 5 秒です。このデフォルトを変更するには、appengine-web.xml 構成ファイルに次の設定を追加します。タイムアウトは秒単位で指定します。
<system-properties>
<property name="appengine.api.urlfetch.defaultDeadline" value="10"/>
</system-properties>