appengine-web.xml リファレンス

App Engine Java アプリケーションでは、web.xml デプロイ記述子に加えて、appengine-web.xml という名前の構成ファイルを使用してアプリに関する情報を指定します。また、このファイルを使用して、アプリの WAR 内のどのファイルが静的ファイル(画像など)で、どのファイルがアプリケーションによって使用されるリソース ファイルであるかを識別します。

以下の例では、アプリケーション ID とバージョン ID のみを指定しています。静的ファイルやリソース ファイルは指定していません。

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>_your_app_id_</application><!-- unused for Cloud SDK based tooling -->
  <version>alpha-001</version><!-- unused for Cloud SDK based tooling -->
  <threadsafe>true</threadsafe>
  <runtime>java8</runtime>
</appengine-web-app>

構文

App Engine Java アプリでは、WAR 内のディレクトリ WEB-INF/appengine-web.xml というファイルを含める必要があります。この XML ファイルのルート要素は <appengine-web-app> です。

appengine-web.xml のドキュメント タイプ定義とスキーマの仕様は、SDK の docs/ ディレクトリにあります。

要素 説明
<application>

gcloud app deploy コマンドなどの Cloud SDK ベースのツールや、IntelliJ、Eclipse、Maven、Gradle の各プラグインを使用してアプリをデプロイする場合には、必須ではありません。Cloud SDK ベースのツールはこの要素を無視し、gcloud 構成プロジェクトのプロパティからプロジェクト ID を取得します。gcloud コマンドライン ツールでプロジェクト ID をオーバーライドできますが、これはマシンワイドのプロジェクト ID であり、複数のプロジェクトを開発している場合、混乱が起きる可能性があるので注意してください。<application> 要素にはアプリケーションのプロジェクト ID が格納されます。このプロジェクト ID は、Google Cloud Platform Console でプロジェクトを作成したときに登録した ID です。アプリのアップロード時には、appcfg がこのファイルからプロジェクト ID を取得します。

<async-session-persistence>

省略可。HTTP セッション データをデータストアに非同期に書き込むようにアプリケーションを構成すると、リクエストのレイテンシを短縮できます。


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <async-session-persistence enabled="true" />
  <!-- ... -->
</appengine-web-app>

非同期のセッションの永続化を有効にすると、App Engine は、memcache にデータを書き込む前に、セッション データをデータストアに書き込むために、タスクキューのタスクを送信します。デフォルトでは、このタスクは default キューに送信されます。別のキューを使用するには、queue-name 属性を追加します。


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <async-session-persistence enabled="true" queue-name="myqueue"/>
  <!-- ... -->
</appengine-web-app>

セッション データは常に同期的に memcache に書き込まれます。memcache が利用できないとき(またはセッション データがフラッシュされたとき)に、セッション データを読み込むリクエストが試行されると、Datastore にフェイルオーバーされますが、ここには最新のセッション データが保存されていない場合があります。つまり、非同期のセッションの永続化を有効にすると、アプリケーションで最新のセッション データを取得できないことがあります。大半のアプリケーションでは、このリスクよりもレイテンシの短縮によるメリットが大きいと言えます。

<auto-id-policy> 省略可。エンティティ ID を自動的に設定している場合、自動 ID ポリシーを設定すると、使用するメソッドを変更できます。有効なオプションは次のとおりです。
default
デフォルト。64 ビット浮動小数点として表現可能で、適度に分散された ID を自動的に割り当てます。
legacy
レガシー オプションは今後のリリースで非推奨となり、最終的に削除される予定です。詳細については、この変更を発表したブログ記事をご覧ください。
<automatic-scaling>

省略可。詳細については、自動スケーリングをご覧ください。

<basic-scaling>

省略可。詳細については、基本スケーリングをご覧ください。

<env-variables>

省略可。appengine-web.xml ファイルには、アプリケーションの実行時に設定される環境変数を定義できます。


<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 8 アプリで有効にするには、appengine-web.xml ファイルに <inbound-services> セクションを追加します。

以下のインバウンド サービスが使用できます。

mail
アプリケーションにメールの受信を許可します。
<instance-class>

省略可。このモジュールのインスタンス クラスのサイズ。

異なるスケーリング オプションを指定するときに、次のインスタンス クラスを使用できます。

automatic_scaling
自動スケーリングの場合、F1、F2、F4、F4_1G のインスタンス クラスを使用できます。
デフォルト: automatic_scaling 要素とともにインスタンス クラスを指定しない場合は、F1 が割り当てられます。
basic_scaling
基本スケーリングの場合、B1、B2、B4、B4_1G、B8 インスタンス クラスを使用できます。
デフォルト: basic_scaling 要素とともにインスタンス クラスを指定しない場合は、B2 が割り当てられます。
manual_scaling
手動スケーリングの場合、B1、B2、B4、B4_1G、B8 のインスタンス クラスを使用できます。
デフォルト: manual_scaling 要素とともにインスタンス クラスを指定しない場合は、B2 が割り当てられます。

注: instance-classF2 以上に設定されている場合、max-concurrent-requests を 10(デフォルト)より大きい値に設定することで、インスタンスを最適化できます。最適な値を見つけるには、値を少しずつ増やしながらアプリケーションのパフォーマンスをモニタリングします。

<manual-scaling>

省略可。詳細については、手動スケーリングをご覧ください。

<precompilation-enabled>

省略可。App Engine では、Java Runtime Environment でのアプリのパフォーマンスを向上させるために、アプリの Java バイトコードで「プリコンパイル」処理を行います。プリコンパイルされたコードは、元のバイトコードとまったく同じように機能します。

アプリでプリコンパイルを行わない場合、次の行を appengine-web.xml ファイルに追加すると、プリコンパイルを無効にできます。


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <precompilation-enabled>false</precompilation-enabled>
  <!-- ... -->
</appengine-web-app>
module

注: モジュールはサービスという名前に変わりましたが、appengine-web.xml ファイルでは、<module>service_name</module> のようにモジュールとしてサービスが宣言されます。

サービスを作成する場合は必須です。デフォルトのサービスでは省略できます。サービスとバージョンには名前を付ける必要があります。名前には、数字、文字、ハイフンを使用できます。名前は 63 文字以下にする必要があります。また、名前の先頭または最後にハイフンは使用できません。サービスとバージョンには一意の名前を付ける必要があります。サービスとバージョンに同じ名前を使用することはできません。

サービスもご覧ください。

<public-root>

省略可。<public-root> はアプリケーションのディレクトリです。ここに、アプリケーションの静的ファイルが格納されます。静的ファイルがリクエストされると、リクエストパスの先頭にアプリケーションの <public-root> が追加されます。これにより、リクエストされたアプリケーション ファイルのパスが渡されます。

デフォルトの <public-root>/ です。

たとえば、次の例では URL パス /index.html がアプリケーション ファイルのパス /static/index.html にマッピングされています。


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <public-root>/static</public-root>
  <!-- ... -->
</appengine-web-app>
<resource-files>

省略可。<resource-files> 要素に記述されているファイルは、ファイル システムを使用するアプリケーション コードからアクセスできるようになります。静的ファイルとは異なり、これらのファイルはアプリと一緒にアプリケーション サーバーに格納されます。

<resource-files> 要素には次の要素を設定できます。

<include>
<include> 要素は、ファイルをリソース ファイルに指定し、アプリケーション コードから使用できるようにします。これらのファイルは読み取り専用で、トラフィックの処理には使用できません。ファイルの追加と除外をご覧ください。
<exclude>

<exclude> パターンに一致するファイルとディレクトリはアップロードされず、アプリケーション コードでも使用できません。ただし、ローカルの開発用サーバーでアプリケーションを実行する場合には、これらのファイルやディレクトリにアクセスできます。詳細については、ファイルの追加と除外をご覧ください。

例:

<resource-files>
  <include path="/**.xml" />
  <exclude path="/feeds/**.xml" />
</resource-files>

この例では、feeds/ ディレクトリとそのすべてのサブディレクトリにあるファイルを除き、すべての .xml ファイルをリソース ファイルとして定義しています。

App Engine リソース ファイルの読み取りには、java.io.File または javax.servlet.ServletContext.getResource/getResourceAsStream が使用されます。Class.getResourceAsStream() でアクセスすることはできません。

runtime

Java 8 ランタイムを使用するには、このエントリを値 java8 に指定する必要があります。Java 7 ランタイムを使用するには、このエントリを省略するか、値 java7 を指定します(App Engine の Java ランタイムは OpenJDK に基づいています)。

例:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <runtime>java8</runtime>
  <!-- ... -->
</appengine-web-app>
service

サービスは、モジュールと呼ばれていました。

現在、サービスを <service>service_name</service > として定義するには、gcloud app コマンドを使用する必要があります。

<sessions-enabled>

省略可。App Engine には、サーブレット セッション インターフェースを使用して実装されるセッションがあります。この実装では、永続性のためにセッション データが Datastore に保存されるだけでなく、高速化を図るために memcache も使用されます。他のほとんどのサーブレット コンテナと同様、リクエスト時に session.setAttribute() で設定されるセッション属性が、リクエストの終了時に永続化されます。

この機能はデフォルトで無効になっています。有効にするには次の行を appengine-web.xml に追加します。

例:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <sessions-enabled>true</sessions-enabled>
  <!-- ... -->
</appengine-web-app>

この実装では、種類が _ah_SESSION の Datastore エンティティと、接頭辞 _ahs のキーを使用した memcache エントリが作成されます。これらのエンティティは、Dataflow テンプレートを使用して削除できます。

: App Engine はセッション データを Datastore と memcache に保存するため、セッションで保存されるすべての値で java.io.Serializable インターフェースを実装する必要があります。

セッション データの保存でレイテンシを短縮する方法については、async-session-persistence 要素をご覧ください。

<ssl-enabled>

省略可。デフォルトでは、どのユーザーも HTTP または HTTPS を使用して任意の URL にアクセスできます。デプロイ記述子の特定の URL には HTTPS を必須とするように、アプリを構成できます。詳細については、デプロイ記述子: 保護された URL をご覧ください。

アプリケーションで HTTPS の使用を禁止する場合は、appengine-web.xml ファイルに次の行を追加します


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <ssl-enabled>false</ssl-enabled>
  <!-- ... -->
</appengine-web-app>

Java Runtime Environment の一部の URL パスのみで HTTPS を禁止する方法はありません。

<static-error-handlers>

省略可。特定のエラーの発生時に、App Engine によって汎用的なエラーページが表示されます。このような汎用的なエラーページではなくカスタムの静的ファイルを表示するようにアプリを構成できます。ただし、カスタム エラーデータは 10 KB 未満にする必要があります。サポート対象のエラーコードごとに異なる静的ファイルが表示されるように設定するには、アプリの appengine-web.xml ファイルでファイルを指定します。カスタム エラーページを表示するには、次の例のように、appengine-web.xml<static-error-handlers> セクションを追加します。


<static-error-handlers>
  <handler file="default_error.html" />
  <handler file="over_quota.html" error-code="over_quota" />
</static-error-handlers>

警告: エラー レスポンス ファイルのパスが静的ファイル ハンドラのパスと重ならないようにしてください。

file エントリには、汎用的なエラー レスポンスの代わりに表示される静的ファイルを指定します。error-code には、関連ファイルを表示するエラーコードを指定します。使用可能なエラーコードは次のとおりです。

over_quota
アプリがリソース割り当てを超過したことを示します。
dos_api_denial
このオプションを使用すると、アプリの DoS 防御構成でブロックされたクライアントにこのエラーページが使用されます。
timeout
アプリからレスポンスが返される前に時間切れとなった場合に使用されます。

error-code は省略可能です。省略すると、指定したファイルがアプリのデフォルトのエラー レスポンスになります。

カスタムエラーの処理時に使用する mime-type を指定することもできます。MIME タイプのリストをご覧ください。

<static-files>

省略可。<static-files> 要素には、静的ファイルのリストに追加または除外するパスのパターンを指定します。これにより、デフォルトの動作を変更または修正できます。静的ファイルは専用のサーバーとアプリケーション サーバーとは別のキャッシュから提供されます。画像、CSS スタイルシート、JavaScript ファイルなどの静的コンテンツを配信する場合に便利です。

<static-files> 要素には次の要素を設定できます。

<include>

<include> 要素は、デフォルトの動作(JSP 以外のすべてのファイルを対象)をオーバーライドします。<include> 要素には、指定したリソースのリクエストに対するレスポンスの HTTP ヘッダーを指定できます。詳細については、ファイルの追加と除外をご覧ください。

include 要素に expiration 属性を指定すると、静的キャッシュの有効期限を指定できます。設定する値は、数値と単位の文字列をスペースで区切ったものです。単位には、日数を表す d、時間数を表す h、分数を表す m、秒数を表す s を指定できます。たとえば、"4d 5h" と指定すると、キャッシュの有効期限はファイルが最初にリクエストされてから 4 日と 5 時間後に設定されます。有効期限を省略すると、本番環境サーバーのデフォルト(10 分)が使用されます。詳細については、静的キャッシュの有効期限をご覧ください。

<exclude>
<exclude> パターンに一致するファイルとディレクトリは、アプリを App Engine にデプロイする際にアップロードされません。ただし、ローカルの開発用サーバーでアプリケーションを実行する場合には、これらのファイルやディレクトリにもアクセスできます。詳細については、ファイルの追加と除外をご覧ください。

<static-files>
  <include path="/my_static-files" >
    <http-header name="Access-Control-Allow-Origin"
                 value="http://example.org" />
  </include>
</static-files>
<system-properties>

省略可。appengine-web.xml ファイルでは、アプリケーションの実行時に設定されるシステム プロパティと環境変数を定義できます。


<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>
<threadsafe>

必須。appengine-web.xmlthreadsafe 要素が false の場合、App Engine は指定されたウェブサーバーにリクエストを順次送信します。値が true の場合、App Engine は複数のリクエストを並列で送信します。


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <threadsafe>true</threadsafe>
  <!-- ... -->
</appengine-web-app>

リクエストを同時処理する場合には、threadsafe を有効にする前にアプリケーション コードで適切なスレッド同期を使用する必要があります。

<url-stream-handler>

省略可。有効な値は native または urlfetch です。デフォルトの値とこの設定は、Java 8 ランタイムか Java 7 ランタイムのどちらで使用されるかによって変わります。

Java 8 ランタイムの場合、デフォルト値は native です。これは Java 8 ランタイムと Java 7 動作の比較に記載されているように、標準 Java ネットワーク クラスでは標準 Java HTTP(S) トランスポートが使用されることを示しています。この設定では、アプリが課金を有効にしている必要があります。有効にしていないと、リクエストから次のランタイム エラーが戻ります。

Java 8 ランタイムで url-stream-handler 要素を urlfetch に設定すると、App Engine が URLStreamHandlerFactoryインストールします。この結果、URL.openConnectionと関連メソッドで http URL と https URL に対し、URL 取得トランスポートが使用されます。

Java 7 ランタイムの場合、デフォルト値は urlfetch です。これは Java 8 ランタイムと Java 7 動作の比較に記載されているように、標準 Java ネットワーク クラスで URL 取得サービスが使用されることを示します。

Java 7 ランタイムで値を native に設定すると、App Engine は java.net.HttpURLConnection に対して URL 取得ではなく Sockets API を使用します。この設定も Java 8 と同様に、アプリが課金を有効にしている必要があります。有効にしないと、リクエストから次のランタイム エラーが戻ります。


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <url-stream-handler>urlfetch</url-stream-handler>
  <!-- ... -->
</appengine-web-app>
<version>

<version> 要素には、アプリの最新のコードのバージョン ID を指定します。バージョン ID には、小文字、数字、ハイフンを使用できます。接頭辞「ah-」で始めることはできません。「default」と「latest」は予約されているので使用できません。

バージョン名は、常に番号で指定される数値インスタンスと区別するために、英字で始まる必要があります。これにより、123.my-module.appspot.com のような URL の曖昧さを回避できます。この URL は、2 通りに解釈できます。バージョン「123」が存在する場合は、指定されたモジュールのバージョン「123」がターゲットになります。そのバージョンが存在しない場合は、このモジュールのデフォルト バージョンのインスタンス番号 123 がターゲットになります。

appcfg コマンドは、アプリケーションのアップロード時に、このバージョン ID でアプリの新しいバージョンを作成するのか、既存のバージョンを置き換えるのかを App Engine に伝えます。アプリの新しいバージョンをテストする場合は、https://_version_id_-dot-_your_app_id_.appspot.com のように URL のサブドメインを「-dot-」で区切ります。Google Cloud Platform Console を使用すると、アプリのデフォルト バージョンを選択できます。デフォルト バージョンは、バージョンが指定されていない場合や無効なバージョンが指定された場合に読み込まれます。

<warmup-requests-enabled>

省略可。デフォルトは true です。Java 8 アプリケーションの場合、ウォームアップ リクエストはデフォルトで有効になっています。

ウォームアップ リクエストを有効にすると、App Engine インフラストラクチャは /_ah/warmup に GET リクエストを送信し、<load-on-startup> サーブレット、ServletContextListenersカスタム ウォームアップ サーブレットを初期化します。この方法で、必要に応じてアプリケーションのコードを初期化できます。選択した方法によっては、/_ah/warmup に独自のハンドラを実装する必要があります。

ウォームアップ リクエストを無効にするには、この要素に false を指定します。


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <warmup-requests-enabled>false</warmup-requests-enabled>
  <!-- ... -->
</appengine-web-app>
<vpc-access-connector>

省略可。サーバーレス VPC アクセス コネクタを使用するようにアプリケーションを構成して、アプリケーションが VPC ネットワークの内部リソースにリクエストを送信できるようにします。<name> 要素にコネクタの完全修飾名を指定します。


<vpc-access-connector>
  <name>projects/[PROJECT_ID]/locations/[REGION]/connectors/[CONNECTOR_NAME]</name>
</vpc-access-connector>

詳細については、VPC ネットワークの内部リソースへの接続をご覧ください。

スケーリングの要素

次の表では、アプリケーションのスケーリングを指定する場合のオプションについて説明します。

スケーリング タイプのパフォーマンス機能の比較については、動的インスタンスのスケーリングをご覧ください。

要素 説明
<automatic-scaling>

省略可。特に指定のない限り、自動スケーリングが適用され、デフォルトのインスタンス クラス F1 が使用されます。

automatic_scaling 要素には、モジュールのインスタンス、レイテンシ、同時接続の最小数と最大数を設定します。

この要素には次の要素を設定できます。

<target-cpu-utilization>
省略可。0.5~0.95 の値を指定します。

このパラメータは、トラフィックを処理する新しいインスタンスを起動するための CPU 使用率のしきい値を指定します。これにより、パフォーマンスとコストのバランスをとることができます。値を小さくするほど、パフォーマンスが向上してコストは増加し、値を大きくするほどパフォーマンスは低下してコストが削減されます。たとえば、値を 0.7 にした場合、CPU 使用率が 70% に達すると新しいインスタンスが起動されます。

重要: App Engine SDK for Java に含まれる appcfg コマンドを使用してデプロイする場合は、appengine-web.xml でこのパラメータを使用することはできません。代わりに、API Explorer による自動スケーリング パラメータの設定の手順を実施するか、App Engine Admin API を使用して、このパラメータを設定します。

<target-throughput-utilization>
省略可。0.5~0.95 の値を指定します。

max-concurrent-requests とともに使用して、同時リクエストによって新しいインスタンスが起動されるタイミングを指定します。同時リクエストの数が max-concurrent-requeststarget-throughput-utilization の積に等しい値に達すると、スケジューラは新しいインスタンスを起動します。

重要: App Engine SDK for Java に含まれる appcfg コマンドを使用してデプロイする場合は、appengine-web.xml でこのパラメータを使用することはできません。代わりに、API Explorer での自動スケーリング パラメータの設定の手順に従うか App Engine Admin API を使用して、パラメータを設定します。

<max-instances>
省略可。App Engine によってこのアプリケーションのバージョンに対して作成されるインスタンスの最大数。これはモジュールのコストを抑える場合に便利です。0~2147483647 の値を指定します。

重要: App Engine SDK for Java に含まれる appcfg を使用してデプロイする場合は、appengine-web.xml でこのパラメータを使用することはできません。代わりに、API Explorer による自動スケーリング パラメータの設定の手順を実施するか、App Engine Admin API を使用して、このパラメータを設定します。

<min-instances>
省略可。App Engine によってこのモジュール バージョンに作成されるインスタンスの最小数。これらのインスタンスは、リクエストが届いたときにトラフィックを処理し、トラフィックを処理するために必要な追加インスタンスが起動されてもトラフィックを処理し続けます。

0~1000 の値を指定します。このパラメータを 0 に設定すると、リクエストが処理されていないときにインスタンス数を 0 にスケールしてコストを削減できます。ただし、トラフィックを受信しているかどうかにかかわらず、指定されたインスタンス数分の料金が請求される点に注意してください。

重要: App Engine SDK for Java に含まれる appcfg を使用してデプロイする場合は、appengine-web.xml でこのパラメータを使用することはできません。代わりに、API Explorer による自動スケーリング パラメータの設定の手順を実施するか、App Engine Admin API を使用して、このパラメータを設定します。

<max-concurrent-requests>

省略可。自動スケーリング インスタンスが受け入れることのできる同時リクエスト数。この数を超えると、スケジューラによって新しいインスタンスが生成されます(デフォルト: 10、最大: 80)。

この値が大きすぎると、API のレイテンシが増加する場合があります。リクエストの最大数に達する前にスケジューラが新しいインスタンスを生成する場合もあります。

注: instance-classF2 以上に設定されている場合、max-concurrent-requests を 10(デフォルト)より大きい値に設定することで、インスタンスを最適化できます。最適な値を見つけるには、値を少しずつ増やしながらアプリケーションのパフォーマンスをモニタリングします。

<max-idle-instances>

App Engine がこのバージョンに保持できるアイドル状態のインスタンスの最大数。デフォルト値は「automatic」です。以下のことに注意してください。

  • 最大数を大きく設定すると、負荷レベルの急増後に通常のレベルに戻る際に、アイドル インスタンスの数がより緩やかに減っていきます。その結果、アプリケーションがリクエスト負荷変動の前後を通じて安定したパフォーマンスを維持しやすくなる一方で、そのような負荷の高い期間のアイドル インスタンスの数(その結果としてランニング コスト)も増えます。
  • 最大数を小さく設定すると、ランニング コストは低く抑えられますが、負荷レベルの変動があったときにパフォーマンスが低下する可能性があります。

注: 負荷の急増後に通常のレベルに戻るときに、アイドル インスタンスの数が指定した最大数を一時的に超える可能性があります。この場合、指定した最大数を超える分について料金が請求されることはありません。

<max-pending-latency>

App Engine でリクエストが保留キューで待機できる最長時間。この時間を経過すると、リクエストを処理する新しいインスタンスが起動されて保留待ち時間が短くなります。デフォルト値は「30 ms」です。

  • 最大時間を短く設定すると、App Engine が保留中のリクエストに対処するための新しいインスタンスを作成するタイミングが早くなり、パフォーマンスは向上しますがランニング コストも高くなります。
  • 最大時間を長く設定すると、ユーザーがリクエストの処理を待つ時間は長くなる可能性があります(保留中のリクエストがあり、それらに対処するアイドル インスタンスがない場合)が、アプリケーションのランニング コストは低くなります。
<min-idle-instances>

動作を継続中で、トラフィックの処理に対応できるインスタンス数。この設定は、トラフィックの大半を受信するバージョンにのみ適用されます。以下のことに留意します。

  • 最小数を小さく設定すると、アイドル時間にかかるランニング コストは低く抑えられますが、負荷の急増があった場合にすぐに対処できるインスタンスの数が少なくなります。
  • 最小数を大きく設定すると、アプリケーションがリクエスト負荷の急増に対応できるようになります。App Engine では、最小数のインスタンスを常に実行して、受信したリクエストの処理に当たります。これらのインスタンスはリクエストの処理中であるかどうかにかかわりなく、料金が発生します。この機能を適正に機能させるには、ウォームアップ リクエストが有効であること、およびアプリケーションでウォームアップ リクエストが処理されることを確認する必要があります。

    アイドル インスタンスの最小数を設定すると、保留待ち時間がアプリケーションのパフォーマンスに与える影響は小さくなります。一定数のアイドル インスタンスが常に確保されるため、異常なほど負荷が急増した場合を除き、リクエストが保留中のキューに入る可能性は低くなります。理想的な予約インスタンス数を判定するには、アプリケーションと予測トラフィック量をテストする必要があります。

<min-pending-latency>

App Engine でリクエストが保留キューで待機できる最短時間(秒)。この時間を経過すると、リクエストを処理する新しいインスタンスが起動されます。0.01~15 の値を指定します。

  • 最小待ち時間を短く設定すると、既存のインスタンスがすべて稼動中のときにリクエストが保留中のキューにとどまる時間が短くなります。パフォーマンスは向上しますが、アプリケーションのランニング コストも高くなります。
  • 最小時間を長く設定すると、既存のインスタンスがすべて稼動中のときにリクエストが保留中のキューにとどまる時間が長くなります。ランニング コストは低くなりますが、ユーザーがリクエストの処理を待つ時間は長くなります。

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <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>

省略可。<basic-scaling> 要素には、モジュールのインスタンス数を設定します。

この要素には次の要素を設定できます。

<idle-timeout>
省略可。最後のリクエストを受信した後、この時間が経過すると、インスタンスはシャットダウンされます。デフォルトは 5 分です。
<max-instances>
必須。App Engine によってこのモジュール バージョンに作成されるインスタンスの最大数。これはモジュールのコストを抑える場合に便利です。

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <instance-class>B8</instance-class>
  <basic-scaling>
    <max-instances>11</max-instances>
    <idle-timeout>10m</idle-timeout>
  </basic-scaling>
</appengine-web-app>
<manual-scaling>

省略可。<manual-scaling> 要素を使用すると、モジュールで手動スケーリングを有効にし、モジュールのインスタンス数を設定できます。

この要素には次の要素を設定できます。

<instances>
モジュール起動時にモジュールに割り当てるインスタンスの数。

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <instance-class>B8</instance-class>
  <manual-scaling>
    <instances>5</instances>
  </manual-scaling>
</appengine-web-app>

ステージング要素

JAR ファイルのアセンブルや、JSP のコンパイルなど、デプロイ中に行われる作業の多くは、ステージングと呼ばれる準備段階でローカルに実行されます。アプリケーション構成ファイル内のステージング要素を使用して、ステージング動作の特定の部分を構成することもできます。ほとんどのアプリケーションは、ステージング動作を手動で構成しなくてもデプロイできます。お使いのアプリがデプロイできない場合は、以下のオプションを使用してステージングを構成する必要があります。

要素 説明
<staging>

省略可。ほとんどのアプリケーションでは、デフォルト動作を変更する必要がありません。

ステージング要素により、デプロイに必要な特定のステージング構成を指定できます。

この要素には次の要素を設定できます。

<enable-jar-splitting>

省略可。10 メガバイトを超える大きい jar ファイルを小さいフラグメントに分割します(デフォルトは true です)。

<jar-splitting-excludes>

jar 分割を使用するときに除外するサフィックスのリストです。

<disable_jar_jsps>

JSP から生成されたクラスを jar に圧縮しません(デフォルトは false です)。

<enable-jar-classes>

WEB-INF / クラスのコンテンツを jar に圧縮します(デフォルトは true です)。

<delete-jsps>

コンパイル後に JSP ソースファイルを削除します(デフォルトは true です)。

<compile-encoding>

コンパイルするソースファイルのエンコードを入力します(デフォルトは utf-8 です)。

ステージング オプションのデフォルト値

ステージング オプションのデフォルト値は、appcfg などの App Engine SDK ベースのツールを使用するか、gcloud コマンドラインなどの Cloud SDK ベースのツール、または Cloud SDK ベースの MavenGradleEclipseIntelliJ の各プラグインを使用するかによって異なります。

ステージング要素 App Engine SDK ベースのデフォルト値 - 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 タイプを関連付けることができます。詳細については、Metawerx web.xml リファレンス wiki をご覧ください。

静的キャッシュの有効期限

特に指定のない限り、ウェブプロキシとブラウザは、ウェブサイトから読み込んだファイルを一定期間保持します。

<static-files><include ... >expiration 属性を追加すると、特定のファイル ハンドラにキャッシュの有効期限を構成できます。設定する値は、数値と単位の文字列をスペースで区切ったものです。単位には、日数を表す d、時間数を表す h、分数を表す m、秒数を表す s を指定できます。たとえば、"4d 5h" と指定すると、キャッシュの有効期限はファイルが最初にリクエストされてから 4 日と 5 時間後に設定されます。有効期限を省略すると、本番環境サーバーのデフォルト(10 分)が使用されます。

例:

<static-files>
  <include path="/**.png" expiration="4d 5h" />
</static-files>

有効期限は Cache-ControlExpires HTTP レスポンス ヘッダーで送信されます。ファイルは、ユーザーのブラウザ キャッシュだけでなく、インターネット サービス プロバイダなど、中間のプロキシ サーバーのキャッシュにも保存されます。有効期限付きでファイルが転送された場合、ユーザーが自身のブラウザ キャッシュからファイルを消去しても、中間キャッシュから消去することはできません。アプリケーションの新しいバージョンを再度デプロイしても、キャッシュはリセットされません。静的ファイルを変更する場合には、有効期限は短く(1 時間未満)設定してください。多くの場合、デフォルトの 10 分で十分です。

URLFetch タイムアウト

URLFetch リクエストの期限を設定できます。デフォルトの取得期限は 5 秒です。このデフォルトを変更するには、appengine-web.xml 構成ファイルに次の設定を追加します。タイムアウトは秒単位で指定します。

<system-properties>
    <property name="appengine.api.urlfetch.defaultDeadline" value="10"/>
</system-properties>
このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

Java 8 の App Engine スタンダード環境