App Engine app.yaml リファレンス

リージョン ID

REGION_ID は、アプリの作成時に選択したリージョンに基づいて Google が割り当てる省略形のコードです。一部のリージョン ID は、一般的に使用されている国や州のコードと類似しているように見える場合がありますが、このコードは国または州に対応するものではありません。2020 年 2 月以降に作成されたアプリの場合、REGION_ID.r は App Engine の URL に含まれています。この日付より前に作成されたアプリの場合、URL のリージョン ID は省略可能です。

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

App Engine アプリの設定は app.yaml 構成ファイルで構成します。構成ファイルには、少なくとも runtime エントリを指定する必要があります。

アプリ内の各サービスにはそれぞれ独自の app.yaml ファイルがあり、デプロイ記述子として機能します。アプリ内の追加サービス用に app.yaml ファイルを作成してデプロイする前に、default サービスに app.yaml ファイルを作成する必要があります。アプリで複数のサービスを構成する方法については、App Engine でのウェブサービスの構造化をご覧ください。

構文

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

YAML 形式ではコメントがサポートされています。ハッシュ（#）記号で始まる行は無視されます。

# This is a comment.

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

例

app.yaml ファイルの例を次に示します。

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

要素 説明
build_env_variables

省略可。buildpacks をサポートするランタイムを使用している場合は、app.yaml ファイルでビルド環境変数を定義できます。

詳細については、ビルド環境変数の使用をご覧ください。
default_expiration

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

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

省略可。app.yaml ファイルで環境変数を定義すると、アプリでそれらを使用できるようなります。環境変数のキーは式「[a-zA-Z_][a-zA-Z0-9_]*」（つまりアルファベットまたは「_」で始まり、その後に英数字または「_」が続く）に必ず一致する必要があります。

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

省略可。エラータイプごとに表示されるカスタム エラーページの構成に使用します。

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

error_code
省略可。error_code には次のいずれか 1 つを指定できます。
over_quota
アプリがリソース割り当ての上限を超えていることを示します。
timeout
アプリからレスポンスが返される前に時間切れとなった場合に使用されます。

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

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

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

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

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

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

自動スケーリング
F1、F2、F4、F4_1G
デフォルト: F1

必要に応じて、automatic_scaling 要素を使用して、インスタンス、レイテンシ、同時接続の最小数と最大数などの自動スケーリングのデフォルト設定を変更できます。

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

基本スケーリングと手動スケーリング
B1、B2、B4、B4_1G、B8
デフォルト: B2

基本および手動インスタンス クラスでは、basic_scaling 要素または manual_scaling 要素のいずれかを指定する必要があります。
runtime

必須。アプリで使用されるランタイム環境の名前。たとえば、ランタイム環境を指定するには、次のようにします。
service

サービスを作成する場合には必須です。default サービスでは省略できます。サービスとバージョンには名前を付ける必要があります。名前には、数字、英字、ハイフンを使用できます。VERSION-dot-SERVICE-dot-PROJECT_ID 全体の長さ（VERSION はバージョンの名前、SERVICE はサービス名、PROJECT_ID はプロジェクト ID）は、63 文字以下にする必要があります。また、名前の先頭や末尾にハイフンは使用できません。各サービスとバージョンには一意の名前を付ける必要があります。サービスとバージョンに同じ名前を使うことはできません。

例:
service: service-name
service_account

省略可。service_account 要素を使用すると、バージョンの ID としてバージョン固有のサービス アカウントを指定できます。指定されたサービス アカウントは、他の Google Cloud サービスにアクセスしてタスクを実行する際に使用されます。

例:
service_account: [SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com
vpc_access_connector

省略可。サーバーレス VPC アクセス コネクタを使用するようにアプリケーションを構成して、アプリケーションが VPC ネットワークの内部リソースにリクエストを送信できるようにします。詳細については、VPC ネットワークへの接続をご覧ください。

name
文字列リテラル。サーバーレス VPC アクセス コネクタの完全修飾名を引用符で囲んで指定します。
"projects/PROJECT_ID/locations/REGION/connectors/CONNECTOR_NAME"
egress_setting
省略可。デフォルトは private-ranges-only です。egress_setting は、以下のいずれかになります。
private-ranges-only
デフォルト。内部 IP アドレスへのリクエストは、サーバーレス VPC アクセス コネクタ経由で、接続された VPC ネットワークに送信されます。外部 IP アドレスへのリクエストは、公共のインターネットに送信されます。
all-traffic
すべてのリクエストは、サーバーレス VPC アクセス コネクタ経由で、接続された VPC ネットワークに送信されます。
例 
vpc_access_connector:
  name: "projects/PROJECT_ID/locations/REGION/connectors/CONNECTOR_NAME"
  egress_setting: all-traffic

ハンドラ要素

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

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

次の表に、静的ファイル、静的ディレクトリ、Node.js 以外のランタイムのスクリプトの動作、その他の設定を制御する handlers 要素のサブ要素を示します。

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

省略可。静的ファイル ハンドラまたはディレクトリ ハンドラのレスポンスに HTTP ヘッダーを設定できます。

script ハンドラで HTTP ヘッダーを設定するには、アプリコードで設定します。キャッシュ保存に影響を及ぼすレスポンス ヘッダーについては、静的コンテンツのキャッシュ保存をご覧ください。

App Engine 固有のヘッダーの詳細については、リクエスト ヘッダーとレスポンスをご覧ください。

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

CORS サポート

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

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

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

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

ヒント: アセットに誰でもアクセスできるようにするには、https://mygame.uc.r.appspot.com ではなく、ワイルドカード '*' を使用します。
mime_type

省略可。指定すると、このハンドラで処理するすべてのファイルが、指定した MIME タイプを使用して処理されます。指定しないと、ファイル名の拡張子からファイルの MIME タイプが決定されます。同じファイルが複数の拡張子を使用してアップロードされている場合、最終的な拡張子はアップロードが行われた順序によって決まります。

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

省略可。redirect_http_response_code は secure 設定とともに使用され、secure 設定の構成方法により要求されるリダイレクトを行う際に返される HTTP レスポンス コードを設定します。redirect_http_response_code 要素には次の値を使用できます。

301
恒久移動のレスポンス コード。
302
検出のレスポンス コード。
303
他の参照を求めるレスポンス コード。
307
一時的リダイレクトのレスポンス コード。

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

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

REGION_ID.r.appspot.com ドメインを使用しているアプリの特定のバージョンを対象とするには、通常、URL のサブドメイン コンポーネントを区切るピリオドを、文字列「-dot-」で置き換えます。次に例を示します。
https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.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

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

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

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

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

スケーリングの要素

次の表の要素は、アプリケーションのスケーリングを構成します。スケーリング タイプが指定されていない場合、デフォルトで自動スケーリングが設定されます。

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

要素 説明
automatic_scaling

省略可。F1 以上のインスタンス クラスを使用するアプリケーションにのみ適用されます。

この要素を指定して、サービスのインスタンス数、レイテンシ、同時接続数の上限と下限の設定など、自動スケーリングのデフォルト設定を変更します。

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

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

このパラメータは、App Engine がこのモジュール バージョンに対して作成するインスタンスの最大数を指定します。これはモジュールのコストを抑えるうえで有用です

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

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

max_idle_instances

省略可。App Engine がこのバージョンに保持できるアイドル状態のインスタンスの最大数。1～1000 の値を指定します。指定しない場合、デフォルト値は automatic です。つまり、App Engine はアイドル状態のインスタンスの数を管理します。

次の点にご注意ください。

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

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

min_idle_instances

省略可。動作を継続中で、このバージョンのトラフィックの処理に対応できる追加のインスタンスの数。

App Engine は、target_cpu_utilization や target_throughput_utilization などのスケーリング設定に基づいて、現在のアプリケーション トラフィックを処理するために必要なインスタンスの数を計算します。min_idle_instances を設定すると、計算されたインスタンスの数に加えて実行するインスタンスの数を指定できます。たとえば、App Engine がトラフィックの処理に 5 つのインスタンスが必要と計算し、min_idle_instances を 2 に設定した場合、App Engine は 7 つのインスタンスを実行します（トラフィックに基づいて計算された 5 つと、min_idle_instances で追加された 2 つ）。

ただし、トラフィックを受信しているかどうかにかかわらず、指定されたインスタンス数分の料金が請求される点に注意してください。以下のことに注意してください。

  • 最小数を小さく設定すると、アイドル時間にかかるランニング コストは低く抑えられますが、負荷の急増があった場合にすぐに対処できるインスタンスの数が少なくなります。

  • 最小数を大きく設定すると、アプリケーションがリクエスト負荷の急増に対応できるようになります。App Engine では、受信リクエストを処理するために最小数のインスタンスが常に実行されています。指定された数のインスタンスについては、リクエストを処理しているかどうかにかかわらず、そのインスタンス数分の料金が請求されます。

    アイドル インスタンスの最小数を設定すると、保留待ち時間がアプリケーションのパフォーマンスに与える影響は小さくなります。

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_requests と target_throughput_utilization の積に等しい値に達すると、スケジューラは新しいインスタンスを起動します。

max_concurrent_requests

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

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

シングル スレッドが必要でない限り、max_concurrent_requests を 10 未満に設定しないようおすすめします。値が 10 未満の場合、スレッドセーフなアプリ向けに必要数を上回る数のインスタンスが作成されて、不必要な費用が発生する可能性があります。

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

max_pending_latency

App Engine でリクエストが保留キューで待機できる最長時間。この時間を経過すると、リクエストを処理する新しいインスタンスが起動されて保留待ち時間が短くなります。このしきい値に達すると、それがスケールアップのきっかけとなり、インスタンス数の増加につながります。

指定しない場合、デフォルト値は automatic です。つまり、新しいインスタンスが起動されるまで、リクエストは最大 10 秒間（保留中のリクエスト時間の上限）まで保留キュー内に残ります。

最長時間を短く設定すると、保留中のリクエストに対処する新しいインスタンスの作成が早くなります。パフォーマンスは向上しますが、ランニング コストも高くなります。

最長時間を長く設定すると、ユーザーがリクエストの処理を待つ時間は長くなる可能性があります（保留中のリクエストがあり、それらに対処するアイドル インスタンスがない場合）が、アプリケーションのランニング コストは低くなります。

min_pending_latency

App Engine でリクエストを保留キューで待機させる最短時間を指定できるオプション要素です。この時間が経過すると、リクエストを処理するために新しいインスタンスが起動されます。値を指定すると、ランニング コストは低くなりますが、ユーザーがリクエストの処理を待つ時間は長くなります。

無料アプリの場合、デフォルト値は 500ms です。有料アプリの場合、デフォルト値は 0 です。

この要素が max_pending_latency 要素と連携することにより、App Engine が新しいインスタンスを作成するタイミングが決定されます。保留中のリクエストがキューにある場合:

  • 指定した min_pending_latency 未満の場合、App Engine は新しいインスタンスを作成しません。
  • max_pending_latency を超えると、App Engine は新しいインスタンスの作成を試みます。
  • min_pending_latency と max_pending_latency で指定された期間に、App Engine は既存インスタンスの再利用を試みます。max_pending_latency までにリクエストを処理できるインスタンスがない場合、App Engine は新しいインスタンスを作成します。
例 
automatic_scaling:
  target_cpu_utilization: 0.65
  min_instances: 5
  max_instances: 100
  min_pending_latency: 30ms
  max_pending_latency: automatic
  max_concurrent_requests: 50
basic_scaling

B1 以上のインスタンス クラスを使用するアプリケーションは、この要素または manual_scaling を使用する必要があります。

この要素は、インスタンス クラス B1 以上の基本スケーリングを有効にし、次の要素を含めることができます。

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

B1 以上のインスタンス クラスを使用するアプリケーションは、この要素または basic_scaling を使用する必要があります。

この要素を使用すると、B1 以上のインスタンス クラスを手動でスケーリングできます。また、次のような要素を追加することもできます。

instances
起動時にサービスに割り当てるインスタンスの数。
例
manual_scaling:
  instances: 5