app.yaml リファレンス

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

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

ディレクトリ構造

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

Python アプリケーションの 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 Platform Console でアプリケーションを作成したときに指定した GCP Console プロジェクト ID です。

api_version

必須。 このアプリで使用する、特定のランタイム環境における API のバージョンです。

Google がランタイム環境の API の新バージョンのサポートを発表しても、デプロイされたアプリはその作成時に使用された API を引き続き使用します。アプリを新バージョンの API にアップグレードするには、この値を変更して、アプリを App Angine に再デプロイします。1 値を指定すると、そのアプリをデプロイするたびに、サポートされている最新のランタイム環境が使用されます(現在は )。

現在、App Engine の python27 ランタイム環境のバージョンは 1 です。

auto_id_policy 省略可。エンティティ ID を自動的に設定している場合、自動 ID ポリシーを設定すると、使用するメソッドを変更できます。有効なオプションは次のとおりです。
default
デフォルト。64 ビット浮動小数点として表現可能で、適度に分散された ID を自動的に割り当てます。
legacy
レガシー オプションは今後のリリースで非推奨となり、最終的に削除する予定です。詳細については、この変更を発表したブログ記事をご覧ください。
builtins

省略可。 Python SDK には、一般的なアプリケーション機能向けの複数の組み込みハンドラが含まれています。builtins ディレクティブを使用すると、特定のハンドラを app.yaml に含めることができます。

使用できる組み込みハンドラは次のとおりです。

appstats
/_ah/stats//_ah/stats/ を有効にします。これにより、アプリケーションのパフォーマンスを計測できます。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 は、以下のいずれかになります。
over_quota
アプリがリソース割り当ての上限を超えていることを表します。
dos_api_denial
リクエストがアプリの DoS 保護構成でブロックされたことを示します。
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 など、コードと一緒にアップロードされた静的ファイルを提供します。

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

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 アプリケーション用にサービスを有効にするには、inbound_services セクションを app.yaml ファイルに含めます。

使用できる受信サービスは次のとおりです。

mail
アプリケーションにメールの受信を許可します。
warmup
ウォームアップ リクエストを有効にします。ウォームアップ リクエストの設定をご覧ください。
例:

inbound_services:
  - mail
  - warmup
instance_class

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

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

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

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

libraries

省略可。 Python 2.7 ランタイムには、一部のサードパティ ライブラリが含まれています。これらの一部はデフォルトで使用できますが、それ以外は使用前に設定が必要です。使用するバージョンを指定するには、name 値と version 値を指定します。


libraries:
- name: PIL
  version: "1.1.7"
- name: webob
  version: "latest"
        

latest を指定すると、SDK はデプロイ時点での最新のライブラリ バージョンを特定します。デプロイ後、ライブラリ バージョンは変更されません。ライブラリの異なるバージョンを取得するには、デプロイをやり直す必要があります。

開発中のアプリケーションにユーザーが存在しない場合には、新しいバージョンを追跡する必要はありません。ただし、アプリケーションを実際に使用している場合、下位互換性のない新しいライブラリ バージョンがアプリケーションで使用される可能性があります。

使用可能なサードパーティ ライブラリの一覧については、サードパーティ ライブラリをご覧ください。ローカル ディレクトリにインストールすることで、追加のピュア Python サードパーティ ライブラリを使用できます。

フレキシブル環境を使用している場合には、フレキシブル環境での Python ライブラリの使用をご覧ください。

module

注: モジュールは名称がサービスに変わりました。

gcloud ツールでアプリを管理するには、service 要素を使用します。

appcfg ツールを使用するには、app.yaml ファイルでモジュールとしてサービスを宣言する必要があります。


module: service-name

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

runtime

必須。アプリで使用されるランタイム環境の名前です。Python を指定する場合には、python27 を使用します。


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

version ファイルから app.yaml 要素を削除するのがおすすめの方法です。コマンドライン フラグを使用してバージョン 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- で始めることはできず、名前 defaultlatest は予約されているので使用できません。

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

アプリケーションの各バージョンに app.yaml の独自のコピーが維持されます。アプリケーションをアップロードすると、アップロードされる app.yaml ファイルのバージョンは、アップロードで作成または置換されるバージョンになります。管理者は、Google Cloud Platform Console を使用して、トラフィックを処理するアプリケーションのバージョンを変更できます。また、トラフィックの受信を構成する前に他のバージョンをテストすることもできます。

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 つは、クロスオリジン リソース シェアリング(CORS)のサポートです。この機能により、別の App Engine アプリでホストされているファイルにアクセスできます。

たとえば、ゲームアプリ 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 ではなく、ワイルドカード '*' を使用します。 .

login

省略可。URL ハンドラがユーザーのログインが必要かどうかを決定します。この要素には次の 3 つの値を使用できます。

optional
デフォルト。ユーザーによるログインを必須としません。
required
ログインしているユーザーに対して、ハンドラは通常どおり処理を進めます。ログインしていないユーザーに対しては、auth_fail_action のアクションを実行します。
admin
required と同様、ユーザーがログインしていない場合に auth_fail_action を実行します。また、ユーザーがアプリケーションの管理者でなければ、auth_fail_action の設定に関係なくエラー メッセージを返します。管理者の場合、ハンドラはそのまま処理を続けます。

optional 以外の login を設定した 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

省略可。secure の設定でリダイレクトが実行されると、redirect_http_response_codesecure 設定を使用して 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 アプリである必要があり、その変数は WSGI アプリである必要があり、慣例により app という名前を付けます。

注: Python import のステートメントと同様に、パッケージのサブディレクトには __init__.py という名前のファイルが存在している必要があります。

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

省略可。このハンドラによって参照されるすべてのファイルのファイルパスと一致する正規表現。ハンドラでは、アプリケーション ディレクトリ内のどのファイルが、指定した 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% に達すると新しいインスタンスが起動されます。

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

重要: Python 用 App Engine SDK から appcfg を使用してデプロイする場合、app.yaml でこのパラメータを使用することはできません。代わりに、API Explorer での自動スケーリング パラメータの設定の手順に従うか、または App Engine Admin API を使用して、パラメータを設定します。

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

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

重要: Python 用 App Engine SDK から appcfg を使用してデプロイする場合、app.yaml でこのパラメータを使用することはできません。代わりに、API Explorer での自動スケーリング パラメータの設定の手順に従うか、または App Engine Admin API を使用して、パラメータを設定します。

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

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

重要: Python 用 App Engine SDK から appcfg を使用してデプロイする場合、app.yaml でこのパラメータを使用することはできません。代わりに、API Explorer での自動スケーリング パラメータの設定の手順に従うか、または App Engine Admin API を使用して、パラメータを設定します。

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: 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 要素を追加します。特定の静的ファイル ハンドラにキャッシュ期間を設定することもできます。

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

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

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

Python の App Engine スタンダード環境