app.yaml リファレンス

リージョン ID

REGION_ID は、アプリの作成時に選択されたリージョンに基づいて Google が割り当てるコードです。App Engine の URL に REGION_ID.r を含めることは、既存のアプリでは任意でしたが新しいアプリでは必須となります。

リージョン ID について理解する。

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

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 Console でアプリケーションを作成したときに指定した Cloud 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 を使用すると、次の種類のディレクティブだけが宛先ファイルから取得されます（存在する場合）。

インクルードされた 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
デフォルト: F1

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

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

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

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

サービスを作成する場合には必須です。 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]

これらのコマンドの詳細については、アプリのデプロイをご覧ください。

App Engine にデプロイするアプリケーション コードのバージョン ID。

バージョン ID には、小文字、数字、ハイフンを使用できます。接頭辞 ah- で始めることはできず、名前 default と latest は予約されているので使用できません。

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

アプリケーションの各バージョンには app.yaml の独自のコピーが維持されます。アプリケーションをアップロードすると、アップロードされる app.yaml ファイルのバージョンは、アップロードで作成または置換されるバージョンになります。管理者は、Google Cloud 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.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 ではなく、ワイルドカード '*' を使用します。

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 用のパスをテストできます。

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 タイプを使用して処理されます。指定したディレクトリ内のすべてのファイルは静的ファイルとしてアップロードされ、これらのファイルはいずれもスクリプトとしては実行できません。

このディレクトリ内のすべてのファイルは、静的ファイルとしてアプリと一緒にアップロードされます。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 以上のインスタンス クラスを使用するアプリケーションにのみ適用されます。

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

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

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_idle_instances

省略可。App Engine がこのバージョンに保持できるアイドル状態のインスタンスの最大数。1～1000 の値、または automatic を指定します。デフォルト値は automatic です。以下のことに注意してください。

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

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

min_idle_instances

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

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

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

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

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_concurrent_requests

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

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

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

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

max_pending_latency

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

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

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

この要素によって、min_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 は新しいインスタンスを作成します。
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

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

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

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

service: my-service
runtime: python27
api_version: 1
instance_class: B8
basic_scaling:
  max_instances: 11
  idle_timeout: 10m
manual_scaling

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

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

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

service: my-service
runtime: python27
api_version: 1
instance_class: B8
manual_scaling:
  instances: 5

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

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

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

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