app.yaml 參考資料

您可以在 app.yaml 檔案中設定 App Engine 應用程式。這個檔案是用來指定網址路徑與要求處理常式和靜態檔案的對應方式。app.yaml 檔案還包含應用程式程式碼的相關資訊,例如執行階段和最新版本 ID。

應用程式中的每項服務都有專屬的 app.yaml 檔案,用來做為其部署的描述元。您必須先為 default 服務建立 app.yaml 檔案,才能為應用程式中的其他服務建立及部署 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.

網址和檔案路徑模式使用 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 主控台中建立應用程式時指定的 GCP 主控台專案 ID。

api_version

必要元素。應用程式使用的指定執行階段環境中的 API 版本。

應用程式是針對特定執行階段環境 API 版本所編寫的,即使 Google 宣佈支援新版,已部署的應用程式也會繼續使用原來的版本。如要將應用程式升級至新版 API,請變更這個值,然後將應用程式重新部署至 App Engine。如果您指定的值為 1,每當您部署該應用程式時,系統就會使用支援的最新執行階段環境 (目前為 )。

目前 App Engine 有一個版本的 python27 執行階段環境:1

auto_id_policy 選用元素,若要自動設定實體 ID,您可以透過設定自動 ID 政策來變更所使用的方法。以下是有效的選項:
default
預設值。使用分散的自動 ID,這些 ID 是分佈均勻的大型整數,大小足以由 64 位元浮點數表示。
legacy
日後推出的版本將會淘汰舊版選項,而且最終會將其移除。詳情請參閱宣佈這類變更的網誌文章
builtins

選用元素。Python 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 檔案中定義的任何處理常式。不過,如果您包含使用 builtinsincludes 的檔案,處理常式會依照 include 階層的順序新增。換句話說,「父項」includes 的處理常式會先加入,然後才是「子項」includes 的內建項目,以此類推。

舉例來說,請思考以下使用內建 appstats 處理常式的 app.yaml


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
如果應用程式未在期限前回應,則提供這個錯誤代碼。

error_code 為選用元素;如未指定,則指派的檔案就是應用程式的預設錯誤回應。

file
每個檔案項目代表要替換一般錯誤回應的靜態檔案。如果您指定的 file 元素沒有對應的 error_code 元素,則靜態檔案將是應用程式的預設錯誤頁面。 自訂的錯誤資料必須小於 10 KB。
範例

error_handlers:
  - file: default_error.html

  - error_code: over_quota
    file: over_quota.html
handlers

必要元素。列出網址模式和這些模式的處理方式說明。App Engine 處理網址的方式有兩種,一種是執行應用程式的程式碼,另一種是提供透過程式碼上傳的靜態檔案,例如圖片、CSS 或 JavaScript。

請參閱處理常式和子元素語法的說明

includes

選用元素。includes 指令可讓您在整個應用程式中加入任何程式庫或服務的設定檔。例如,您可以加入使用者管理程式庫,如下所示:


includes:
- lib/user_admin.yaml

App Engine 會以下列順序解析加入的路徑:

  • 工作目錄的絕對或相對路徑。指定路徑會解析為檔案。
  • 與應用程式的目錄相對的路徑,也稱為「basepath」。basepath 和路徑都會解析為檔案。
  • 與含有目前檔案的檔案相對的路徑。參照檔案的位置和包含路徑都會解析為內含檔案。

如果 include 指令指定了目錄,則 App Engine 會在這個目錄中尋找名為 include.yaml 的檔案。如果 include 指令是一個檔案,則會包含這個特定檔案。使用 includes 只會從目的地檔案擷取以下類型的指令 (如有的話):

含有的 skip_files 模式會加入所含 app.yaml 中的模式,或如果 app.yaml 中沒有明確的清單則加入預設的清單中。請注意,skip_files 會比較絕對路徑。

inbound_services

選用元素。應用程式必須先啟用這些服務,才能接收內送要求。您可以在 app.yaml 檔案中加入 inbound_services 區段,為 Python 應用程式啟用服務。

可用的內送服務如下:

mail
讓您的應用程式能夠接收郵件
warmup
啟用暖機要求。請參閱設定暖機要求的說明。
範例:

inbound_services:
  - mail
  - warmup
instance_class

選用元素。這項服務的執行個體類別

視您服務的資源調度方式而定,可用的值如下:

自動調整資源配置
F1F2F4F4_1G
預設值:如果您沒有搭配 automatic_scaling 元素來指定執行個體類別,系統會指派 F1
基本與手動調整資源調度
B1B2B4B4_1GB8
預設值:如果您沒有搭配 basic_scaling 元素或 manual_scaling 元素來指定執行個體類別,系統會指派 B2

附註:如果 instance_class 已設為 F2 以上的值,您可以將 max_concurrent_requests 設為大於預設值 10 的值,藉此將執行個體最佳化。如要找出最佳值,請逐步提高數值並監控應用程式的效能。

libraries

選用元素。Python 2.7 執行階段包含某些第三方程式庫。在這些程式庫中,有些是預設可使用,有些則需要經過設定才可使用。您可以指定 nameversion 的值,藉此指定要使用的版本。


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 2.7,請使用:


runtime: python27
service

「服務」先前稱為「模組」。

僅限 gcloud 工具或 Cloud SDK 外掛程式提供支援,例如:gcloud app deploy

如要使用 appcfg 工具,請參閱 module 的說明。

如要建立服務,則為必要元素。如為 default 服務,則為選用元素。每項服務和每個版本都必須具有名稱。名稱可包含數字、字母和連字號,服務與版本的合併長度上限為 63 個字元,且開頭或結尾不得使用連字號。請為各項服務和每個版本皆選擇不重複名稱,不要以相同名稱為服務和版本命名。

範例:

service: service-name

附註:gcloud app deploy 指令具有回溯相容性,並可支援內含服務 (已宣告為模組) 的現有 app.yaml 檔案,例如:


module: service-name
skip_files

選用元素。skip_files 元素是用來指定不要將應用程式目錄中的哪些檔案上傳到 App Engine。這個元素的值可以是規則運算式或規則運算式清單。上傳應用程式時,所有與任一規則運算式相符的檔案名稱會從檔案清單中省略。檔案名稱與專案目錄具有相對關係。

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 程式庫,每次要求後即會清除 threading.local() 傳回的執行緒本機資料。


threadsafe: [true | false]

注意:Python 2.7 應用程式必須要有 threadsafe 指令。 threadsafe: true 要求所有指令碼處理常式必須為 WSGI 處理常式。也就是說,每個指令碼都必須在 script: 指令中指定,且使用以英文句點分隔套件名稱的 Python 模組路徑。使用 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- 開頭,且 defaultlatest 為不可使用的保留名稱。

注意:數字執行個體一律是以數字指定,為了有所區別,版本名稱的開頭應為字母。如此可避免網址出現模稜兩可的情況,例如 123.my-service.appspot.com 有兩種解讀方式:如果「123」版本存在,目標會是指定服務的「123」版本;如果這個版本不存在,目標會是服務預設版本的執行個體數 123。

應用程式的每個版本都會保留自己的 app.yaml 複本。上傳應用程式時,在上傳的 app.yaml 檔案中提及的版本,即為由上傳內容建立或取代的版本。系統管理員可使用 Google Cloud Platform 主控台變更提供流量的應用程式版本,也可以測試其他版本後再將這些版本設為接收流量

vpc_access_connector

選用元素。將您的應用程式設定為使用無伺服器虛擬私人雲端存取連接器,以傳送要求至虛擬私人雲端網路中的內部資源。在 name 欄位中指定完整連接器路徑:


vpc_access_connector:
  name: "projects/[PROJECT_ID]/locations/[REGION]/connectors/[CONNECTOR_NAME]"

詳情請參閱連線至虛擬私人雲端網路中的內部資源

處理常式元素

handlers 元素是 app.yaml 設定檔中的必要元素,這個元素提供網址模式清單,以及這些模式的處理方式說明。App Engine 處理網址的方式有兩種,一種是執行應用程式程式碼,另一種是提供透過程式碼上傳的靜態檔案 (例如圖片、CSS 或 JavaScript)。

系統會依照模式在 app.yaml 檔案中出現的順序,由上到下進行評估,並以第一個符合網址的對應模式來處理要求。

下表列出 handlers 元素的子元素,這些子元素可控制指令碼、靜態檔案、靜態目錄和其他設定的行為。

元素 說明
application_readable 選用元素,布林值。根據預設,靜態檔案處理常式中宣告的檔案會以靜態資料的形式上傳,且只會提供給使用者,應用程式無法讀取。如果將這個欄位設為 true,檔案也會以程式碼資料的形式上傳,讓應用程式能夠讀取。這兩種上傳方式都會計入您的程式碼和靜態資料的儲存空間資源配額
auth_fail_action

選用元素。說明處理常式已指定 login 元素且使用者未登入時要採取的行動。可用的值有兩種:

redirect
預設值。系統會將使用者重新導向至 Google 登入頁面;如果有使用 OpenID 驗證,則會重新導向至 /_ah/login_required。使用者登入或建立帳戶後,系統會將其重新導回應用程式網址。
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 來設定處理常式,讓未登入的使用者無法存取受保護的網址,而不是將使用者重新導向至登入頁面:


handlers:
- url: /secure_api/.*
  script: api_handler.app
  login: required
  auth_fail_action: unauthorized
expiration 選用元素。針對這個處理常式提供的靜態檔案,指定網路 Proxy 和瀏覽器應快取的時間長度。這個值是字串,由以空格分隔的數字和單位組成,其中單位可為 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 支援

這項功能的一大用途,就是支援跨源資源共享 (CORS),例如存取託管給其他 App Engine 應用程式的檔案。

舉例來說,您的遊戲應用程式 mygame.appspot.com 可能會存取託管給 myassets.appspot.com 的資產。不過,如果 mygame 嘗試向 myassets 發出 JavaScript XMLHttpRequest,則除非 myassets 的處理常式傳回包含值為 http://mygame.appspot.comAccess-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

選用元素。決定網址處理常式是否要求使用者登入。這個元素有三個可用的值:

optional
預設值,不要求使用者登入。
required
如果使用者已登入,處理常式會照常執行。如果使用者未登入,則會採取 auth_fail_action 中指定的動作。
admin
如同 required,假如使用者未登入,則執行 auth_fail_action。此外,如果使用者不是應用程式的管理員,則無論 auth_fail_action 設定為何,他們都會收到錯誤訊息。如果使用者是管理員,處理常式將繼續進行。

login 設定不是 optional 的網址處理常式比對網址時,處理常式會先檢查使用者是否使用應用程式的驗證選項登入應用程式。若非如此,則預設會將使用者重新導向至登入頁面。您也可以使用 auth_fail_action 來設定應用程式,直接拒絕未經適當驗證的使用者發出的處理常式要求,而不是將使用者重新導向至登入頁面。

注意:App Engine 會為內部要求設定適當的 X-Appengine 特殊標頭,因此內部要求也會滿足 admin 登入限制。舉例來說,由於 App Engine 會在各個要求設定 HTTP 標頭 X-AppEngine-Cron: true,因此以 cron 排定的工作會滿足 admin 限制,不過,要求不會滿足 required 登入限制,因為以 cron 排定的工作不是以使用者的身分執行。

mime_type

選用元素。如有指定,這個處理常式將使用指定的 MIME 類型提供所有的檔案。如未指定,則檔案的 MIME 類型將衍生自檔案名稱的副檔名。如果上傳的同一個檔案有多個副檔名,則產生的副檔名可能會取決於上傳的順序。

如要進一步瞭解可用的 MIME 媒體類型,請造訪 IANA MIME 媒體類型網站

redirect_http_response_code

選用元素。redirect_http_response_code 需與 secure 設定搭配使用,設定執行必要的重新導向動作時傳回的 HTTP 回應碼 (必要的重新導向動作視 secure 的設定方式而定)。 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 匯入路徑,例如指向 WSGI 應用程式的 package.module.app。使用 Python 模組路徑的 script: 指令的最後一個元件是模組中的全域變數名稱,這個變數必須為 WSGI 應用程式,且依照慣例通常稱為 app

附註:就跟 Python import 陳述式的情況一樣,如果子目錄是套件,就必須包含名為 __init__.py 的檔案。

secure 選用元素,任何網址處理常式都可使用 secure 設定,包括指令碼處理常式和靜態檔案處理常式。secure 元素的可用值如下:
optional
如果要求的網址符合處理常式,不論是 HTTP 或 HTTPS 要求,都能順利進行而無須重新導向。應用程式可檢查要求來決定要使用哪個通訊協定,並依此做出回應。如未針對處理常式提供 secure,則這為預設值。
never
如果要求的網址符合這個處理常式,且要求使用 HTTPS,則會自動重新導向至 HTTP 對應網址。當使用者的 HTTPS 要求重新導向為 HTTP 要求時,查詢參數會從要求中移除,避免使用者不小心透過不安全的連線提交應透過安全連線傳送的查詢資料。
always
如果要求的網址符合這個處理常式,且要求未使用 HTTPS,則會自動重新導向至相同路徑的 HTTPS 網址。系統將保留查詢參數以用於重新導向。
範例

handlers:
- url: /youraccount/.*
  script: accounts.app
  login: required
  secure: always

開發網路伺服器不支援 HTTPS 連線。這類伺服器會忽略 secure 參數,因此可使用開發網路伺服器的一般 HTTP 連線來測試要搭配 HTTPS 使用的路徑。

如要使用 appspot.com 網域指定特定應用程式版本,請將通常用於分隔網址子網域部分的句點改成「-dot-」字串,例如:


https://[VERSION_ID]-dot-[YOUR_PROJECT_ID].appspot.com

如要搭配 HTTPS 使用自訂網域,必須先啟用及設定這個網域的安全資料傳輸層 (SSL) 憑證

Google 帳戶的登入和登出作業一律使用安全連線執行,與應用程式的網址設定方式並無關聯。

static_dir

選用元素。從應用程式根目錄到靜態檔案所屬目錄的路徑。相符 url 模式結尾後的所有內容都會附加到 static_dir,以構成所要求檔案的完整路徑。

除非遭到目錄的 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

選用元素。靜態檔案模式處理常式會將網址模式與隨應用程式一併上傳的靜態檔案路徑建立關聯。網址模式規則運算式可定義規則運算式的分組,以用來建構檔案路徑。您可以使用這個元素取代 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 底下的必要元素。形式為規則運算式的網址模式。運算式可包含分組,且這些分組可透過規則運算式反向參照的方式,在指令碼檔案路徑中參照。舉例來說,/profile/(.*)/(.*) 會比對 /profile/edit/manager 網址,並使用 editmanager 來做為第一和第二個分組。

當與下列元素搭配使用時,網址模式的行為會稍有不同:

static_dir
使用網址前置字串。當與 static_dir 元素搭配使用時,規則運算式模式不應包含分組。這個處理常式會處理所有開頭為這個前置字串的網址,使用前置字串後的網址部分做為檔案路徑的一部分。
static_files
靜態檔案模式處理常式會將網址模式與隨應用程式一併上傳的靜態檔案路徑建立關聯。網址模式規則運算式可定義規則運算式的分組,以用來建構檔案路徑。您可以使用這個元素取代 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_requests 乘以 target_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_requests 乘以 target_throughput_utilization,排程器就會啟動新的執行個體。

如果這項設定的值過高,API 延遲時間可能會增加。請注意,排程器可能會在達到實際的要求數量上限前,就產生新的執行個體。

附註:如果 instance_class 已設為 F2 以上的值,您可以將 max_concurrent_requests 設為大於預設值 10 的值,藉此將執行個體最佳化。如要找出最佳值,請逐步提高數值並監控應用程式的效能。

max_idle_instances

選用元素,App Engine 應為這個版本維持的閒置執行個體數量上限。請指定 1 到 1000 之間的值,或 automatic。預設值為 automatic。請注意以下幾點:

  • 如果上限較高,則當尖峰結束且負載回到正常程度時,閒置執行個體數量的減少速率會較慢。這可協助應用程式在要求負載變動時維持穩定效能,但同時會在負載較重的時期提高閒置執行個體的數量 (進而提高執行成本)。
  • 如果上限較低,則可降低執行成本,但當負載程度不穩定時,效能可能會降低。

注意:在負載尖峰結束並回到正常程度時,閒置執行個體的數量可能會暫時超出您指定的上限。不過,系統不會針對超出您指定數量上限的執行個體收費。

max_pending_latency

指定 App Engine 在啟動其他執行個體來處理要求以降低等待延遲時間前,最多應讓要求在待處理佇列中等候多久的時間。如果達到這個門檻,系統就知道要擴充資源,進而提高執行個體的數量。預設值為 30ms

App Engine 可在 min_pending_latencymax_pending_latency 的指定時間之間隨時建立執行個體。也就是說,在達到 min_pending_latency 的指定時間之前,App Engine 不會建立執行個體來解決待處理的要求,但會在達到 max_pending_latency 後建立執行個體。

  • 如果上限較低,表示 App Engine 會較早啟動新的執行個體來解決待處理的要求;這可改善效能,但是執行成本也會隨之提高。
  • 如果上限較高,表示系統可能需要較久的時間才會處理使用者的要求 (如果有待處理的要求且沒有閒置的執行個體可處理要求時),但應用程式的執行成本較低。
min_idle_instances

保持運作且可提供流量的執行個體數量。請注意,系統是依指定的執行個體數量收費,與執行個體是否收到流量無關。這項設定僅適用於接收大部分流量的版本。請注意以下幾點:

  • 如果下限較低,則可降低閒置期間的執行成本,但這也表示可立即回應突發負載尖峰的執行個體會較少。
  • 如果上限較高,應用程式就能夠應付要求負載遽增的情況。App Engine 會保持運作下限數量的執行個體以處理傳入的要求。系統是依指定的執行個體數量收費,與執行個體是否在處理要求無關。如要讓這項功能順利運作,您必須確認暖機要求已啟用,且應用程式可處理暖機要求。

    如果您設定閒置執行個體的數量下限,則等待延遲時間對應用程式效能造成的影響會比較小。由於 App Engine 會保留閒置執行個體,因此除了負載尖峰極高的情況以外,要求不太可能會進入待處理佇列。您必須測試應用程式和預期流量,才能判斷理想的保留執行個體數量為何。

min_pending_latency

指定 App Engine 在啟動新的執行個體來處理要求前,最少應讓要求在待處理佇列中等候多久的時間。如果達到這個門檻,系統就知道要縮減資源,進而減少執行個體的數量。預設值為 30ms

  • 如果下限較低,表示當所有的現有執行個體皆處於運作狀態時,要求在待處理佇列中必須等候的時間會較短。這可改善效能,但應用程式的執行成本也會隨之提高。
  • 如果下限較高,表示當所有的現有執行個體皆處於運作狀態時,要求等候的時間會較長。這樣可降低執行成本,但使用者等候要求完成的時間會增加。
範例

service: my-service
runtime: python27
api_version: 1
instance_class: F2
automatic_scaling:
  target_cpu_utilization: 0.65
  min_instances: 5
  max_instances: 100
  min_pending_latency: 30ms  # default value
  max_pending_latency: automatic
  max_concurrent_requests: 50
basic_scaling

選用元素。basic_scaling 元素可設定服務的執行個體數量。

這個元素可包含下列元素:

idle_timeout
選用元素。指定執行個體收到上次要求後經過多久時間會關閉。預設值為 5 分鐘 (5m)。
max_instances
必要元素。指定 App Engine 為這個服務版本建立的執行個體數量上限,適合用來限制服務的成本。
範例

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

選用元素。manual_scaling 元素可讓您手動調度服務的資源,並設定服務的執行個體數量。

這個元素可包含下列元素:

instances
一開始指派給服務的執行個體數量。
範例

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

靜態快取效期

除非另有指示,否則網路 Proxy 和瀏覽器會將從網站載入的檔案保留一定的時間。

您可以透過加入頂層的 default_expiration 元素,針對應用程式的所有靜態檔案處理常式來定義全域的預設快取效期,也可以設定特定靜態檔案處理常式的快取效期

效期會透過 Cache-ControlExpires HTTP 回應標頭傳送,因此使用者的瀏覽器和中繼快取 Proxy 伺服器 (例如網際網路服務供應商) 可能會快取檔案。具有指定效期的檔案經傳輸後,通常就無法從中繼快取中清除,即使使用者清除自己的瀏覽器快取也無法執行此操作。重新部署新版應用程式不會重設任何快取。因此,如果您打算修改靜態檔案,請為其設定較短的效期 (不超過一小時)。在大多數情況下,預設的 10 分鐘效期即為適當的設定。

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Python 2 適用的 App Engine 標準環境