app.yaml 構成ファイル

App Engine アプリの設定は、app.yaml ファイルで構成します。app.yaml ファイルには、アプリのコード、Node.js ランタイム、環境変数に関する情報も含まれています。

アプリ内の各サービスには固有の app.yaml ファイルがあり、このファイルはそのアプリのデプロイ記述子としての役割を果たします。アプリ内の追加サービス用に app.yaml ファイルを作成してデプロイする前に、まず default サービス用の app.yaml ファイルを作成する必要があります。

Node.js の場合、app.yaml には少なくとも runtime: nodejs8 というエントリが含まれている必要があります。概要については、ランタイム設定の定義をご覧ください。

ディレクトリ構造

アプリでの複数サービスの構造化の詳細については、App Engine でのウェブサービスの構造化をご覧ください。

Node.js アプリケーションの app.yaml ファイルの例を次に示します。

runtime: nodejs8

instance_class: F2

env_variables:
  BUCKET_NAME: "example-gcs-bucket"

handlers:
- url: /stylesheets
  static_dir: stylesheets

- url: /.*
  secure: always
  redirect_http_response_code: 301
  script: auto

構文

app.yaml の構文は YAML 形式です。

YAML 形式ではコメントがサポートされています。シャープ(#)記号で始まる行は無視されます。

# This is a comment.

URL とファイルパスのパターンは、要素照合とクラス照合を除き、POSIX 拡張正規表現構文を使用します。グループ化した一致への後方参照(例: \1)は、Perl 拡張(\w \W \s \S \d \D)と同様にサポートされます。

ランタイムとアプリの要素

要素 説明
default_expiration

省略可。アプリケーションのすべての静的ファイル ハンドラにグローバルなデフォルト キャッシュ期間を設定します。特定の静的ファイル ハンドラにキャッシュ期間を設定することもできます。値は、数値と単位の文字列をスペースで区切ったものです。単位には、日数を表す d、時間数を表す h、分数を表す m、秒数を表す s を指定できます。たとえば、"4d 5h" は、ファイルが最初に要求された後のキャッシュの有効期限を 4 日と 5 時間後に設定します。省略すると、本番環境のサーバーが有効期限を 10 分に設定します。

例:

runtime: nodejs8

handlers:
# ...

詳細については、静的キャッシュの有効期限をご覧ください。

env_variables

省略可。アプリで使用できるように、app.yaml ファイルで環境変数を定義できます。

GAE という接頭辞が付いた環境変数はシステム用に予約されており、app.yaml ファイルでは使用できません。

例:

env_variables:
  MY_VAR: 'my value'
ここで、MY_VARmy value は定義する環境変数の名前と値です。環境変数の各エントリは、env_variables 要素の下にスペース 2 つ分インデントしています。

環境変数を取得して使用するには、process.env を使用します。

上書きできないランタイム環境変数のリストも参照してください。

error_handlers

省略可。各種エラータイプに対して返されるカスタム エラーページを構成するために使用します。

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

error_code
省略可。error_code は、以下のいずれかになります。
over_quota
アプリがリソース割り当ての上限を超えていることを表します。
timeout
アプリからレスポンスが返される前に時間切れとなった場合に処理されます。

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

file
file エントリには、汎用的なエラー レスポンスの代わりに表示される静的ファイルを指定します。対応する error_code 要素を使用せずに file 要素を指定すると、静的ファイルがアプリのデフォルトのエラーページになります。 カスタム エラーデータは 10 KB 以下にする必要があります。

error_handlers:
  - file: default_error.html

  - error_code: over_quota
    file: over_quota.html
handlers

省略可。URL パターンと処理方法の説明のリストです。App Engine で URL を処理するには、アプリケーション コードを実行するか、画像、CSS、JavaScript など、コードと一緒にアップロードされた静的ファイルを提供します。

ハンドラとサブ要素の構文をご覧ください。

inbound_services

省略可。アプリケーションは、受信リクエストを受け取る前に、これらのサービスを有効にする必要があります。このサービスを Node.js アプリで有効にするには、inbound_services セクションを app.yaml ファイルに含めます。

warmup
ウォームアップ リクエストを有効にします。ウォームアップ リクエストの設定をご覧ください。
例:

inbound_services:
  - warmup
instance_class

省略可。 このサービスのインスタンス クラス

サービスのスケーリングに応じて、次の値を使用できます。

自動スケーリング
F1F2F4F4_1G
デフォルト: automatic_scaling 要素と一緒にインスタンス クラスを指定しない場合、F1 が割り当てられます。
基本スケーリング、手動スケーリング
B1B2B4B4_1GB8
デフォルト: basic_scaling 要素または manual_scaling 要素と一緒にインスタンス クラスを指定しない場合、B2 が割り当てられます。

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

runtime

必須。アプリで使用されるランタイム環境の名前です。Node.js を指定するには、nodejs8 を使用します。


runtime: nodejs8
service

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

例:

service: service_name

handlers 要素

handlers 要素は、URL パターンのリストとそれらの処理方法の説明を提供します。App Engine で URL を処理するには、アプリケーション コードを実行するか、画像、CSS、JavaScript など、コードとともにアップロードされた静的ファイルを提供します。

パターンは、app.yaml ファイルの上から下へ順に評価されます。URL とパターンが一致する最初の組み合わせが、リクエストの処理に使用されます。

以下の表に、静的ファイル、静的ディレクトリ、その他の設定の動作を制御する、handlers 要素のサブ要素を示します。

要素 説明
expiration 省略可。このハンドラで処理する静的ファイルがウェブプロキシとウェブブラウザでキャッシュに保存される有効期限。値は、数値と単位の文字列をスペースで区切ったものです。単位には、日数を表す d、時間数を表す h、分数を表す m、秒数を表す s を指定できます。たとえば、"4d 5h" は、ファイルが最初に要求された後のキャッシュの有効期限を 4 日と 5 時間後に設定します。省略した場合は、アプリケーションの default_expiration が使用されます。詳細については、静的キャッシュの有効期限をご覧ください。
http_headers

省略可。静的ファイル ハンドラまたはディレクトリ ハンドラのレスポンスに HTTP ヘッダーを設定できます。Node.js で HTTP ヘッダーを設定する場合は、その設定をアプリのコードで行います。


handlers:
- url: /images
  static_dir: static/images
  http_headers:
    X-Foo-Header: foo
    X-Bar-Header: bar value
  # ...

CORS サポート

この機能の重要な用途の 1 つは、別の App Engine アプリでホストされているファイルへのアクセスなど、クロスオリジン リソース シェアリング(CORS)をサポートすることです。

たとえば、ゲームアプリ mygame.appspot.com から myassets.appspot.com でホストされているアセットにアクセスできます。ただし、mygame が JavaScript XMLHttpRequestmyassets に実行すると、myassets のハンドラが値 http://mygame.appspot.com を含む Access-Control-Allow-Origin: レスポンス ヘッダーを返さない限り、処理が成功しません。

以下の例では、静的ファイル ハンドラが必要なレスポンス ヘッダー値を返しています。


handlers:
- url: /images
  static_dir: static/images
  http_headers:
    Access-Control-Allow-Origin: http://mygame.appspot.com
  # ...

注: すべてのユーザーにアセットに対するアクセスを許可するには、http://mygame.appspot.com ではなく、ワイルドカード '*' を使用します。

mime_type

省略可。指定した場合、このハンドラで処理するすべてのファイルが、指定した MIME タイプを使用して処理されます。指定しない場合、ファイル名の拡張子からファイルの MIME タイプが決定されます。

使用可能な MIME メディア タイプについては、IANA MIME メディア タイプのウェブサイトをご覧ください。

redirect_http_response_code

省略可。secure の設定でリダイレクトが実行されると、redirect_http_response_codesecure 設定を使用して HTTP レスポンス コードを設定します。 redirect_http_response_code 要素には次の値を使用できます。

301
恒久移動のレスポンス コード。
302
検出のレスポンス コード。
303
他のレスポンス コードを参照してください。
307
一時的リダイレクトのレスポンス コード。

ユーザーのリクエストがリダイレクトされると、HTTP ステータス コードが redirect_http_response_code パラメータの値に設定されます。このパラメータが存在しない場合には、302 が返されます。

script

省略可。特定のハンドラへのリクエストでアプリを対象とする必要があることを指定します。すべてのトラフィックが entrypoint コマンドを使用して提供されるため、script 要素で許容される値は auto のみです。静的ハンドラでデプロイに成功するには、ハンドラの少なくとも 1 つに script: auto という行が含まれている必要があります。


handlers:
- url: /images
  static_dir: static/images

- url: /.*
  secure: always
  redirect_http_response_code: 301
  script: auto

secure 省略可。静的ファイル ハンドラを含むすべての URL ハンドラで、secure 設定を使用できます。secure 要素には次の値を使用できます。
optional
HTTP と HTTPS のどちらのリクエストも URL がハンドラと一致すれば成功し、リダイレクトは行われません。アプリケーションは、リクエストを調べてどちらのプロトコルが使われたか確認し、それに従って適切に応答できます。ハンドラで secure が指定されていない場合、これがデフォルトです。
never
リクエストの URL がこのハンドラと一致し、かつ HTTPS を使用している場合、リクエストを対応する HTTP URL に自動的にリダイレクトします。ユーザーの HTTPS リクエストがリダイレクトされて HTTP リクエストになると、クエリ パラメータはリクエストから削除されます。これにより、ユーザーが誤って、保護された接続用のクエリデータを保護されていない接続で送信することを防ぎます。
always
リクエストの URL がこのハンドラと一致し、かつ HTTPS を使用していない場合、リクエストを同じパスの HTTP URL に自動的にリダイレクトします。クエリ パラメータはリダイレクトされても維持されます。

handlers:
- url: /youraccount/.*
  secure: always
  script: auto

appspot.com ドメインを使用している特定のバージョンのアプリを対象とするには、URL のサブドメインを区切るピリオドを文字列 "-dot-" で置き換えます。次に例を示します。


https://[VERSION_ID]-dot-[YOUR_PROJECT_ID].appspot.com

HTTPS でカスタム ドメインを使用するには、そのドメインで SSL 証明書を有効にして構成する必要があります。

Google アカウントのログインとログアウトは常に保護された接続を使用して実行されます。アプリケーションの URL の構成方法とは関係ありません。

static_dir

省略可。アプリケーションのルート ディレクトリから、静的ファイルを含むディレクトリへのパス。static_dir の後に、一致する url パターンより後ろの部分を追加すると、リクエストされたファイルへのフルパスとなります。

各ファイルは、ディレクトリの mime_type の設定で上書きしない限り、ファイル名の拡張子に対応する MIME タイプを使用して処理されます。指定したディレクトリ内のすべてのファイルは静的ファイルとしてアップロードされ、これらのファイルはいずれもスクリプトとして実行することはできません。

例:

handlers:
# All URLs beginning with /stylesheets are treated as paths to
# static files in the stylesheets/ directory.
- url: /stylesheets
  static_dir: stylesheets
  # ...
static_files

省略可。静的ファイル ハンドラを使用して、URL パターンと、アプリケーションとともにアップロードされる静的ファイルへのパスを関連付けます。URL パターンの正規表現を使用して、ファイル パスの構成で使用する正規表現のグループを定義できます。static_dir ではなくこのハンドラを使用すると、ディレクトリ全体にマッピングするのではなく、ディレクトリ構造内の特定のファイルにマッピングできます。

例:

handlers:
# All URLs ending in .gif .png or .jpg are treated as paths to
# static files in the static/ directory. The URL pattern is a
# regular expression, with a grouping that is inserted into the
# path to the file.
- url: /(.*\.(gif|png|jpg))$
  static_files: static/\1
  upload: static/.*\.(gif|png|jpg)$
  # ...

静的ファイルとアプリケーション コードファイルを同じファイルにすることはできません。

upload

省略可。このハンドラによって参照されるすべてのファイルのファイルパスと一致する正規表現。ハンドラでは、アプリケーション ディレクトリ内のどのファイルが、指定した urlstatic_files パターンに対応するのかを特定できないため、この定義が必要になります。静的ファイルは、アプリケーション ファイルと分けてアップロード、処理されます。上の例では、次の upload パターンを使用できます。archives/(.*)/items/(.*)

url

handlers で必要な要素。グループ化を含めることができる正規表現を使用した URL パターンです。たとえば、/profile/(.*)/(.*) は、URL /profile/edit/manager に一致し、editmanager を最初と 2 番目のグループとして使用します。

以下の要素と一緒に使用すると、URL パターンの動作の一部が変わります。

static_dir
URL 接頭辞を使用します。static_dir 要素を使用する場合には、正規表現のパターンにグループ化を使用することはできません。この接頭辞で始まるすべての URL は、このハンドラで処理され、URL の接頭辞より後ろの部分がファイルパスの一部として使用されます。
static_files
静的ファイル ハンドラを使用して、URL パターンと、アプリケーションとともにアップロードされる静的ファイルへのパスを関連付けます。URL パターンの正規表現を使用して、ファイル パスの構成で使用する正規表現のグループ化を定義できます。static_dir ではなくこのハンドラを使用すると、ディレクトリ全体にマッピングするのではなく、ディレクトリ構造内の特定のファイルにマッピングできます。

要素のスケーリング

App Engine アプリのスケーリングの詳細については、動的インスタンスのスケーリングをご覧ください。

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

要素 説明
automatic_scaling

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

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

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

target_cpu_utilization
省略可。0.5〜0.95 の値を指定します。デフォルトは 0.6 です。

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

target_throughput_utilization
省略可。0.5〜0.95 の値を指定します。デフォルトは 0.6 です。

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

max_instances
省略可。0〜2147483647 の値を指定します。0 にするとこの設定が無効になります。

このパラメータは、App Engine がこのモジュール バージョンに対して作成するインスタンスの最大数を指定します。これはモジュールのコストを制限する場合に役立ちます。

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

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

max_concurrent_requests

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

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

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

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

max_idle_instances

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

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

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

max_pending_latency

App Engine がリクエストを保留キューで待機させることができる最長時間。この時間が経過すると、保留待ち時間を短縮できるように、リクエストを処理する新しいインスタンスが起動されます。このしきい値に到達すると、それがスケールアップの信号となり、インスタンス数の増加につながります。デフォルト値は 30ms です。

App Engine は、min_pending_latencymax_pending_latency で指定された時間の間にいつでもインスタンスを作成できます。つまり、App Engine は min_pending_latency で指定された時間より前には、保留中のリクエストを処理するためのインスタンスを作成しませんが、保留待ち時間が max_pending_latency に達するとインスタンスを作成します。

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

動作中でトラフィックを処理する準備ができているインスタンスの数。ただし、トラフィックを受信しているかどうかにかかわらず、指定されたインスタンス数分の料金が請求される点にご注意ください。この設定は、トラフィックの大半を受信するバージョンにのみ適用されます。以下のことに注意してください。

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

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

min_pending_latency

App Engine でリクエストが保留キューで待機する最短時間。この時間が経過すると、リクエストを処理するために新しいインスタンスが起動されます。このしきい値に到達すると、それがスケールダウンの信号となり、インスタンス数の減少につながります。デフォルト値は 30ms です。

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

service: my-service
runtime: nodejs8
instance_class: F2
automatic_scaling:
  max_instances: 11
  target_cpu_utilization: 0.7
basic_scaling

省略可。basic_scaling 要素には、サービスのインスタンス数を設定します。

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

idle_timeout
省略可。最後のリクエストを受信した後、この時間が経過すると、インスタンスはシャットダウンされます。デフォルトは 5 分(5m)です。
max_instances
必須。App Engine によってこのサービスのバージョンに対して作成されるインスタンスの最大数。これはサービスのコストを制限する場合に役立ちます。

service: my-service
runtime: nodejs8
instance_class: B8
basic_scaling:
  max_instances: 11
  idle_timeout: 10m
manual_scaling

省略可。manual_scaling 要素を使用すると、サービスで手動スケーリングを有効にし、サービスのインスタンス数を設定できます。

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

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

service: my-service
runtime: nodejs8
instance_class: B8
manual_scaling:
  instances: 5

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

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

アプリケーションのすべての静的ファイル ハンドラにグローバルなデフォルト キャッシュ期間を定義するには、最上位の default_expiration 要素を追加します。特定の静的ファイル ハンドラのキャッシュ期間を構成することもできます。

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

このページは役立ちましたか?評価をお願いいたします。

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

Node.js 用 App Engine スタンダード環境に関するドキュメント