appengine-web.xml 參考資料

除了 web.xml部署作業描述元之外,App Engine Java 應用程式還會使用名為 appengine-web.xml 的設定檔來指定應用程式的相關資訊,以及識別應用程式 WAR 中有哪些檔案為靜態檔案 (例如圖片) 和應用程式使用哪些資源檔案。

範例

下列範例是具備最小限度內容的檔案,其中會指定應用程式 ID、版本 ID,但是未指定靜態檔案和資源檔案:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>_your_app_id_</application><!-- unused for Cloud SDK based tooling -->
  <version>alpha-001</version><!-- unused for Cloud SDK based tooling -->
  <threadsafe>true</threadsafe>
</appengine-web-app>

語法

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

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

元素 說明
<application>

如果您使用 gcloud app deploy 指令、IntelliJ 或 Eclipse 外掛程式、Maven 或 Gradle 外掛程式等以 Cloud SDK 為基礎的工具來部署應用程式,則非必要元素。以 Cloud SDK 為基礎的工具會忽略這項元素,並從 gcloud 設定專案屬性取得專案 ID。請注意,您可以使用 gcloud 指令列工具覆寫專案 ID,但是這會設定全機器的專案 ID;如果您正在開發多個專案,此做法可能會造成混淆。<application> 元素包含應用程式的專案 ID。這是您在 Google Cloud Platform 主控台中建立專案時註冊的專案 ID。當您上傳應用程式時,appcfg 就會從這個檔案中取得專案 ID。

<async-session-persistence>

選用元素。您可以設定應用程式,將 HTTP 工作階段資料以非同步方式寫入資料儲存庫,藉以減少要求的延遲時間。


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <async-session-persistence enabled="true" />
  <!-- ... -->
</appengine-web-app>

如果開啟非同步工作階段的持續性,App Engine 將提交「工作佇列」工作,以便將工作階段資料寫入資料儲存庫,然後再將資料寫入 Memcache。根據預設,系統會將工作提交至「預設」佇列。如果您想使用其他佇列,請透過下列指令新增「queue-name」屬性:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <async-session-persistence enabled="true" queue-name="myqueue"/>
  <!-- ... -->
</appengine-web-app>

系統一律會將工作階段資料同步寫入至 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 時,系統會建立已設定這些變數的環境。

<inbound-services>

選用元素。應用程式必須設為啟用服務,之後才能接收電子郵件。您可藉由在 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 Runtime Environment 中的效能。先行編譯的程式碼作用與原始位元組碼完全相同。

如果基於某些原因,您希望應用程式不要使用先行編譯,請在 appengine-web.xml 檔案中加入下列程式碼以關閉此程序:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <precompilation-enabled>false</precompilation-enabled>
  <!-- ... -->
</appengine-web-app>
module

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

如要建立服務,則為必要元素。如果是預設服務,則為選用元素。每項服務和每個版本都必須具有名稱。名稱可包含數字、字母和連字號,長度上限為 63 個字元,且開頭或結尾不得為連字號。請為每項服務和每個版本選擇專屬名稱,不要以相同名稱為服務和版本命名。

如有需要,您也可以參閱服務

<public-root>

選用元素。 <public-root> 是您的應用程式中的目錄,內含應用程式的靜態檔案。發出靜態檔案的要求時,即會在要求路徑後方加上應用程式的 <public-root>,因此會產生含有要求內容之應用程式檔案的路徑。

預設的 <public-root>/

例如,下列程式碼會將網址路徑 /index.html 對應到應用程式檔案路徑 /static/index.html


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <public-root>/static</public-root>
  <!-- ... -->
</appengine-web-app>
<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.Filejavax.servlet.ServletContext.getResource/getResourceAsStream 讀取。如果經由 Class.getResourceAsStream() 則無法存取。

runtime

如要使用 Java 8 執行階段,則必須透過值 java8 指定此項目。如要使用 Java 7 執行階段,請略過此項目或指定值 java7 (請注意,App Engine Java 執行階段以 OpenJDK 為基礎)。

範例:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <runtime>java8</runtime>
  <!-- ... -->
</appengine-web-app>
service

服務先前稱為模組

目前服務定義為僅能經由 gcloud app 指令支援 <service>service_name</service >

<sessions-enabled>

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

此功能預設為關閉。如要開啟此功能,請將下列指令新增至 appengine-web.xml

範例:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <sessions-enabled>true</sessions-enabled>
  <!-- ... -->
</appengine-web-app>

實作會建立種類為 _ah_SESSION 的 Datastore 實體,以及採用字首為 _ahs 之鍵值的 Memcache 項目。您可以使用 Dataflow 範本來刪除這些實體。

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

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

<ssl-enabled>

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

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


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <ssl-enabled>false</ssl-enabled>
  <!-- ... -->
</appengine-web-app>

在 Java Runtime Environment 中,無法只針對某些網址路徑禁用 HTTPS。

<static-error-handlers>

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


<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
表示應用程式已超出資源配額上限
dos_api_denial
此選項會向遭應用程式的 DoS 保護設定封鎖的任何用戶端提供這個錯誤頁面。
timeout
如果應用程式未在期限前回應,則會提供此錯誤代碼。

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

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

<static-files>

選用元素。<static-files> 元素會指定檔案路徑比對模式,決定靜態檔案清單應包含及排除哪些檔案路徑。靜態檔案是從應用程式伺服器以外的專用伺服器和快取記憶體提供,可用來提供圖片、CSS 樣式表或 JavaScript 檔案等靜態內容。

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

<include>

<include> 元素會覆寫包含所有非 JSP 檔案的預設行為。<include> 元素可以指定 HTTP 標頭以回應指定資源的要求。詳情請參閱包含與排除檔案

您可以在包含元素上指定 expiration 屬性以指定靜態快取效期。這個值是由一串以空格分隔的數字和單位所組成,其中單位可為 d (天數)、h (時數)、m (分鐘數) 和 s (秒數)。例如,"4d 5h" 會將快取效期設為首次要求檔案後的 4 天又 5 小時。如果省略到期時間,實際運作伺服器則會將效期預設為 10 分鐘。詳情請參閱靜態快取效期

<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>
<threadsafe>

必要元素。當 appengine-web.xml 中的 threadsafe 元素為 false 時,App Engine 會依序將要求傳送至特定的網路伺服器。當值為 true 時,App Engine 可並行傳送多個要求:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <threadsafe>true</threadsafe>
  <!-- ... -->
</appengine-web-app>

如要使用並行要求,則應用程式的程式碼必須使用適當的執行緒同步處理,才能讓您啟用 threadsafe

<url-stream-handler>

選用元素。可能的值為 nativeurlfetch。此設定的預設值及作用需視其與 Java 8 或 Java 7 執行階段搭配使用而定。

如果搭配 Java 8 執行階段,則預設值為 native,這表示標準的 Java 網路類別會使用標準的 Java HTTP(S) 傳輸,如 Java 8 執行階段與 Java 7 行為的比較所述。此設定會要求應用程式啟用計費功能,否則在要求時會產生下列執行階段錯誤:

在 Java 8 執行階段中,將 url-stream-handler 元素設為 urlfetch 會導致 App Engine 安裝 URLStreamHandlerFactory,而此類別可讓 URL.openConnection 和相關方法針對 httphttps 網址使用網址擷取傳輸。

如果搭配 Java 7 執行階段,則預設值為 urlfetch,這表示標準的 Java 網路類別會使用網址擷取服務,如 Java 8 執行階段與 Java 7 行為的比較所述。

在 Java 7 執行階段中,將值設為 native 表示 App Engine 會使用 Sockets API (而非網址擷取) 來實作 java.net.HttpURLConnection。和 Java 8 類似,此設定會要求應用程式啟用計費功能,否則在要求時會產生下列執行階段錯誤:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <url-stream-handler>urlfetch</url-stream-handler>
  <!-- ... -->
</appengine-web-app>
<version>

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

數字執行個體一律是以數字指定,為了有所區別,版本名稱的開頭應為字母。這樣一來,123.my-module.appspot.com 之類的網址就不會產生歧異;這個網址有兩種解讀方式:如果版本「123」確實存在,目標將是指定模組的版本「123」;如果這個版本不存在,目標會是模組預設版本的執行個體編號 123。

appcfg 指令上傳應用程式時會使用此版本 ID,這是告訴 App Engine 要採用指派的 ID 建立新版應用程式,或使用指派的 ID 取代現有的應用程式版本 (如果已存在)。您可以在網址中使用「-dot-」當做子網域分隔符來測試新版應用程式,例如 https://_version_id_-dot-_your_app_id_.appspot.com。此外,您可透過 Google Cloud Platform 主控台選取應用程式的預設版本。如果未指定版本或指定的版本無效,系統即會載入預設版本。

<warmup-requests-enabled>

選用元素。預設值:true。根據預設,系統會針對 Java 應用程式啟用暖機要求。

如果已啟用暖機要求,App Engine 基礎架構就會向 /_ah/warmup 發出「GET」要求,以便初始化 <load-on-startup> Servlet、ServletContextListeners自訂暖機 Servlet,這樣您就能視需要初始化應用程式的程式碼。您可能必須針對 /_ah/warmup 實作自己的處理常式,實際情況取決於您所選擇的方法。

如要停用暖機要求,請將此元素指定為 false


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <warmup-requests-enabled>false</warmup-requests-enabled>
  <!-- ... -->
</appengine-web-app>

資源調度元素

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

如需比較資源調度類型的效能特色,請參閱調整動態執行個體的資源配置

元素 說明
<automatic-scaling>

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

automatic_scaling 元素可針對模組的執行個體數量、延遲時間和並行連線數設定上下限。

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

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

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

重要事項:如果您使用 Java 專用 App Engine SDK 的 appcfg 指令進行部署,就無法在 appengine-web.xml 中使用這項參數,而必須改為依在 API Explorer 中設定自動調度資源參數一文的指示,或使用 App Engine Admin API 設定參數。

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

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

重要事項:如果您使用 Java 專用 App Engine SDK 的 appcfg 指令進行部署,就無法在 appengine-web.xml 中使用這項參數,而必須改為依在 API Explorer 中設定自動調度資源參數的指示或使用 App Engine Admin API 來設定參數。

<max-instances>
選用元素。指定 App Engine 為這個應用程式版本建立的執行個體數量上限,適合用來限制模組的成本。請指定介於 0 到 2147483647 之間的值。

重要事項:如果您使用 Java 專用 App Engine SDK 的 appcfg 進行部署,就無法在 appengine-web.xml 中使用這項參數,而必須改為依在 API Explorer 中設定自動調度資源參數的指示或使用 App Engine Admin API 來設定參數。

<min-instances>
選用元素。指定 App Engine 為這個模組版本建立的執行個體數量下限。這些執行個體可在要求送達時提供流量,即使系統已視需要啟動其他執行個體以處理流量,這些執行個體仍會繼續提供流量。

請指定介於 0 到 1000 之間的值。您可以將這項參數的值設為 0,允許調整至 0 個執行個體的資源調度,藉此在未提供任何要求時降低成本。請注意,系統是依指定的執行個體數量收費,與執行個體是否收到流量無關。

重要事項:如果您使用 Java 專用 App Engine SDK 的 appcfg 進行部署,就無法在 appengine-web.xml 中使用這項參數,而必須改為依在 API Explorer 中設定自動調度資源參數的指示或使用 App Engine Admin API 來設定參數。

<max-concurrent-requests>

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

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

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

<max-pending-latency>

指定 App Engine 在啟動其他執行個體來處理要求以降低等待延遲時間前,應讓要求在待處理佇列中等候的最長時間。預設值為「30ms」。

  • 如果上限較低,表示 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>
  <threadsafe>true</threadsafe>
  <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>
  <threadsafe>true</threadsafe>
  <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>
  <threadsafe>true</threadsafe>
  <instance-class>B8</instance-class>
  <manual-scaling>
    <instances>5</instances>
  </manual-scaling>
</appengine-web-app>

暫存元素

部署期間完成的大部分工作會以名為「暫存」的準備步驟在本機進行,其中會執行組合 JAR 檔案、編譯 JSP 等工作。您可以在設定檔中使用暫存元素,選擇性地設定暫存行為的特定部分。大部分的應用程式都不需要使用者手動設定暫存行為,即可成功部署。如果您的應用程式無法部署,您可能必須透過下列選項來設定暫存。

元素 說明
<staging>

選用元素。大部分應用程式都不需要變更預設行為。

暫存元素可讓您視部署作業的需要,指定特定的暫存設定。

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

<enable-jar-splitting>

選用元素。將大型 jar 檔案 (> 10MB) 拆分成較小的片段 (預設值:true)。

<jar-splitting-excludes>

使用 jar-splitting 時要排除的後置字串清單。

<disable_jar_jsps>

請勿 jar 從 JSP 產生的類別 (預設值:false)。

<enable-jar-classes>

對 WEB-INF/類別的內容進行 Jar (預設值:true)。

<delete-jsps>

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

<compile-encoding>

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

暫存選項預設值

暫存選項的預設值會取決於您是使用以 App Engine SDK 為基礎的工具 (如 appcfg)、以 Cloud SDK 為基礎的工具 (如 gcloud 指令列),或以 Cloud SDK 為基礎的 MavenGradleEclipseIntelliJ 外掛程式。

暫存元素 以 App Engine SDK 為基礎的預設值 以 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 類型與靜態檔案的副檔名建立關聯。詳情請參閱 Metawerx web.xml 參考資料維基

靜態快取效期

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

您可以提供 expiration 屬性給 <static-files><include ... >,以設定特定靜態檔案處理常式的快取效期。這個值是由一串以空格分隔的數字和單位所組成,其中單位可為 d (天數)、h (時數)、m (分鐘數) 和 s (秒數)。例如,"4d 5h" 會將快取效期設為首次要求檔案後的 4 天又 5 小時。如果省略到期時間,實際運作伺服器則會將效期預設為 10 分鐘。

例如:

<static-files>
  <include path="/**.png" expiration="4d 5h" />
</static-files>

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

URLFetch 逾時

您可以設定每個 URLFetch 要求的期限。擷取的預設期限是 5 秒。您可以在 appengine-web.xml 設定檔加入下列設定,即可變更此預設值。請以秒為單位指定逾時時間:

<system-properties>
    <property name="appengine.api.urlfetch.defaultDeadline" value="10"/>
</system-properties>
本頁內容對您是否有任何幫助?請提供意見:

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

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