appengine-web.xml 參考資料

區域 ID

REGION_ID 是 Google 根據您建立應用程式時選取的區域指派的縮寫代碼。這個代碼不對應國家/地區或省/市,即使某些區域 ID 可能與常用的國家/地區和省/市代碼相似。如果是 2020 年 2 月後建立的應用程式,App Engine 網址會包含 REGION_ID.r。如果是 2020 年 2 月前建立的現有應用程式,網址中的區域 ID 則為選用。

進一步瞭解區域 ID。

只有在將現有應用程式從 App Engine Java 8 執行階段遷移至最新支援的 Java 版本,且想要使用舊版隨附服務時,才應使用 appengine-web.xml 檔案設定應用程式。如果您在專案中使用 appengine-web.xml,系統會在部署時自動產生 app.yaml。

App Engine Java 應用程式會使用名為 appengine-web.xml 的設定檔,指定應用程式的相關資訊,並識別應用程式 WAR 檔案中的哪些檔案是靜態檔案 (例如圖片),哪些是應用程式使用的資源檔案。

語法

App Engine Java 應用程式必須在 WAR 的 WEB-INF/ 目錄中,包含名為 appengine-web.xml 的檔案。這是一個 XML 檔案,其根元素為 <appengine-web-app>。

您可以在 SDK 的 docs/ 目錄中,找到 appengine-web.xml 的文件類型定義和結構定義規格。

元素 說明
<application>

如果您使用以 Google Cloud SDK 為基礎的工具 (例如 gcloud app deploy 指令、IntelliJ 外掛程式、Maven 或 Gradle 外掛程式) 部署應用程式,則不需要執行這項操作。以 Google Cloud SDK 為基礎的工具會忽略這個元素,並從 gcloud 設定專案屬性取得專案 ID。請注意,雖然您可以使用 Google Cloud CLI 覆寫專案 ID,但這會設定全機專案 ID,如果您正在開發多項專案,可能會造成混淆。<application> 元素包含應用程式的專案 ID。這是您在 Google Cloud console中建立專案時註冊的專案 ID。

app_engine_apis

選用。將這個欄位設為 true,即可啟用第二代執行階段的所有隨附服務。如果將這個欄位設為 true 或 false,則只有在未指定 app_engine_bundled_services 設定時,部署作業才會成功。

建議您使用 app_engine_bundled_services 指定應用程式所需的隨附服務。這種做法可提供精細控管,並盡可能減少不必要的服務,進而提升安全性。此外,這項做法可確保應用程式收到實際使用服務的重要更新,方便維護。

app_engine_bundled_services

選用。設定這個欄位,即可為第二代執行階段啟用特定隨附服務的存取權。如果設定「app_engine_apis」欄位,就無法使用這項設定。

使用這項設定指定下列任一支援的隨附服務:

  • 應用程式身分:app_identity_service
  • Blobstore:blobstore
  • 功能:capability_service
  • Datastore:datastore_v3
  • 圖片數:images
  • 命名空間:namespaces
  • 搜尋:search
  • 延後:deferred
  • 郵件:mail
  • Memcache:memcache
  • 模組:modules
  • 工作佇列:taskqueue
  • 網址擷取:urlfetch
  • 使用者:user

範例:

<app-engine-bundled-services>
  <api>datastore_v3</api>
  <api>memcache</api>
</app-engine-bundled-services>

這個範例可讓應用程式僅使用 Datastore 和 Memcache 隨附服務。

<entrypoint>

選用,且僅適用於第二代執行階段。 覆寫預設進入點,也就是啟動 Java 應用程式的程序指令列。根據預設,為 F4 執行個體類別產生的進入點 (記憶體設定是根據執行個體類別計算) 相當於下列設定:

  <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <entrypoint>
   java
   -showversion -Xms32M -Xmx819M -XX:+UseG1GC -XX:+ParallelRefProcEnabled
   -XX:+PrintCommandLineFlags
   --add-opens java.base/java.lang=ALL-UNNAMED
   --add-opens java.base/java.nio.charset=ALL-UNNAMED
   --add-opens java.logging/java.util.logging=ALL-UNNAMED
   --add-opens java.base/java.util.concurrent=ALL-UNNAMED
   -Dclasspath.runtimebase=/base/java_runtime
   -Djava.class.path=/base/java_runtime/runtime-main.jar
   -Djava.library.path=/base/java_runtime:
   com/google/apphosting/runtime/JavaRuntimeMainWithDefaults
   --fixed_application_path=/workspace
   /base/java_runtime
  </entrypoint>
</appengine-web-app>

您可以修改設定,新增額外的 JVM 程序旗標,或定義自己的程序來啟動。請注意,應用程式部署在 /workspace 目錄中,而執行階段 JAR 則位於 /base/java_runtime 目錄下。

瞭解如何使用環境變數自訂 Java 執行階段的進入點。
<async-session-persistence>

選用元素。您可以將應用程式設為以非同步方式將 HTTP 工作階段資料寫入 Datastore,藉此縮短要求延遲時間:

<async-session-persistence enabled="true" />

啟用非同步工作階段持續性後,App Engine 會提交工作佇列工作,先將工作階段資料寫入 Datastore,再寫入 memcache。根據預設,工作會提交至「default」佇列。如想使用其他佇列,請執行下列指令來新增「queue-name」屬性:

  <async-session-persistence enabled="true" queue-name="myqueue"/>

工作階段資料一律會同步寫入 memcache。無法使用 Memcache (或已清除工作階段資料) 時,如果要求嘗試讀取工作階段資料,系統會將其容錯移轉至 Datastore,但是其中可能還沒有最新的工作階段資料。這表示非同步工作階段的持續性,可能會使應用程式看到過時的工作階段資料。不過,對大多數應用程式來說,延遲時間縮短帶來的好處遠大於風險。

<auto-id-policy> 選用。如果您要自動設定實體 ID,可以透過設定自動 ID 政策來變更所使用的方法。以下是有效的選項:
default
預設值。會使用分散的自動 ID;這些 ID 是分布均勻的大型整數,且整數小到足以由 64 位元浮點數表示。
legacy
舊版選項會在日後推出的版本中遭到淘汰,最終會遭到移除。詳情請參閱宣布該變更的網誌文章。
<automatic-scaling>

選用。如需完整說明,請參閱自動調整資源配置一節。

<basic-scaling>

選用。如需完整說明,請參閱基本資源調度一節。

<env-variables>

選用元素。appengine-web.xml 檔案可以定義應用程式執行時設定的環境變數。

<env-variables>
<env-var name="DEFAULT_ENCODING" value="UTF-8" />
</env-variables>

為避免與本機環境發生衝突,開發伺服器不會根據這個檔案設定環境變數,且本機環境必須已將這些變數設為相符的值。

export DEFAULT_ENCODING="UTF-8"
dev_appserver war

部署至 App Engine 時,系統會建立已設定這些變數的環境。

如要判斷連線在沒有任何資料傳輸的情況下,可以閒置多久,用戶端才會關閉連線,請使用下列語法設定閒置逾時:

<env-variables>
<env-var name="APPENGINE_API_CALLS_IDLE_TIMEOUT_MS" value="TIMEOUT_IN_MS" />
</env-variables>

將 TIMEOUT_IN_MS 替換為所需的逾時時間 (以毫秒為單位)。

如要符合 60 秒的整體要求/網址擷取期限,請將其設為 60000。或者,將其設為略低於伺服器端逾時 (通常為 60 秒) 的值可能會有幫助,例如 59000。目前預設值為 58000 毫秒。

這項閒置逾時設定與擴充的整體要求期限不同,也與您使用 appengine.api.urlfetch.defaultDeadline 設定的 URL Fetch API 期限不同。

<inbound-services>

選用元素。應用程式必須先設定啟用服務,才能接收電子郵件。如要為 Java 應用程式啟用服務,請在 appengine-web.xml 檔案中加入 <inbound-services> 區段。

可用的內送服務如下:

mail
允許應用程式接收郵件。
<instance-class>

選用元素。這個模組的執行個體類別大小。

指定不同的資源調度選項時,可使用下列執行個體類別:

automatic_scaling
使用自動調度資源時,可以使用 F1、F2、F4 和 F4_1G 執行個體類別。
預設:如未指定執行個體類別和 automatic_scaling 元素,系統會指派 F1。
basic_scaling
使用基本級資源調度時,可用的執行個體類別包括 B1、B2、B4、B4_1G 和 B8。
預設:如果您未指定執行個體類別和 basic_scaling 元素,系統會指派 B2。
manual_scaling
使用手動調度資源時,可以使用 B1、B2、B4、B4_1G 和 B8 執行個體類別。
預設:如果您未指定執行個體類別和 manual_scaling 元素,系統會指派 B2。

注意:如果 instance-class 設為 F2 以上,您可以將 max-concurrent-requests 設為高於預設值 10 的值,藉此最佳化執行個體。如要找出最適合的值,請逐步提高該值,並監控應用程式的效能。

<manual-scaling>

選用。如需完整說明,請參閱手動調整資源配置一節。

<precompilation-enabled>

選用元素。App Engine 會對應用程式的 Java 位元碼使用「預先編譯」程序,藉此提升應用程式在 Java 執行階段環境中的效能。預先編譯的程式碼與原始位元碼的功能相同。

如果因故不希望應用程式使用預先編譯功能,只要在 appengine-web.xml 檔案中加入下列程式碼,即可關閉這項功能:

<precompilation-enabled>false</precompilation-enabled>
<module>

注意:模組現在稱為「服務」,而服務仍會在 appengine-web.xml 檔案中宣告為模組,例如:<module>service_name</module>。

如要建立服務,則必須提供這項資訊。預設服務的選用項目。 每項服務和每個版本都必須具有名稱。名稱可包含數字、字母和連字號,長度不得超過 63 個字元,開頭或結尾不得為連字號,且不得包含 `-dot` 字串。請為各項服務和各個版本選擇不重複的名稱。請勿在服務和版本之間重複使用名稱。

另請參閱「服務」。

<public-root>

選用元素。<public-root> 是應用程式中的目錄,其中包含應用程式的靜態檔案。提出靜態檔案要求時,系統會將應用程式的 <public-root> 附加至要求路徑。這會提供應用程式檔案的路徑,其中包含要求的內容。

<public-root> 預設為 /。

舉例來說,下列指令會將網址路徑 /index.html 對應至應用程式路徑 /static/index.html:

<public-root>/static</public-root>
<resource-files>

選用。應用程式程式碼可使用檔案系統,存取 <resource-files> 元素中列出的檔案。這些檔案會與應用程式一起儲存在應用程式伺服器上,與靜態檔案的儲存和提供方式不同。

<resource-files> 元素可包含下列元素:

<include>
<include> 元素會將檔案指定為資源檔案,並可供應用程式程式碼使用。這些檔案僅供程式碼讀取,不會用於提供流量。納入及排除檔案。
<exclude>

系統不會上傳符合 <exclude> 模式的檔案和目錄,也不會提供給應用程式程式碼。不過,當應用程式在本機開發伺服器上執行時,仍可存取這些檔案和目錄。詳情請參閱「納入及排除檔案」一節。

範例:
<resource-files>
  <include path="/**.xml" />
  <exclude path="/feeds/**.xml" />
</resource-files>

這個範例說明如何將所有 .xml 檔案指定為資源檔案,但不包括 feeds/ 目錄及其所有子目錄中的檔案。

App Engine 資源檔案是使用 java.io.File 或 javax.servlet.ServletContext.getResource/getResourceAsStream 讀取。無法透過 Class.getResourceAsStream() 存取。

<runtime>

如要使用最新支援的 Java 版本,請將這個項目的值指定為 java25。

範例:
<runtime>java25</runtime>
<service>

服務先前稱為模組。

只有 gcloud app 指令支援將服務定義為:<service>service_name</service >

<service-account>

選用。<service-account> 元素可讓您指定使用者自行管理的服務帳戶做為版本身分。存取其他 Google Cloud 服務及執行工作時,系統會使用指定的服務帳戶。

範例:
<service-account>[SERVICE_ACCOUNT_NAME]@[PROJECT_ID].</service-account>
<sessions-enabled>

選用元素。App Engine 包含工作階段實作,使用 Servlet 工作階段介面。實作會將工作階段資料儲存在 Datastore 中,以便永久保存,並使用 memcache 提高速度。和其他大部分 Servlet 容器一樣,在要求期間透過「session.setAttribute()」設定的工作階段屬性於要求結束時仍會留存。

這項功能預設為關閉。如要啟用,請在 appengine-web.xml 中加入以下內容:

範例:
<sessions-enabled>true</sessions-enabled>

實作會建立 _ah_SESSION 類型的 Datastore 實體,以及使用前置字串為 _ahs 的金鑰建立 memcache 項目。您可以使用 Dataflow 範本刪除這些實體。

注意:App Engine 會將工作階段資料儲存在 Datastore 和 memcache 中,因此儲存在工作階段中的所有值都必須實作 java.io.Serializable 介面。

請參閱 async-session-persistence 元素,瞭解如何縮短工作階段資料的儲存延遲時間。

<ssl-enabled>

選用元素。根據預設,任何使用者都可以使用 HTTP 或 HTTPS 存取任何網址。 您可以在 deployment descriptor 中,設定應用程式要求特定網址使用 HTTPS。詳情請參閱部署作業描述元:安全的網址。

如要禁止應用程式使用 HTTPS,請在 appengine-web.xml 檔案中加入以下內容:

<ssl-enabled>false</ssl-enabled>

在 Java 執行階段環境中,無法只禁止部分網址路徑使用 HTTPS。

<static-error-handlers>

選用元素。發生特定錯誤時,App Engine 會提供一般錯誤頁面。您可以設定應用程式,改為提供自訂靜態檔案,而不是提供上述一般錯誤頁面,但是自訂錯誤資料必須小於 10 KB。您可以在應用程式的 appengine-web.xml 檔案中指定檔案,為每個支援的錯誤代碼設定要提供的不同靜態檔案。如要提供自訂錯誤頁面,請在 appengine-web.xml 中新增 <static-error-handlers> 區段,如以下範例所示:

<static-error-handlers>
  <handler file="default_error.html" />
  <handler file="over_quota.html" error-code="over_quota" />
</static-error-handlers>

警告:請確認錯誤回應檔案的路徑與靜態檔案處理常式路徑不重疊。

每個 file 項目都代表一個靜態檔案,應取代一般錯誤回應。error-code 會指出應導致提供相關檔案的錯誤代碼。支援的錯誤代碼如下所示:

over_quota
表示應用程式已超出資源配額。
timeout
如果應用程式未在期限前回應,就會放送這個廣告。

error-code 為選用項目;如未指定,則指定檔案會是應用程式的預設錯誤回應。

您可以視需要指定提供自訂錯誤時要使用的 mime-type。請參閱 MIME 類型的完整清單。

<static-files>

選用元素。<static-files> 元素會指定與檔案路徑相符的模式,以便在靜態檔案清單中納入或排除檔案,並覆寫或修改預設行為。靜態檔案是由專用伺服器和快取提供,與應用程式伺服器分開,適合用於提供圖片、CSS 樣式表或 JavaScript 檔案等靜態內容。

<static-files> 元素可包含下列元素:

<include>

<include> 元素會覆寫包含所有非 JSP 檔案的預設行為。<include> 元素可指定回應指定資源要求時要使用的 HTTP 標頭。詳情請參閱「納入及排除檔案」一節。

您可以在 include 元素中指定 expiration 屬性,覆寫預設的靜態快取到期時間。值是由數字和單位組成的字串,以空格分隔,單位可以是 d (天)、h (小時)、m (分鐘) 和 s (秒)。舉例來說,"4d 5h" 會將快取到期時間設為首次要求檔案後的 4 天 5 小時。詳情請參閱「快取到期」。

<exclude>
將應用程式部署至 App Engine 時,系統不會上傳符合 <exclude> 模式的檔案和目錄。不過,當應用程式在本機開發伺服器上執行時,仍可存取這些檔案和目錄。詳情請參閱「納入及排除檔案」一節。
範例
<static-files>
  <include path="/my_static-files" >
    <http-header name="Access-Control-Allow-Origin"
                 value="http://example.org" />
  </include>
</static-files>
<system-properties>

選用。appengine-web.xml 檔案可定義應用程式執行時設定的系統屬性和環境變數。

<system-properties>
  <property name="myapp.maximum-message-length" value="140" />
  <property name="myapp.notify-every-n-signups" value="1000" />
  <property name="myapp.notify-url"
            value="http://www.example.com/signupnotify" />
</system-properties>

<env-variables>
  <env-var name="DEFAULT_ENCODING" value="UTF-8" />
</env-variables>

選用。您可以設定 HTTP 連接器,提高 CPU 和記憶體使用率。如果應用程式會與 Datastore 或工作佇列作業互動,請設定監控功能,以便在啟用這項功能後監控效能和行為影響。

  <system-properties>
    <property name="appengine.use.httpconnector" value="true"/>
  </system-properties>

選用。您可以使用下列系統屬性,設定基礎 Java 17 執行階段在 EE 8 上運作、Java 21 在 EE 10 上運作,或 Java 25 在 EE 11 上運作。如要進一步瞭解 EE 支援,請參閱「在相容的 Enterprise Edition (EE) 版本上更新 Java」。

  <system-properties>
    <property name="appengine.use.EE11" value="true"/><!--only for Java 25-->
  </system-properties>
從 Java 21 開始,您可以設定 Java 網路伺服器使用虛擬執行緒。例如:
  <system-properties>
    <property name="appengine.use.virtualthreads" value="true"/>
  </system-properties>
如要進一步瞭解執行緒支援,請參閱「Jetty 12 – Virtual Threads Support」(Jetty 12 - 虛擬執行緒支援)。
<url-stream-handler>

選用。可能的值為 native 或 urlfetch。

預設值為 native,表示標準 Java 網路類別會使用標準 Java HTTP(S) 傳輸。如要使用這項設定,您必須為應用程式啟用計費功能,否則會收到例外狀況,詳情請參閱「發出要求」。

如果將 url-stream-handler 設為 urlfetch,URL.openConnection 和相關方法會使用網址擷取功能進行 http 和 https 傳輸。

<url-stream-handler>urlfetch</url-stream-handler>
<version>

<version> 元素包含應用程式程式碼最新版本的版本 ID。版本 ID 可包含小寫字母、數字和連字號,開頭不得為前置字元「ah-」,且「default」和「latest」為保留名稱,無法使用。

版本名稱開頭應為英文字母,以便與一律以數字指定的數字執行個體區分。這樣可以避免 123.my-module.uc.r.appspot.com 等網址產生歧義,因為這類網址有兩種解讀方式:如果版本「123」存在,目標就會是指定模組的版本「123」。如果該版本不存在,目標就會是模組預設版本的第 123 個執行個體。

<warmup-requests-enabled>

選用。預設值:true。Java 應用程式預設會啟用暖機要求。

啟用暖機要求後,App Engine 基礎架構會向 /_ah/warmup 發出 `GET` 要求,初始化 <load-on-startup> Servlet、ServletContextListeners 和自訂暖機 Servlet,讓您視需要初始化應用程式的程式碼。視您選擇的方法而定,您可能需要為 /_ah/warmup 實作自己的處理常式。

如要停用暖機要求,請為這個元素指定 false:

<warmup-requests-enabled>false</warmup-requests-enabled>
<vpc-access>

選用。為服務設定直連虛擬私有雲輸出,讓應用程式能向虛擬私有雲網路中的內部資源傳送要求。您無法同時指定 <vpc-access> 和 <vpc-access-connector>。

這個元素包含下列元素:

<network-interface>

指定 <vpc-access> 時,必須提供這項資訊。 包含用於直連虛擬私有雲輸出的網路介面設定。您可以指定 <network>、<subnet> 或兩者。如果只指定 <network>,子網路會預設為與網路同名。如果只指定 <subnet>,App Engine 會從指定的子網路查詢虛擬私有雲網路。

<network>
要用於直接虛擬私有雲輸出的虛擬私有雲網路名稱。如果是 Shared VPC,則必須指定完整的資源路徑,例如 projects/HOST_PROJECT_ID/global/networks/NETWORK。
<subnet>
用於直連虛擬私有雲輸出的虛擬私有雲子網路名稱。如果是 Shared VPC,則必須指定完整資源路徑,例如 projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET。
<tag>
選用。與服務執行個體建立關聯的網路標記,用於防火牆規則和路由政策。如要新增多個網路標記,請重複 <tag> 元素。
<vpc-egress>
選用。控管傳出流量的轉送方式。這個元素支援下列設定:
private-ranges-only
預設值。只有傳送至內部 IP 位址的流量會透過虛擬私有雲網路轉送。網際網路流量會使用預設的 App Engine 路徑。
all-traffic
所有傳出要求都會透過虛擬私有雲網路轉送。

如要進一步瞭解如何設定直連虛擬私有雲輸出及管理執行個體限制,請參閱「使用直連虛擬私有雲輸出連線至虛擬私有雲網路」和「配額與限制」。

範例
<vpc-access>
  <network-interface>
    <network>direct-vpc-network</network>
    <subnet>direct-vpc-subnetwork</subnet>
    <tag>my-tag1</tag>
    <tag>my-tag2</tag>
  </network-interface>
  <vpc-egress>all-traffic</vpc-egress>
</vpc-access>
<vpc-access-connector>

選用元素。設定應用程式使用無伺服器 VPC 存取連接器,讓應用程式將要求傳送至虛擬私有雲網路中的內部資源。在 <name> 元素中指定連接器的完整名稱:

<vpc-access-connector>
  <name>projects/[PROJECT_ID]/locations/[REGION]/connectors/[CONNECTOR_NAME]</name>
</vpc-access-connector>

詳情請參閱「連線至虛擬私有雲網路中的內部資源」。

資源調度元素

下表列出的選項是用來定義您可以指定的應用程式資源調度方式。

如要比較不同資源調度類型的成效與特色,請參閱調整動態執行個體的資源配置。

元素 說明
<automatic-scaling>

選用。除非另行指定,否則系統預設會採用自動調整資源配置設定,預設的執行個體類別為 F1。

automatic_scaling 元素會設定模組的執行個體數量、延遲時間和並行連線的最低和最高等級。

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

<target-cpu-utilization>
選用。請指定介於 0.5 至 0.95 之間的值。

這項參數是用來指定 CPU 用量的臨界值,讓系統在該用量達到臨界值時啟動新的執行個體來處理流量,進而讓您可在效能和成本之間取得平衡。如果您把該值調低,效能和成本就會提高;如果您把這個值調高,效能和成本都會下降。舉例來說,如果值為 0.7,則代表系統會在 CPU 用量達到 70% 時啟動新的執行個體。

<target-throughput-utilization>
選用元素。請指定介於 0.5 至 0.95 之間的值。

如果與 max-concurrent-requests搭配使用,可指定為因應並行要求而啟動新執行個體的時機。如果並行要求的數量達到 max-concurrent-requests 乘以 target-throughput-utilization 的值,排程器就會啟動新的執行個體。

<max-instances>
選用元素。指定 App Engine 為這個應用程式版本建立的執行個體數量上限,適合用來限制模組的成本。請指定介於 0 至 2147483647 之間的值。
<min-instances>
選用元素。指定 App Engine 為這個模組版本建立的執行個體數量下限。這些執行個體會在要求送達時處理流量,即使系統視需要啟動額外執行個體來處理流量,這些執行個體仍會繼續處理流量。

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

<max-concurrent-requests>

選用。自動調度資源執行個體在排程器產生新執行個體前,可接受的並行要求數量 (預設值:10,最大值:80)。

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

注意:如果 instance-class 設為 F2 以上,您可以將 max-concurrent-requests 設為高於預設值 10 的值,藉此最佳化執行個體。如要找出最適合的值,請逐步提高該值,並監控應用程式的效能。

<max-idle-instances>

App Engine 應為這個版本維護的閒置執行個體數量上限。預設值為「automatic」。 請注意以下幾點:

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

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

<max-pending-latency>

App Engine 允許要求在待處理佇列中等待的時間上限,超過這個時間後,系統就會啟動其他執行個體來處理要求,藉此縮短等待延遲時間。

  • 如果上限偏低,App Engine 會提早為待處理要求啟動新的執行個體,進而提升效能,但會增加執行成本。
  • 如果上限較高,當有待處理的要求,但沒有閒置的執行個體可處理時,使用者可能需要等待較長的時間,才能處理要求,但應用程式的執行成本會較低。
<min-idle-instances>

要保持運作並準備好處理流量的執行個體數量。這項設定僅適用於接收大部分流量的版本。請注意以下幾點:

  • 如果下限較低,閒置期間的執行成本就會降低,但這也代表在發生負載突然暴增的情況時,可立刻做出回應的執行個體數量會較少。
  • 如果將下限設得較高,應用程式就能做好準備,因應要求負載快速飆升的情況。App Engine 會讓下限數量的執行個體保持運作以處理傳入的要求。系統是依執行個體數量收費,與執行個體是否處理要求無關。如要讓這項功能正常運作,請務必啟用暖機要求,並確保應用程式會處理暖機要求。

    如果您設定了閒置執行個體數量的下限,等待延遲時間對應用程式效能的影響會較低。由於 App Engine 會保留閒置執行個體,因此除非負載量異常飆高,否則要求不太可能進入待處理佇列。您必須測試應用程式和預期流量,才能判斷要保留之執行個體的最佳數量為何。

<min-pending-latency>

App Engine 應允許要求在待處理佇列中等待的最短時間 (以秒為單位),超過這個時間就會啟動新的執行個體來處理要求。請指定 0.01 到 15 之間的值。

  • 如果下限較低,代表當所有的現有執行個體皆為運作中時,要求在待處理佇列中等候的時間必須較短。這可改善效能,但會提高應用程式的執行成本。
  • 如果下限較高,代表當所有的現有執行個體皆為運作中時,要求等候的時間會較長。這可降低執行成本,但使用者必須等待較久的時間才能讓要求得到處理。
範例
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <instance-class>F2</instance-class>
  <automatic-scaling>
    <target-cpu-utilization>0.65</target-cpu-utilization>
    <min-instances>5</min-instances>
    <max-instances>100</max-instances>
    <max-concurrent-requests>50</max-concurrent-requests>
  </automatic-scaling>
</appengine-web-app>
<basic-scaling>

選用元素。<basic-scaling> 元素會設定模組的執行個體數量。

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

<idle-timeout>
選用元素。執行個體會在收到最後一個要求後,經過這段時間再關閉。預設值為 5 分鐘。
<max-instances>
必要元素。指定 App Engine 為這個模組版本建立的執行個體數量上限,這有助於限制模組的成本。
範例
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <instance-class>B8</instance-class>
  <basic-scaling>
    <max-instances>11</max-instances>
    <idle-timeout>10m</idle-timeout>
  </basic-scaling>
</appengine-web-app>
<manual-scaling>

選用元素。<manual-scaling> 元素可讓您手動調度模組資源,並設定模組的執行個體數量。

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

<instances>
一開始要指派給模組的執行個體數量。
範例
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <instance-class>B8</instance-class>
  <manual-scaling>
    <instances>5</instances>
  </manual-scaling>
</appengine-web-app>

暫存元素

部署期間的大部分工作都是在本機的準備步驟中完成,這個步驟稱為「暫存」,會組合 JAR 檔案、編譯 JSP 等。您也可以在應用程式設定檔中使用暫存元素,設定暫存行為的特定部分。大部分的應用程式都不需要使用者手動設定暫存行為,即可成功部署。如果應用程式未部署,您可能需要使用下表所示的選項設定測試環境。

元素 說明
<staging>

選用。大多數應用程式都不需要變更預設行為。

如有部署需求,您可以使用暫存元素指定特定暫存設定。

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

<enable-jar-splitting>

選用。將大型 jar 檔案 (超過 10 MB) 分割成較小的片段。(預設值:true)。

<jar-splitting-excludes>

指定以逗號分隔的檔案尾碼清單。 如果啟用 enable-jar-splitting,系統會從所有 JAR 中排除與後置字串相符的所有檔案。

<disable_jar_jsps>

請勿將 JSP 產生的類別封裝成 JAR 檔案。 (預設值:false)。

<enable-jar-classes>

將 WEB-INF/classes 的內容封裝成 JAR 檔案。 (預設值:true)。

<delete-jsps>

編譯後刪除 JSP 來源檔案。 (預設值:true)。

<compile-encoding>

編譯來源檔案的輸入編碼。(預設值:utf-8)。

例如:

        <staging>
          <delete-jsps>false</delete-jsps>
        </staging>
        

暫存選項預設值

預設的暫存選項會因您使用的工具而異,例如以 Google Cloud SDK 為基礎的工具 (如 gcloud CLI),或以 Google Cloud SDK 為基礎的 Maven 或 Gradle 外掛程式。

暫存元素 以 App Engine SDK 為基礎的預設值 Google Cloud SDK 預設值
enable-jar-splitting false true
jar-splitting-excludes 不適用 不適用
disable-jar-jsps false false
enable-jar-classes false true。這可能會影響類別載入順序,因此如果應用程式依賴使用先前 false 預設值的特定順序,您可以將其設為 false。
delete-jsps false true
compile-encoding utf-8 utf-8

包含及排除語法

路徑模式是使用零或多個 <include> 和 <exclude> 元素指定。在模式中,'*' 代表檔案或目錄名稱中的零或多個任意字元,** 則代表路徑中的零或多個目錄。將應用程式部署至 App Engine 時,系統不會上傳符合 <exclude> 模式的檔案和目錄。但是當應用程式在本機開發伺服器上執行時,仍可存取這些檔案和目錄。

<include> 元素會覆寫包含所有檔案的預設行為。<exclude> 元素會在所有 <include> 模式 (以及未提供明確 <include> 時的預設模式) 之後套用。

以下範例說明如何將所有 png 檔案指定為靜態檔案 (data/ 目錄及其所有子目錄中的檔案除外):

<static-files>
  <include path="/**.png" />
  <exclude path="/data/**.png" />
</static-files>

您也可以設定 HTTP 標頭,以便在回應這些靜態資源要求時使用。

<static-files>
  <include path="/my_static-files" >
    <http-header name="Access-Control-Allow-Origin"
                 value="http://example.org" />
  </include>
</static-files>

靜態檔案的 MIME 類型

根據預設,靜態檔案會使用根據副檔名選取的 MIME 類型提供。您可以使用 web.xml 中的 mime-mapping 元素,將自訂 MIME 類型與靜態檔案的副檔名 建立關聯。

URLFetch 逾時

您可以為每個 URLFetch 要求設定期限。擷取作業的預設期限為 5 秒。如要變更這項預設設定,請在 appengine-web.xml 設定檔中加入以下設定。請以秒為單位指定逾時時間:

<system-properties>
    <property name="appengine.api.urlfetch.defaultDeadline" value="10"/>
</system-properties>