app.yaml リファレンス

Python 2.7/3.7 |Java 8/11 |PHP 5/7 |Ruby |Go 1.9/1.11/1.12 |Node.js

App Engine アプリは app.yaml ファイルで構成します。このファイルでは、URL パスとリクエスト ハンドラや静的ファイルとの対応関係を指定します。app.yaml ファイルには、ランタイムや最新バージョンの ID など、アプリコードについての情報も記載されています。

アプリ内の各サービスにはそれぞれ独自の app.yaml ファイルがあり、デプロイ記述子として機能します。アプリ内の追加サービス用に app.yaml ファイルを作成してデプロイする際は、事前に default サービス用の app.yaml ファイルを作成する必要があります。

ディレクトリ構造

各サービスには、そのルート ディレクトリ内に app.yaml ファイルが必要です。アプリ内の複数のサービスの構造化については、App Engine でのウェブサービスの構造化をご覧ください。

例

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

runtime: python27
api_version: 1
threadsafe: true

handlers:
- url: /
  script: home.app

- url: /index\.html
  script: home.app

- url: /stylesheets
  static_dir: stylesheets

- url: /(.*\.(gif|png|jpg))$
  static_files: static/\1
  upload: static/.*\.(gif|png|jpg)$

- url: /admin/.*
  script: admin.app
  login: admin

- url: /.*
  script: not_found.app

script: ディレクティブには、.py で終わるファイルパスを指定できます。この場合、スクリプトは CGI を使用します。また、パッケージ名をドットで区切った Python モジュールのパスを指定することもできます。この場合、スクリプトは WSGI を使用します。

構文

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

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

# This is a comment.

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

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

要素	説明
application	警告: appcfg ツールの使用だけでなく、application 要素も非推奨になりました。gcloud コマンドラインなどの Cloud SDK ツールを使用してアプリケーションを指定するには、次の手順をご覧ください。 app.yaml ファイルから application 要素を削除し、代わりにコマンドライン フラグを使用してアプリケーション ID を指定することをおすすめします。 gcloud app deploy コマンドを使用するには、--project フラグを指定します。 gcloud app deploy --project [YOUR_PROJECT_ID] appcfg.py update コマンドを使用するには、-A フラグを指定します。 appcfg.py update -A [YOUR_PROJECT_ID] これらのコマンドの詳細については、アプリのデプロイをご覧ください。 アプリケーション ID は、Google Cloud Platform Console でアプリケーションを作成したときに指定した GCP Console プロジェクト ID です。
api_version	必須。アプリで使用される特定のランタイム環境における API のバージョンです。 Google がランタイム環境の API の新バージョンのサポートを発表しても、デプロイされたアプリはその作成時に使用された API を引き続き使用します。アプリを新バージョンの API にアップグレードするには、この値を変更して、アプリを App Engine に再デプロイします。値を 1 に設定すると、そのアプリをデプロイするたびに、サポートされている最新のランタイム環境が使用されます（現在は ）。 現在、App Engine の python27 ランタイム環境のバージョンは 1 です。
auto_id_policy	省略可。エンティティ ID を自動的に設定している場合、自動 ID ポリシーを設定すると、使用するメソッドを変更できます。有効なオプションは次のとおりです。 default デフォルト。64 ビット浮動小数点として表現可能で、適度に分散された ID を自動的に割り当てます。 legacy レガシー オプションは今後のリリースで非推奨となり、最終的に削除される予定です。詳細については、この変更を発表したブログ記事をご覧ください。
builtins	省略可。Python 2 SDK には、一般的なアプリケーション機能向けの複数の組み込みハンドラが含まれています。builtins ディレクティブを使用すると、特定のハンドラを app.yaml に含めることができます。 使用できる組み込みハンドラは次のとおりです。 appstats /_ah/stats/ にある Appstats を有効にします。これにより、アプリケーションのパフォーマンスを測定できます。Appstats を使用するには、イベント レコーダをインストールする必要もあります。 deferred /_ah/queue/deferred にある遅延ハンドラを有効にします。 この組み込みハンドラにより、デベロッパーは deferred.defer() を使用してタスクキューのタスクを簡単に作成できるようになります。遅延ライブラリのバックグラウンド作業もご覧ください。 remote_api /_ah/remote_api/ にある remote_api を有効にします。この組み込みハンドラにより、リモート アプリケーションで適切な認証情報を使用してデータストアにリモート アクセスできます。 例: builtins: - deferred: on - appstats: on builtins ディレクティブは、includes ディレクティブの特別なインスタンスです。Python では、各 builtin ディレクティブはパスを展開した includes ディレクティブと同等です。例: builtins: - name: on これは次と同等です。 includes: - $PYTHON_LIB/google/appengine/ext/builtins/name/ app.yaml ファイルで builtins を使用する場合、組み込み include.yaml ファイルで定義されているハンドラは、app.yaml ファイルで定義したハンドラよりも優先されます。ただし、builtins または includes を使用するファイルをインクルードすると、インクルード階層の順番でハンドラが追加されます。つまり、親インクルードのハンドラは、子インクルードの組み込みよりも前に追加されます。 たとえば、次の app.yaml では、組み込みの appstats ハンドラを使用しています。 handlers: - url: /.* script: main.app builtins: - appstats: on ハンドラの結果リストは次のようになります。 [/_ah/stats, /.*] app.yaml が includes ディレクティブを使用する場合: includes: - included.yaml さらに、included.yaml ファイルが builtins を使用する場合: handlers: - url: /.* script: main.app builtins: - appstats: on ハンドラの結果リストは次のようになります。 [/.*, /_ah/stats] .yaml ファイル内で builtins 句が配置される順序によって動作は変化しません。
default_expiration	省略可。アプリケーションのすべての静的ファイル ハンドラにグローバルなデフォルト キャッシュ期間を設定します。特定の静的ファイル ハンドラを対象にキャッシュ期間を設定することもできます。設定する値は、数値と単位の文字列をスペースで区切ったものです。単位には、日数を表す d、時間数を表す h、分数を表す m、秒数を表す s を指定できます。たとえば、"4d 5h" と指定すると、キャッシュの有効期限はファイルが最初にリクエストされてから 4 日と 5 時間後に設定されます。省略すると、本番環境のサーバーは有効期限を 10 分に設定します。 例: runtime: python27 api_version: 1 threadsafe: true default_expiration: "4d 5h" handlers: # ... 詳細については、静的キャッシュの有効期限をご覧ください。
env_variables	省略可。アプリで使用できるように、app.yaml ファイルで環境変数を定義できます。 GAE という接頭辞が付いた環境変数はシステム用に予約されており、app.yaml ファイルでは使用できません。 これらの変数は os.environ 辞書で利用できます。 env_variables: DJANGO_SETTINGS_MODULE: "myapp.settings"
error_handlers	省略可。エラータイプごとに表示されるカスタム エラーページの構成に使用します。 この要素には次の要素を設定できます。 error_code 省略可。error_code には次のいずれか 1 つを指定できます。 over_quota アプリがリソース割り当ての上限を超えていることを示します。 dos_api_denial リクエストがアプリの DoS 防御サービスの構成でブロックされたことを示します。 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 など、コードと一緒にアップロードされた静的ファイルを提供します。 ハンドラとサブ要素の構文をご覧ください。
includes	省略可。includes ディレクティブを使用すると、アプリケーション内の任意のライブラリまたはサービスの構成ファイルをインクルードできます。たとえば、次のようにユーザー管理ライブラリをインクルードします。 includes: - lib/user_admin.yaml App Engine では、インクルードしたパスが次の順序で解決されます。 作業ディレクトリへの絶対パスまたは相対パス。指定したパスはファイルに解決されます。 アプリケーション ディレクトリへの相対パス（ベースパスとも呼ばれます）。ベースパスとパスはファイルに解決されます。 現在のファイルをインクルードしたファイルへの相対パス。参照しているファイルの場所とインクルード パスはインクルードしたファイルに解決されます。 include ディレクティブでディレクトリが指定されている場合、App Engine はそのディレクトリで include.yaml というファイルを探します。インクルード ディレクティブがファイルの場合は、そのファイルがインクルードされます。includes を使用すると、次の種類のディレクティブだけが宛先ファイルから取得されます（存在する場合）。 builtins includes handlers skip_files インクルードされた skip_files パターンがインクルード先の app.yaml のディレクティブに追加されます。app.yaml に明示的なリストがない場合には、デフォルトのリストに追加されます。skip_files は絶対パスを比較することに注意してください。
inbound_services	省略可。アプリケーションが受信リクエストを受け取るには、これらのサービスを有効にする必要があります。Python 2 アプリ用にサービスを有効にするには、inbound_services セクションを app.yaml ファイルに含めます。 使用できる受信サービスは次のとおりです。 mail アプリケーションにメールの受信を許可します。 warmup ウォームアップ リクエストを有効にします。ウォームアップ リクエストの構成をご覧ください。 例: inbound_services: - mail - warmup
instance_class	省略可。このサービスのインスタンス クラス。 サービスのスケーリングに応じて、次の値を使用できます。 自動スケーリング F1、F2、F4、F4_1G デフォルト: automatic_scaling 要素とともにインスタンス クラスを指定しない場合は、F1 が割り当てられます。 基本スケーリングと手動スケーリング B1、B2、B4、B4_1G、B8 デフォルト: basic_scaling 要素または manual_scaling 要素とともにインスタンス クラスを指定しない場合は、B2 が割り当てられます。 注: instance_class が F2 以上に設定されている場合、max_concurrent_requests を 10（デフォルト）より大きい値に設定することで、インスタンスを最適化できます。最適な値を見つけるには、値を少しずつ増やしながらアプリケーションのパフォーマンスをモニタリングします。
libraries	省略可。Python 2.7 ランタイムには、一部のサードパーティ ライブラリが含まれています。これらの一部はデフォルトで使用できますが、それ以外は使用前に構成が必要です。name 値と version 値を指定して、使用するバージョンを指定できます。 libraries: - name: PIL version: "1.1.7" - name: webob version: "latest" latest を指定すると、デプロイするときに最新のライブラリ バージョンが取得されます。デプロイ後、ライブラリ バージョンは変更されません。ライブラリの異なるバージョンを取得するには、デプロイをやり直す必要があります。 開発中のアプリケーションにユーザーが存在しない場合には、新しいバージョンを追跡する必要はありません。ただし、アプリケーションを実際に使用している場合、下位互換性のない新しいライブラリ バージョンがアプリケーションで使用される可能性があります。 使用可能なサードパーティ ライブラリの一覧については、サードパーティ ライブラリをご覧ください。ローカル ディレクトリにインストールすることで、追加のピュア Python サードパーティ ライブラリを使用できます。 フレキシブル環境を使用している場合には、フレキシブル環境での Python ライブラリの使用をご覧ください。
module	注: モジュールは名称がサービスに変わりました。 gcloud ツールでアプリを管理するには、代わりに service 要素を使用します。 appcfg ツールを使用するには、app.yaml ファイルでモジュールとしてサービスを宣言する必要があります。次に例を示します。 module: service-name 警告: appcfg ツールの使用だけでなく、module 要素も非推奨になりました。gcloud コマンドラインなどの Cloud SDK ツールを使用してアプリケーションを指定するには、次の手順をご覧ください。 サービスを作成する場合には必須です。 default サービスでは省略できます。サービスとバージョンには名前を付ける必要があります。名前には、数字、英字、ハイフンを使用できます。サービスとバージョンを組み合わせた長さは、63 文字以下にする必要があります。また、名前の始まりと末尾にハイフンは使用できません。各サービスとバージョンには一意の名前を付ける必要があります。サービスとバージョンに同じ名前を使うことはできません。
runtime	必須。アプリで使用されるランタイム環境の名前です。Python 2.7 を指定するには、次のようにします。 runtime: python27
service	サービスは以前「モジュール」と呼ばれていました。 gcloud ツールまたは Cloud SDK ベースのプラグインのみでサポートされます。例: gcloud app deploy appcfg ツールの使用については、モジュールをご覧ください。 サービスを作成する場合には必須です。 default サービスでは省略できます。サービスとバージョンには名前を付ける必要があります。名前には、数字、英字、ハイフンを使用できます。サービスとバージョンを組み合わせた長さは、63 文字以下にする必要があります。また、名前の始まりと末尾にハイフンは使用できません。各サービスとバージョンには一意の名前を付ける必要があります。サービスとバージョンに同じ名前を使うことはできません。 例: service: service-name 注: gcloud app deploy コマンドは後方互換性があり、モジュールとして宣言されたサービスを含む既存の app.yaml ファイルもサポートします。次に例を示します。 module: service-name
skip_files	省略可。skip_files 要素には、アプリケーション ディレクトリ内にあるファイルのうち、App Engine にアップロードしないものを指定します。値は、1 つの正規表現または正規表現のリストです。ファイル名が正規表現と一致する場合、そのファイル名はアプリケーションがアップロードされるときに、アップロードするファイルのリストから除外されます。ファイル名はプロジェクト ディレクトリからの相対名です。 skip_files には以下のデフォルトが設定されています。 skip_files: - ^(.*/)?#.*#$ - ^(.*/)?.*~$ - ^(.*/)?.*\.py[co]$ - ^(.*/)?.*/RCS/.*$ - ^(.*/)?\..*$ デフォルトのパターンでは、名前が #...# および ...~ という形式の Emacs バックアップ ファイル、.pyc および .pyo ファイル、RCS リビジョン コントロール ディレクトリのファイル、ピリオド（.）で始まる Unix 隠しファイルが除外されます。 上の正規表現リストを拡張するには、上のリストをコピーして app.yaml に貼り付け、独自の正規表現を追加します。たとえば、デフォルトのパターンに加えて名前が .bak で終わるファイルをスキップするには、skip_files で次のようなエントリを追加します。 skip_files: - ^(.*/)?#.*#$ - ^(.*/)?.*~$ - ^(.*/)?.*\.py[co]$ - ^(.*/)?.*/RCS/.*$ - ^(.*/)?\..*$ - ^(.*/)?.*\.bak$ ディレクトリ全体をスキップするには、リストにディレクトリ名を追加します。たとえば、logs という名前のディレクトリをスキップするには、前述の行に次の行を追加します。 skip_files: - logs/
threadsafe	必須。同時リクエストを利用するようにアプリケーションを構成します。Python のスレッド ライブラリを使用している場合は、threading.local() によって返されるスレッド ローカルデータが各リクエストの後にクリアされます。 threadsafe: [true | false] 注: Python 2.7 アプリケーションには、threadsafe ディレクティブが必要です。threadsafe: true の場合、すべてのスクリプト ハンドラは WSGI でなければなりません。つまり、パッケージ名をドットで区切った Python モジュールのパスを使用して、script: ディレクティブに各スクリプトを指定する必要があります。Python モジュールのパスを使用した script: ディレクティブの最後の要素は、service: のグローバル変数名です。その変数は WSGI アプリとし、通常は慣例に従って app という名前を付けます。
version	app.yaml ファイルから version 要素を削除し、代わりにコマンドライン フラグを使用してバージョン ID を指定することをおすすめします。 gcloud app deploy コマンドを使用するには、-v フラグを指定します。 gcloud app deploy -v [YOUR_VERSION_ID] appcfg.py update コマンドを使用するには、-V フラグを指定します。 appcfg.py update -V [YOUR_VERSION_ID] 警告: appcfg ツールは非推奨になりました。 gcloud コマンドラインなどの Cloud SDK ツールを使用してください。 これらのコマンドの詳細については、アプリのデプロイをご覧ください。 App Engine にデプロイするアプリケーション コードのバージョン ID。 バージョン ID には、小文字、数字、ハイフンを使用できます。接頭辞 ah- で始めることはできず、名前 default と latest は予約されているので使用できません。 注: バージョン名は、常に番号で指定される数値インスタンスと区別するために、英字で始まる必要があります。これにより、123.my-service.appspot.com のような URL の曖昧さを回避できます。この URL は、2 通りに解釈できます。バージョン 123 が存在する場合は、指定されたサービスのバージョン 123 がターゲットになります。そのバージョンが存在しない場合は、このサービスのデフォルト バージョンのインスタンス番号 123 がターゲットになります。 アプリケーションの各バージョンには app.yaml の独自のコピーが維持されます。アプリケーションをアップロードすると、アップロードされる app.yaml ファイルのバージョンは、アップロードで作成または置換されるバージョンになります。管理者は、Google Cloud Platform Console を使用して、トラフィックを処理するアプリケーションのバージョンを変更できます。また、トラフィックの受信を構成する前に他のバージョンをテストすることもできます。
vpc_access_connector	省略可。サーバーレス VPC アクセス コネクタを使用するようにアプリケーションを構成して、アプリケーションが VPC ネットワークの内部リソースにリクエストを送信できるようにします。name フィールドにコネクタの完全修飾名を指定します。 vpc_access_connector: name: "projects/[PROJECT_ID]/locations/[REGION]/connectors/[CONNECTOR_NAME]" 詳細については、VPC ネットワーク内の内部リソースへの接続をご覧ください。

handlers 要素

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

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

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

要素	説明
application_readable	省略可。ブール値。デフォルトでは、静的ファイル ハンドラで宣言されたファイルが静的データとしてアップロードされ、エンドユーザーにのみ提供されます。アプリケーションでは読み取れません。このフィールドを true に設定すると、ファイルはコードデータとしてもアップロードされ、アプリケーションでも読み取れるようになります。両方のアップロードが、コードデータと静的データのストレージ リソース割り当てとして課金されます。
auth_fail_action	省略可。ハンドラに login 要素が指定され、ユーザーがログインしていないときに実行されるアクションを記述します。使用可能な値は次の 2 つです。 redirect デフォルト。ユーザーは Google ログインページまたは /_ah/login_required（OpenID 認証を使用している場合）にリダイレクトされます。ログイン後またはアカウント作成後のユーザーをリダイレクトしてアプリケーション URL に戻します。 unauthorized リクエストを拒否し、HTTP 401 ステータス コードとエラー メッセージを返します。 異なる動作を必要とするアプリケーションでは、ユーザーのログイン処理を実装できます。詳細については、Users API をご覧ください。 次の例では、/profile/ ディレクトリでログインを必須とし、/admin/ ディレクトリでは管理者のログインを必須としています。 handlers: - url: /profile/.* script: user_profile.app login: required - url: /admin/.* script: admin.app login: admin - url: /.* script: welcome.app ハンドラの構成に auth_fail_action: unauthorized を追加すると、ユーザーがログインしていないときに、ユーザーをログインページにリダイレクトせず、保護された URL に対するアクセスを拒否するようにハンドラを構成できます。 handlers: - url: /secure_api/.* script: api_handler.app login: required auth_fail_action: unauthorized
expiration	省略可。このハンドラで処理する静的ファイルがウェブプロキシとウェブブラウザでキャッシュに保存される有効期限。設定する値は、数値と単位の文字列をスペースで区切ったものです。単位には、日数を表す d、時間数を表す h、分数を表す m、秒数を表す s を指定できます。たとえば、"4d 5h" と指定すると、キャッシュの有効期限はファイルが最初にリクエストされてから 4 日と 5 時間後に設定されます。省略した場合は、アプリケーションの default_expiration が使用されます。詳細については、静的キャッシュの有効期限をご覧ください。
http_headers	省略可。静的ファイル ハンドラまたはディレクトリ ハンドラのレスポンスに HTTP ヘッダーを設定できます。script ハンドラで 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 が myassets に対して JavaScript の XMLHttpRequest を実行する場合、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 ではなく、ワイルドカード '*' を使用します。
login	省略可。URL ハンドラがユーザーによるログインを必要とするかどうかを決定します。この要素には次の 3 つの値を使用できます。 optional デフォルト。ユーザーによるログインを必要としません。 required ログインしているユーザーに対して、ハンドラは通常どおり処理を進めます。ログインしていないユーザーに対しては、auth_fail_action のアクションを実行します。 admin required と同様、ユーザーがログインしていない場合に auth_fail_action を実行します。また、ユーザーがアプリケーションの管理者でない場合は、auth_fail_action の設定にかかわらずエラー メッセージを表示します。管理者の場合、ハンドラはそのまま処理を続けます。 login が optional 以外に設定された URL ハンドラが URL と一致する場合は、まず、ユーザーが認証オプションを使用してアプリケーションにログインしているかどうかが確認されます。ログインしていない場合は、デフォルトでログインページにリダイレクトされます。auth_fail_action を使用すると、適切に認証されていないユーザーがハンドラをリクエストしたときに、そのユーザーをログインページにリダイレクトしないでリクエストを拒否するようにアプリを構成することもできます。 注: admin ログイン制限は、App Engine が内部リクエストに適切な X-Appengine 特殊ヘッダーを設定することによっても満たされます。たとえば、cron スケジュール タスクは、App Engine がリクエストの HTTP ヘッダー X-AppEngine-Cron: true を設定するので、admin 制限を満たします。ただし、cron スケジュール タスクは特定のユーザーとして実行されないため、このリクエストは required ログイン制限を満たしません。
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 一時的リダイレクトのレスポンス コード。 例 handlers: - url: /youraccount/.* script: accounts.app login: required secure: always redirect_http_response_code: 301 ユーザーのリクエストがリダイレクトされると、HTTP ステータス コードが redirect_http_response_code パラメータの値に設定されます。このパラメータが存在しない場合には、302 が返されます。
script	省略可。 アプリケーションのルート ディレクトリを起点として、このスクリプトまでのパスを指定します。 handlers: # The root URL (/) is handled by the WSGI application named # "app" in home.py. No other URLs match this pattern. - url: / script: home.app # The URL /index.html is also handled by the home.py script. - url: /index\.html script: home.app # A regular expression can map parts of the URL to the # path of the script. - url: /browse/(books|videos|tools) script: \1.catalog.app # All other URLs use the WSGI application named in "app" # in not_found.py. - url: /.* script: not_found.app script: ディレクティブは、Python のインポートパスです。たとえば、package.module.app は WSGI アプリケーションを参照します。Python モジュールのパスを使用した script: ディレクティブの最後の要素は、モジュールのグローバル変数名です。その変数は WSGI アプリとし、通常は慣例に従って app という名前を付けます。 Python の import ステートメントと同様に、パッケージである各サブディレクトリには __init__.py という名前のファイルが存在している必要があります。
secure	省略可。secure の設定は、スクリプト ハンドラと静的ファイル ハンドラを含むすべての URL ハンドラで使用できます。secure 要素には次の値を使用できます。 optional リクエストが HTTP か HTTPS を問わず、URL がハンドラと一致すれば成功し、リダイレクトは行われません。アプリケーションは、リクエストを調べてどちらのプロトコルが使われたか確認し、それに従って適切に応答できます。ハンドラで secure が指定されていない場合、これがデフォルトです。 never リクエストの URL がこのハンドラと一致し、かつ HTTPS を使用している場合、リクエストを対応する HTTP URL に自動的にリダイレクトします。ユーザーの HTTPS リクエストがリダイレクトされて HTTP リクエストになると、クエリ パラメータはリクエストから削除されます。これにより、ユーザーが誤って、保護された接続で送信すべきクエリデータを保護されていない接続で送信することを防ぎます。 always リクエストの URL がこのハンドラと一致し、かつ HTTPS を使用していない場合、リクエストを同じパスの HTTPS URL に自動的にリダイレクトします。クエリ パラメータはリダイレクトされても維持されます。 例 handlers: - url: /youraccount/.* script: accounts.app login: required secure: always 開発用ウェブサーバーでは HTTPS 接続はサポートされていません。開発用ウェブサーバーでは secure パラメータが無視されるので、開発用ウェブサーバーとの間に通常の HTTP 接続を使用して、HTTPS 用のパスをテストできます。 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 タイプを使用して処理されます。指定したディレクトリ内のすべてのファイルは静的ファイルとしてアップロードされ、これらのファイルはいずれもスクリプトとしては実行できません。 このディレクトリ内のすべてのファイルは、静的ファイルとしてアプリと一緒にアップロードされます。App Engine は、静的ファイルをアプリのファイルと分けて格納し、処理します。デフォルトでは、アプリのファイル システムで静的ファイルを使用できません。これを変更するには、application_readable オプションを true に設定します。 例 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)$ # ... App Engine は、静的ファイルをアプリケーション ファイルと分けて格納し、処理します。デフォルトでは、アプリケーションのファイル システムで静的ファイルを使用できません。これを変更するには、application_readable オプションを true に設定します。 静的ファイルとアプリケーション コードファイルを同じファイルにすることはできません。静的ファイルのパスが動的ハンドラで使用するスクリプトへのパスと一致する場合、動的ハンドラではスクリプトを使用できません。
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 が使用されます。 automatic_scaling 要素には、サービスのインスタンス、レイテンシ、同時接続の最小数と最大数を設定します。 この要素には次の要素を設定できます。 target_cpu_utilization 省略可。0.5～0.95 の値を指定します。デフォルトは 0.6 です。 このパラメータは、トラフィックを処理する新しいインスタンスを起動するための CPU 使用率のしきい値を指定します。これにより、パフォーマンスとコストのバランスをとることができます。値を小さくするほど、パフォーマンスが向上してコストは増加し、値を大きくするほどパフォーマンスは低下してコストが削減されます。たとえば、値を 0.7 にした場合、CPU 使用率が 70% に達すると新しいインスタンスが起動されます。 重要: Python 2 用 App Engine SDK から appcfg を使用してデプロイする場合、app.yaml でこのパラメータを使用することはできません。代わりに、API Explorer での自動スケーリング パラメータの設定の手順を実施するか、App Engine Admin API を使用して、このパラメータを設定します。 target_throughput_utilization 省略可。0.5～0.95 の値を指定します。デフォルトは 0.6 です。 max_concurrent_requests とともに使用して、同時リクエストによって新しいインスタンスが起動されるタイミングを指定します。同時リクエストの数が max_concurrent_requests と target_throughput_utilization の積に等しい値に達すると、スケジューラは新しいインスタンスを起動します。 重要: Python 2 用 App Engine SDK から appcfg を使用してデプロイする場合、app.yaml でこのパラメータを使用することはできません。代わりに、API Explorer での自動スケーリング パラメータの設定の手順を実施するか、App Engine Admin API を使用して、このパラメータを設定します。 max_instances 省略可。0～2147483647 の値を指定します。0 にするとこの設定が無効になります。 このパラメータは、App Engine がこのモジュール バージョンに対して作成するインスタンスの最大数を指定します。これはモジュールのコストを抑えるのに役立ちます。 重要: Python 2 用 App Engine SDK から appcfg を使用してデプロイする場合、app.yaml でこのパラメータを使用することはできません。代わりに、API Explorer での自動スケーリング パラメータの設定の手順を実施するか、App Engine Admin API を使用して、このパラメータを設定します。 min_instances 省略可。App Engine がこのモジュール バージョンに対して作成するインスタンスの最小数。これらのインスタンスは、リクエストが届いたときにトラフィックを処理し、トラフィックを処理するために必要な追加インスタンスが起動されてもトラフィックを処理し続けます。 0～1000 の値を指定します。このパラメータを 0 に設定すると、リクエストが処理されていないときにインスタンス数を 0 にスケールしてコストを削減できます。ただし、トラフィックを受信しているかどうかにかかわらず、指定されたインスタンス数分の料金が請求される点に注意してください。 重要: Python 2 用 App Engine SDK から appcfg を使用してデプロイする場合、app.yaml でこのパラメータを使用することはできません。代わりに、API Explorer での自動スケーリング パラメータの設定の手順を実施するか、App Engine Admin API を使用して、このパラメータを設定します。 max_concurrent_requests 省略可。自動スケーリング インスタンスが受け入れることのできる同時リクエスト数。この数を超えると、スケジューラによって新しいインスタンスが生成されます（デフォルト: 10、最大: 80）。 target_throughput_utilization とともに使用して、同時リクエストによって新しいインスタンスが起動されるタイミングを指定します。同時リクエストの数が max_concurrent_requests と target_throughput_utilization の積に等しい値に達すると、スケジューラは新しいインスタンスを起動します。 この値が大きすぎると、API のレイテンシが増加する場合があります。リクエストの最大数に達する前にスケジューラが新しいインスタンスを生成する場合もあります。 注: instance_class が F2 以上に設定されている場合、max_concurrent_requests を 10（デフォルト）より大きい値に設定することで、インスタンスを最適化できます。最適な値を見つけるには、値を少しずつ増やしながらアプリケーションのパフォーマンスをモニタリングします。 max_idle_instances 省略可。App Engine がこのバージョンに保持できるアイドル状態のインスタンスの最大数。1～1000 の値、または automatic を指定します。デフォルト値は automatic です。以下のことに注意してください。 最大数を大きく設定すると、負荷レベルの急増後に通常のレベルに戻る際に、アイドル インスタンスの数がより緩やかに減っていきます。その結果、アプリケーションがリクエスト負荷変動の前後を通じて安定したパフォーマンスを維持しやすくなる一方で、そのような負荷の高い期間のアイドル インスタンスの数（その結果としてランニング コスト）も増えます。 最大数を小さく設定すると、ランニング コストは低く抑えられますが、負荷レベルの変動があったときにパフォーマンスが低下する可能性があります。 注: 負荷の急増後に通常のレベルに戻るときに、アイドル インスタンスの数が指定した最大数を一時的に超える可能性があります。この場合、指定した最大数を超える分について料金が請求されることはありません。 max_pending_latency App Engine でリクエストが保留キューで待機できる最長時間。この時間を経過すると、リクエストを処理する新しいインスタンスが起動されて保留待ち時間が短くなります。このしきい値に達すると、それがスケールアップのきっかけとなり、インスタンス数の増加につながります。デフォルト値は 30ms です。 App Engine は、min_pending_latency と max_pending_latency で指定された時間の間にいつでもインスタンスを作成できます。つまり、App Engine は min_pending_latency で指定された時間より前には、保留中のリクエストを処理するためのインスタンスを作成しませんが、保留待ち時間が max_pending_latency に達するとインスタンスを作成します。 最大時間を短く設定すると、保留中のリクエストに対処する新しいインスタンスの作成が早くなります。パフォーマンスは向上しますが、ランニング コストも高くなります。 最大時間を長く設定すると、ユーザーがリクエストの処理を待つ時間は長くなる可能性があります（保留中のリクエストがあり、それに対処するアイドル インスタンスがない場合）が、アプリケーションのランニング コストは低くなります。 min_idle_instances 動作を継続中で、トラフィックの処理に対応できるインスタンス数。ただし、トラフィックを受信しているかどうかにかかわらず、指定されたインスタンス数分の料金が請求される点に注意してください。この設定は、トラフィックの大半を受信するバージョンにのみ適用されます。以下のことに注意してください。 最小数を小さく設定すると、アイドル時間にかかるランニング コストは低く抑えられますが、負荷の急増があった場合にすぐに対処できるインスタンスの数が少なくなります。 最小数を大きく設定すると、アプリケーションがリクエスト負荷の急増に対応できるようになります。App Engine では、受信リクエストを処理するために最小数のインスタンスが常に実行されています。指定された数のインスタンスについては、リクエストを処理しているかどうかにかかわらず、そのインスタンス数分の料金が請求されます。この機能を適切に機能させるには、ウォームアップ リクエストが有効で、アプリケーションがウォームアップ リクエストを処理していることを確認する必要があります。 アイドル インスタンスの最小数を設定すると、保留待ち時間がアプリケーションのパフォーマンスに与える影響は小さくなります。App Engine では一定数のアイドル インスタンスが常に確保されるため、異常なほど負荷が急増した場合を除き、リクエストが保留中のキューに入る可能性は低くなります。理想的な予約インスタンス数を判定するには、アプリケーションと予測トラフィック量をテストする必要があります。 min_pending_latency App Engine でリクエストが保留キューで待機する最短時間。この時間が経過すると、リクエストを処理するために新しいインスタンスが起動されます。このしきい値に達すると、それがスケールダウンのきっかけとなり、インスタンス数の減少につながります。デフォルト値は 30ms です。 最小待ち時間を短く設定すると、既存のインスタンスがすべて稼動中のときにリクエストが保留中のキューにとどまる時間が短くなります。パフォーマンスは向上しますが、アプリケーションのランニング コストも高くなります。 最小時間を長く設定すると、既存のインスタンスがすべて稼動中のときにリクエストが保留中のキューにとどまる時間が長くなります。ランニング コストは低くなりますが、ユーザーがリクエストの処理を待つ時間は長くなります。 例 service: my-service runtime: python27 api_version: 1 instance_class: F2 automatic_scaling: target_cpu_utilization: 0.65 min_instances: 5 max_instances: 100 min_pending_latency: 30ms # default value max_pending_latency: automatic max_concurrent_requests: 50
basic_scaling	省略可。basic_scaling 要素には、サービスのインスタンス数を設定します。 この要素には次の要素を設定できます。 idle_timeout 省略可。最後のリクエストを受信した後、この時間が経過すると、インスタンスはシャットダウンされます。デフォルトは 5 分（5m）です。 max_instances 必須。App Engine によってこのサービスのバージョンに対して作成されるインスタンスの最大数。これはサービスのコストを抑えるのに役立ちます。 例 service: my-service runtime: python27 api_version: 1 instance_class: B8 basic_scaling: max_instances: 11 idle_timeout: 10m
manual_scaling	省略可。manual_scaling 要素を使用すると、サービスで手動スケーリングが有効になり、サービスのインスタンス数を設定できます。 この要素には次の要素を設定できます。 instances 起動時にサービスに割り当てるインスタンスの数。 例 service: my-service runtime: python27 api_version: 1 instance_class: B8 manual_scaling: instances: 5

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

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

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

注: スクリプト ハンドラは、適切な HTTP ヘッダーをブラウザに返すことで、キャッシュの期間を設定できます。

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