リージョン ID
REGION_ID
は、アプリの作成時に選択したリージョンに基づいて Google が割り当てる省略形のコードです。一部のリージョン ID は、一般的に使用されている国や州のコードと類似しているように見える場合がありますが、このコードは国または州に対応するものではありません。既存のアプリでは省略可能ですが、まもなく、新しいアプリのすべてにおいて App Engine の URL に REGION_ID .r
を含めることが必須となる予定です。
移行がスムーズに行われるように、リージョン ID を使用するよう App Engine を徐々に更新しています。Google Cloud プロジェクトがまだ更新されていない場合、アプリにリージョン ID が表示されません。ID は既存のアプリでは省略可能なため、リージョン ID が既存のアプリで使用可能になったときに、URL の更新や他の変更を行う必要はありません。
詳しくは、リージョン ID をご覧ください。
OK
App Engine アプリの設定は app.yaml
ファイルで構成します。このファイルでは、URL パスとリクエスト ハンドラや静的ファイルとの対応関係を指定します。app.yaml
ファイルには、ランタイムや最新バージョンの ID など、アプリコードについての情報も記載されています。
アプリ内の各サービス にはそれぞれ独自の app.yaml
ファイルがあり、デプロイ記述子として機能します。アプリ内の追加サービス用に app.yaml
ファイルを作成してデプロイする際は、事前に default
サービス用の 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 を指定することをおすすめします。
これらのコマンドの詳細については、アプリのデプロイ をご覧ください。
アプリケーション ID は、 Google Cloud Console でアプリケーションを作成したときに指定した Cloud Console プロジェクト ID です。
api_version
必須。アプリで使用される特定のランタイム環境における API のバージョンです。
このフィールドは、新しい App Engine ランタイムで非推奨になりました 。
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
に含めることができます。
このフィールドは Python 3 ランタイムで非推奨 になりました。
使用できる組み込みハンドラは次のとおりです。
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
値を指定して、使用するバージョンを指定できます。
このフィールドは Python 3 ランタイムで非推奨 になりました。
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()
によって返されるスレッド ローカルデータが各リクエストの後にクリアされます。
このフィールドは Python 3 ランタイムで非推奨 になりました。
threadsafe: [true | false]
注: Python 2.7 アプリケーションには、threadsafe
ディレクティブが必要です。threadsafe: true
の場合、すべてのスクリプト ハンドラは WSGI でなければなりません。つまり、パッケージ名をドットで区切った Python モジュール のパスを使用して、script:
ディレクティブに各スクリプトを指定する必要があります。Python モジュール のパスを使用した script:
ディレクティブの最後の要素は、service:
のグローバル変数名です。その変数は WSGI アプリとし、通常は慣例に従って app
という名前を付けます。
version
app.yaml
ファイルから 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 に設定すると、ファイルはコードデータとしてもアップロードされ、アプリケーションでも読み取れるようになります。両方のアップロードが、コードデータと静的データのストレージ リソース割り当て として課金されます。このフィールドは、新しい App Engine ランタイムで非推奨になりました 。
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
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
ではなく、ワイルドカード '*'
を使用します。
login
省略可。URL ハンドラがユーザーによるログインを必要とするかどうかを決定します。
このフィールドは新しい App Engine ランタイムでは使用できません 。
この要素には次の 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
という名前のファイルが存在している必要があります。
新しい App Engine ランタイムでは、このフィールドの動作が変更されています 。
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 は、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% に達すると新しいインスタンスが起動されます。
重要: 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 でリクエストが保留キューで待機できる最長時間。この時間を経過すると、リクエストを処理する新しいインスタンスが起動されて保留待ち時間が短くなります。このしきい値に達すると、それがスケールアップの信号となり、インスタンス数の増加につながります。
最長時間を短く設定すると、保留中のリクエストに対処する新しいインスタンスの作成が早くなります。パフォーマンスは向上しますが、ランニング コストも高くなります。
最長時間を長く設定すると、ユーザーがリクエストの処理を待つ時間は長くなる可能性があります(保留中のリクエストがあり、それらに対処するアイドル インスタンスがない場合)が、アプリケーションのランニング コストは低くなります。
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