app.yaml リファレンス

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

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

ディレクトリ構造

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

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

runtime: go
api_version: go1

handlers:
- url: /stylesheets
  static_dir: stylesheets

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

- url: /.*
  script: _go_app

構文

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

YAML 形式ではコメントがサポートされています。シャープ(#)記号で始まる行は無視されます。

# This is a comment.

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

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

要素 説明
application

app.yaml ファイルから application 要素を削除するのがおすすめの方法です。コマンドライン フラグを使用してアプリケーション ID を指定することもできます。

  • goapp deploy コマンドを使用するには、-application フラグを指定します。
    
    goapp deploy -application [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 に再デプロイします。go1 値を指定すると、そのアプリをデプロイするたびに、サポートされている最新のランタイム環境が使用されます(現在は go1.9)。

指定できる Go ランタイム環境のバージョンは、go1go1.9 です。

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

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

例:

runtime: go
api_version: go1

default_expiration: "4d 5h"

handlers:
  # ...

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

env_variables

省略可。アプリで使用できるように、app.yaml ファイルで環境変数を定義できます。

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

例:

env_variables:
  MY_VAR: 'my value'
ここで、MY_VARmy value は定義する環境変数の名前と値です。環境変数の各エントリは、env_variables 要素の下にスペース 2 つ分インデントされています。

これらの値は os.Getenv を使用して取得できます。


import "os"
//...
if v := os.Getenv("MY_VAR"); v != "" {
  //...
}
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

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

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

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

inbound_services:
- warmup
instance_class

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

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

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

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

module

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

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

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


module: service-name

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

runtime

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


runtime: go
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/
version

version ファイルから app.yaml 要素を削除するのがおすすめの方法です。コマンドライン フラグを使用してバージョン ID を指定することもできます。

  • goapp deploy コマンドを使用するには、-version フラグを指定します。
    
    goapp deploy -version [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: _go_app
  login: required

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

- url: /.*
  script: _go_app

ハンドラの構成に auth_fail_action: unauthorized を追加すると、ユーザーがログインしていないときに、保護された URL に対するアクセスを拒否し、ユーザーをログインページにリダイレクトするようにハンドラを構成できます。


handlers:
- url: /secure_api/.*
  script: _go_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 でホストされているアセットにアクセスできます。ただし、mygamemyassets に対して 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 の設定にかかわらずエラー メッセージを表示します。管理者の場合、ハンドラはそのまま処理を続けます。

loginoptional 以外に設定された 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: _go_app
  login: required
  secure: always
  redirect_http_response_code: 301

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

script

省略可。アプリケーションのルート ディレクトリを起点として、このスクリプトへのパスを指定します。

Go アプリの場合、script には常に _go_app の値を含める必要があります。


handlers:

# The root URL (/) is handled by the Go application.
# No other URLs match this pattern.
- url: /
  script: _go_app

# The URL /index.html is also handled by the Go application.
- url: /index\.html
  script: _go_app

# A regular expression indicating that it should be handled
# by the Go application.
- url: /browse/(books|videos|tools)
  script: _go_app

# All other URLs are handled by the Go application.
- url: /.*
  script: _go_app
secure 省略可。スクリプト ハンドラと静的ファイル ハンドラを含むすべての URL ハンドラで、secure の設定を使用できます。secure 要素には次の値を使用できます。
optional
HTTP と HTTPS のどちらのリクエストも URL がハンドラと一致すれば成功し、リダイレクトは行われません。アプリケーションは、リクエストを調べてどちらのプロトコルが使われたか確認し、それに従って適切に応答できます。ハンドラで secure が指定されていない場合、これがデフォルトです。
never
リクエストの URL がこのハンドラと一致し、かつ HTTPS を使用している場合、リクエストを対応する HTTP URL に自動的にリダイレクトします。ユーザーの HTTPS リクエストがリダイレクトされて HTTP リクエストになると、クエリ パラメータはリクエストから削除されます。これにより、ユーザーが誤って、保護された接続用のクエリデータを保護されていない接続で送信することを防ぎます。
always
リクエストの URL がこのハンドラと一致し、かつ HTTPS を使用していない場合、リクエストを同じパスの HTTPS URL に自動的にリダイレクトします。クエリ パラメータはリダイレクトされても維持されます。

handlers:
- url: /youraccount/.*
  script: _go_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% に達すると新しいインスタンスが起動されます。

重要: App Engine SDK for Go から 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 の積に等しい値に達すると、スケジューラは新しいインスタンスを起動します。

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

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

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

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

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

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

重要: App Engine SDK for Go から 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 では、受信リクエストを処理するために最小数のインスタンスが常に実行されています。指定された数のインスタンスについては、リクエストを処理しているかどうかにかかわらず、そのインスタンス数分の料金が請求されます。この機能を適切に機能させるには、ウォームアップ リクエストが有効で、アプリケーションがウォームアップ リクエストを処理していることを確認する必要があります。

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

min_pending_latency

App Engine でリクエストが保留キューで待機する最短時間。この時間が経過すると、リクエストを処理するために新しいインスタンスが起動されます。このしきい値に達すると、それがスケールダウンの信号となり、インスタンス数の減少につながります。デフォルト値は 30ms です。

  • 最小待ち時間を短く設定すると、既存のインスタンスがすべて稼働中のときにリクエストが保留中のキューにとどまる時間が短くなります。パフォーマンスは向上しますが、アプリケーションのランニング コストも高くなります。
  • 最小時間を長く設定すると、既存のインスタンスがすべて稼動中のときにリクエストが保留中のキューにとどまる時間が長くなります。ランニング コストは低くなりますが、ユーザーがリクエストの処理を待つ時間は長くなります。

service: my_service
runtime: go
api_version: go1
instance_class: F2
automatic_scaling:
  min_idle_instances: 5
  max_idle_instances: automatic  # default value
  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: go
api_version: go1
instance_class: B8
basic_scaling:
  max_instances: 11
  idle_timeout: 10m
manual_scaling

省略可。manual_scaling 要素を使用すると、サービスで手動スケーリングを有効にし、サービスのインスタンス数を設定できます。

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

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

service: my_service
runtime: go
api_version: go1
instance_class: B8
manual_scaling:
  instances: 5

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

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

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

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

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

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

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