app.yaml 參考資料

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

應用程式中的每個服務都有自己的 app.yaml 檔案,做為該服務的部署作業描述元。您必須先為應用程式中的 default 服務建立 app.yaml 檔案,才能為其他的服務建立並部署 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.

網址和檔案路徑模式會使用 POSIX 擴充規則運算式語法,但不包括對照元素和對照類別。系統支援對分組相符項目 (例如 \1) 的反向參照,也支援下列擴充項目:\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 版本。

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

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

auto_id_policy 選用元素。如果您要自動設定實體 ID,可以透過設定自動 ID 政策來變更所使用的方法。以下是有效的選項:
default
預設值。會使用分散的自動 ID;這些 ID 是分布均勻的大型整數,且整數小到足以由 64 位元浮點數表示。
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 檔案中所定義的任何處理常式。然而,如果您納入會使用 builtinsincludes 的檔案,系統就會依照 includes 階層的順序來新增處理常式。換句話說,系統會先新增「父項」includes 的處理常式,然後才是「子項」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]

builtins 子句在 .yaml 檔案中的位置順序並不會改變這個行為。

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 路徑都會解析為已納入檔案。

如果 include 指令指定了某目錄,App Engine 就會查看該目錄來尋找名為 include.yaml 的檔案如果 include 指令是檔案,系統就會納入這個特定的檔案。使用 includes 只會從目的地檔案中擷取以下類型的指令 (如果有的話):

已納入的 skip_files 模式會新增到所納入 app.yaml 中的模式,或是新增到預設清單中,但前提是 app.yaml 中沒有明確的清單。請注意,skip_files 會比較絕對路徑。

inbound_services

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

下列為可用的內送服務:

mail
可讓應用程式接收郵件
warmup
啟用暖機要求。請參閱設定暖機要求
範例:

inbound_services:
  - mail
  - warmup
instance_class

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

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

自動調整資源配置
F1, F2, F4, F4_1G
預設值:如果您在設定 automatic_scaling 元素時沒有指定執行個體類別,系統就會指派 F1
基本與手動資源調度
B1, B2, B4, B4_1G, B8
預設值:如果您在設定 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.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.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

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

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 設定搭配使用,以便設定在執行由 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 匯入路徑,例如指向 WSGI 應用程式的 package.module.app。使用 Python 模組路徑的 script: 指令的最後一個部分,就是 module: 中某個全域變數的名稱,而該變數必須是 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 類型來提供,除非該類型遭到目錄的 mime_type 設定覆寫。指定目錄中的所有檔案都會上傳成靜態檔案,無法當做指令碼來執行。

這個目錄中的所有檔案,都會隨著應用程式上傳成靜態檔案。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 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_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_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 指定的時間之間,隨時建立執行個體。也就是說,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: 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 標準環境