App Engine app.yaml 參考資料

區域 ID

REGION_ID 是 Google 根據您在建立應用程式時選取的地區所指派的縮寫代碼。此代碼不對應至國家/地區或省份，即使部分區域 ID 可能與常用的國家/地區和省份代碼相似。如果是 2020 年 2 月後建立的應用程式，App Engine 網址會包含 REGION_ID.r。如果是這段時間前建立的現有應用程式，網址可選擇是否包含地區 ID。

進一步瞭解區域 ID。

您可以在 app.yaml 設定檔中設定 App Engine 應用程式的設定。設定檔至少須指定 runtime 項目。

應用程式中的每個服務都有自己的 app.yaml 檔案，做為該服務的部署作業描述元。您必須先為 default 服務建立 app.yaml 檔案，才能為應用程式中的其他服務建立及部署 app.yaml 檔案。如要進一步瞭解如何在應用程式中建構多項服務，請參閱在 App Engine 中建構網路服務。

語法

app.yaml 的語法採用 YAML 格式。

YAML 格式支援註解功能，因此系統會忽略以井字 (#) 字元開頭的行：

# This is a comment.

網址和檔案路徑模式會使用 POSIX 擴充規則運算式語法，但不包括對照元素和對照類別。系統支援對分組相符項目 (例如 \1) 的反向參照，也支援下列擴充項目：\w \W \s \S \d \D。

範例

app.yaml 檔案的範例如下：

runtime: php85

handlers:
# Serve a directory as a static resource.
- url: /stylesheets
  static_dir: stylesheets


# Serve images as static resources.
- url: /(.+\.(gif|png|jpg))$
  static_files: \1
  upload: .+\.(gif|png|jpg)$

# Serve your app through a front controller at index.php or public/index.php.
- url: .*
  script: auto

在這個範例中，App Engine 會提供副檔名為 gif、png 或 jpg 的檔案做為靜態資源。應用程式碼會在執行階段讀取設定檔。

下表提供 app.yaml 檔案中可用欄位的 YAML 範例：

執行階段和應用程式元素

元素 說明
app_engine_apis

選用。如要使用第二代執行階段的 App Engine 舊版套裝組合服務，請將這個欄位設為 true。

build_env_variables

選用。如果使用的執行階段支援 buildpack，您可以在 app.yaml 檔案中定義建構環境變數。

詳情請參閱「 使用建構環境變數」。
default_expiration

選用。會針對應用程式的所有靜態檔案處理常式，設定全域的預設快取有效期限。您也可以設定特定靜態檔案處理常式的快取效期。這個值是由數字和單位 (以空格分隔) 組成的字串，其中單位可為 d (天數)、h (小時數)、m (分鐘數) 和 s (秒數)。舉例來說，"4d 5h" 會將快取有效期限設定為檔案首次收到要求後的 4 天又 5 小時。如果您省略這個值，實際工作環境伺服器會把有效期限設定為 10 分鐘。

PHP 範例： 
runtime: php85

default_expiration: "4d 5h"

handlers:
# ...

詳情請參閱「快取效期」。
entrypoint

選用。應用程式啟動時，執行 entrypoint 指令，覆寫預設啟動行為。為了讓應用程式接收 HTTP 要求，entrypoint 元素應包含啟動網路伺服器的指令，該伺服器會監聽通訊埠 8080。

如果您未指定 PHP 執行階段的 entrypoint，App Engine 會透過 public/index.php 或 index.php 檔案中的前端控制器， 提供應用程式服務。

詳情請參閱「 啟動應用程式」。
env_variables

選用元素。您可以在 app.yaml 檔案中定義環境變數，以供應用程式使用。請確保「環境變數」中的鍵符合運算式「[a-zA-Z_][a-zA-Z0-9_]*」(開頭為字母或「_」，後接任何英數字元或「_」)。

開頭為 GAE 的環境變數已保留給系統使用，無法用於 app.yaml 檔案中。

範例：

env_variables:
  MY_VAR: "my value"
 其中 MY_VAR 和 my value 是您要定義的環境變數名稱和值，且各個環境變數項目位在 env_variables 元素下方並縮排兩個空格。未獲派值的環境變數預設為 "None"。

如果是 PHP，您可以使用 getenv() 或 $_SERVER 擷取這些變數的值，但不得使用 $_ENV。下列指令可輸出環境變數 MY_VAR 的值：

echo getenv('MY_VAR');
 或 
echo $_SERVER['MY_VAR'];

另請參閱無法覆寫的 執行階段環境變數清單。
error_handlers

選用元素。用來設定自訂的錯誤頁面，讓系統能針對不同的錯誤類型傳回。

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

error_code
選用元素。error_code 可以是下列其中一個：
over_quota
代表應用程式已 超出資源配額上限。
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。

請參閱處理常式和子元素語法。

如果是 PHP，您也必須定義處理常式，才能將其他所有應用程式流量轉送至 entrypoint。如要轉送至 entrypoint，請使用 entrypoint 元素指定前端控制器的路徑，或者在應用程式包含 public/index.php 或 index.php 檔案的情況下使用 script 元素。

例如：

url: .*
script: auto
inbound_services

選用元素。應用程式必須先啟用這些服務，才能讓這些服務接收內送要求。如要啟用應用程式的服務，請在 app.yaml 檔案中加入 inbound_services 區段。

warmup
啟用暖機要求。請參閱 設定暖機要求。
範例： 
inbound_services:
- 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 元素。

runtime

這是必要旗標，應用程式使用的執行階段環境名稱。舉例來說，如要指定執行階段環境，請使用：

runtime: php85
service

如要建立服務，這就是必要元素。如要使用 default 服務，這就是選用元素。每個服務和每個版本都必須要有名稱。名稱可包含數字、字母和連字號，VERSION-dot-SERVICE-dot-PROJECT_ID 的總長度不得超過 63 個字元，且開頭或結尾不得使用連字號。其中 VERSION 是版本名稱、SERVICE 是服務名稱，而 PROJECT_ID 則是專案 ID。請為各項服務和每個版本選擇不重複的名稱，不要以相同名稱為服務和版本命名。

範例：
service: service-name
service_account

選用。service_account 元素可讓您指定版本專屬服務帳戶做為版本的身分。存取其他 Google Cloud 服務及執行工作時，系統會使用指定的服務帳戶。

範例：
service_account: [SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com
vpc_access_connector

選用。將您的應用程式設定為使用無伺服器的虛擬私有雲存取連接器，讓該應用程式能夠將要求傳送至虛擬私有雲網路中的內部資源。詳情請參閱「連線至虛擬私有雲網路」。

name
字串常值。以半形引號指定無伺服器 VPC 存取連接器的完整名稱：
"projects/PROJECT_ID/locations/REGION/connectors/CONNECTOR_NAME"
egress_setting
選用。預設值為 private-ranges-only。egress_setting 可以是下列其中一個：
private-ranges-only
預設值。傳送至內部 IP 位址的要求會透過無伺服器虛擬私有雲存取連接器，傳送至已連線的虛擬私有雲網路。傳送至外部 IP 位址的要求會傳送至公開網際網路。
all-traffic
所有要求都會透過無伺服器虛擬私有雲存取連接器，傳送至已連線的虛擬私有雲網路。
範例 
vpc_access_connector:
  name: "projects/PROJECT_ID/locations/REGION/connectors/CONNECTOR_NAME"
  egress_setting: all-traffic

處理常式元素

handlers 元素提供網址模式清單，以及這些網址模式的處理方式說明。App Engine 處理網址的方式有兩種，一種是執行應用程式碼，另一種是提供隨程式碼一併上傳的靜態檔案 (例如圖片、CSS 或 JavaScript)。

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

下表列出 handlers 元素的子元素，這些子元素可控制靜態檔案、靜態目錄、Node.js 以外執行階段的指令碼和其他設定的行為。

元素 說明
expiration 選用。應該要讓該處理常式所提供的靜態檔案保留在網路 Proxy 和瀏覽器快取中的時間長度。這個值是由數字和單位 (以空格分隔) 組成的字串，其中單位可為 d (天數)、h (小時數)、m (分鐘數) 和 s (秒數)。舉例來說，"4d 5h" 會將快取到期時間設定為檔案首次收到要求後的 4 天又 5 小時。如果您省略這個值，系統會使用應用程序的 default_expiration。詳情請參閱「快取有效期限」。
http_headers

選用。您可以針對靜態檔案或目錄處理常式的回應，設定 HTTP 標頭。

如果您需要在 script 處理常式中設定 HTTP 標頭，請改在應用程式的程式碼中設定。如要瞭解哪些回應標頭會影響快取，請參閱「快取靜態內容」。

如要進一步瞭解 App Engine 專屬標頭，請參閱 要求標頭和回應。

範例 
handlers:
- url: /images
  static_dir: static/images
  http_headers:
    X-Foo-Header: foo
    X-Bar-Header: bar value
    vary: Accept-Encoding
  # ...

CORS 支援

這個功能的重要用途之一，就是支援跨來源資源共享 (CORS)，例如存取另一個 App Engine 應用程式託管的檔案。

舉例來說，假設您有個遊戲應用程式 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。
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
「暫時重新導向」回應碼。
PHP 範例： 
handlers:
- url: /youraccount/.*
  script: auto
  secure: always
  redirect_http_response_code: 301

當使用者的要求遭到重新導向時，系統會將 HTTP 狀態碼設定為 redirect_http_response_code 參數的值。如果這個參數不存在，系統會傳回 302。
script

選用元素。指定送向特定處理常式的要求應以您的應用程式為目標。script 元素唯一可接受的值是 auto，因為所有流量皆透過 entrypoint 指令提供。如要使用靜態處理常式，則至少要有一個處理常式必須包含字行 script: auto 或定義 entrypoint 元素才能成功部署。

handlers:
- url: /images
  static_dir: static/images

- url: /.*
  script: auto
secure 選用。所有網址處理常式都可以使用 secure 設定，包括靜態檔案處理常式。以下是 secure 可用的值：
optional
只要 HTTP 或 HTTPS 要求的網址符合處理常式，就能夠在不重新導向的情況下順利執行。應用程式可檢查要求來決定要使用哪個通訊協定，並依此做出回應。當您沒有提供 secure 給處理常式時，這就會是預設值。
never
如果要求的網址符合這個處理常式，且該要求使用 HTTPS，系統就會自動將該要求重新導向至對等的 HTTP 網址。當使用者的 HTTPS 要求遭到重新導向為 HTTP 要求時，要求中的查詢參數會遭到移除。這能避免讓使用者不小心透過不安全的連線提交應該要透過安全連線傳送的查詢資料。
always
如果要求的網址符合這個處理常式，且該要求沒有使用 HTTPS，系統就會自動將該要求重新導向至相同路徑的 HTTPS 網址。而系統會保留查詢參數，以便在重新導向時使用。
PHP 範例 
handlers:
- url: /youraccount/.*
  script: auto
  secure: always

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

如要搭配 HTTPS 使用自訂網域，您必須先啟用並設定該網域的安全資料傳輸層 (SSL) 憑證。

Google 帳戶的登入和登出作業永遠都是使用安全連線來進行，與應用程式的網址設定方式無關。
static_dir

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

靜態目錄中的每個檔案，都是使用與該檔案的副檔名對應的 MIME 類型來提供，除非該類型遭到目錄的 mime_type 設定覆寫。指定目錄中的所有檔案都會上傳成靜態檔案，無法當做指令碼來執行。

範例： 
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)$
  # ...

靜態檔案不能與應用程式的程式碼檔案相同。

upload

選用。與這個處理常式將會參照的所有檔案之路徑相符的規則運算式。這是必要的，因為處理常式無法判斷應用程式目錄中的哪些檔案會與指定的 url 和 static_files 模式相對應。系統會將靜態檔案和應用程式檔案分開上傳及處理。上述範例可能會使用下列的 upload 模式：archives/(.*)/items/(.*)
url

handlers 下方的必要元素。做為規則運算式的網址模式，可包含分組。舉例來說，/profile/(.*)/(.*) 會符合網址 /profile/edit/manager，且會把 edit 和 manager 當做第一個和第二個分組。

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

static_dir
會使用網址前置字串。當規則運算式模式與 static_dir 元素搭配使用時，不應該包含分組。以這個前置字串開頭的所有網址都會由這個處理常式處理，該處理常式會把網址中位於前置字串之後的部分當做檔案路徑的一部分。
static_files
靜態檔案模式處理常式會建立網址模式與隨應用程式上傳的靜態檔案路徑之間的關聯。網址模式規則運算式可定義規則運算式的分組，以用來建構檔案路徑。您可以在不用對應整個目錄的情況下使用這個方法，而不是使用 static_dir 對應到目錄結構中的特定檔案。

資源調度元素

下表中的元素會設定應用程式的資源調度方式。如未指定資源調度類型，系統預設會設定為自動調整資源配置。

如要進一步瞭解 App Engine 應用程式的資源調度方式，請參閱資源調度類型。

元素 說明
automatic_scaling

選用。僅適用於使用 F1 以上執行個體類別的應用程式。

指定這個元素可變更自動資源調度的預設設定，例如設定服務的執行個體數量、延遲時間和並行連線數的上、下限。

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

max_instances
選用元素。請指定介於 0 到 2147483647 之間的值；如果指定為 0，就會停用這個設定。

這項參數可指定 App Engine 為這個模組版本建立的執行個體數量上限，因此很適合用來限制模組的成本。

min_instances
選用。指定 App Engine 為這個模組版本建立的執行個體數量下限。這些執行個體會在收到要求時提供流量，且在系統已視需要啟動其他執行個體以處理流量之後，還是會繼續提供流量。

請指定介於 0 到 1000 之間的值。您可以將這項參數的值設為 0，允許系統進行資源調度時將執行個體數調整為 0，這麼一來，在沒有任何處理中的要求時，就能降低成本。請注意，系統是依指定的執行個體數量收費，與執行個體是否收到流量無關。

max_idle_instances

選用。App Engine 應為這個版本維持的閒置執行個體數量上限。請指定介於 1 到 1000 之間的值。如未指定，預設值為 automatic，表示 App Engine 會管理閒置執行個體數量。

請注意以下幾點：

  • 如果上限較高，當負載在暴增之後回到正常水準時，閒置執行個體數量的減少速率就會降低。這可協助應用程式在要求負載變動時維持穩定的效能，但也會在這種負載較重的時期提高閒置執行個體的數量 (進而提高執行成本)。
  • 如果上限較低，就能降低執行成本，但在負載不穩定時，效能就可能會降低。

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

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% 時啟動新的執行個體。

target_throughput_utilization
選用元素。請指定介於 0.5 到 0.95 之間的值，預設值為 0.6。

如果與 max_concurrent_requests搭配使用，可指定為因應並行要求而啟動新執行個體的時機。如果並行要求的數量達到 max_concurrent_requests 乘以 target_throughput_utilization 的值，排程器就會嘗試啟動新的執行個體。

max_concurrent_requests

選用。在排程器產生新的執行個體前，單一自動調整資源配置執行個體可接受的並行要求數量 (預設值為 10，最大值為 1000)。

如果與 target_throughput_utilization 搭配使用，可指定為因應並行要求而啟動新執行個體的時機。如果並行要求的數量達到 max_concurrent_requests 乘以 target_throughput_utilization 的值，排程器就會嘗試啟動新的執行個體。

建議您不要將 max_concurrent_requests 設為小於 10，除非您需要單一執行緒。如果值小於 10，系統可能會為安全執行緒應用程式建立超出需求的執行個體，導致產生不必要的費用。

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

max_pending_latency

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

如未指定，則預設值為 automatic。也就是說，要求在觸發啟動新執行個體前，最多可在待處理佇列中停留 10 秒，這是 待處理要求時間限制上限。

如果上限較低，表示 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