區域 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 為基礎的工具 (例如 |
app_engine_apis
|
選用。將這個欄位設為 建議您使用 |
app_engine_bundled_services
|
選用。設定這個欄位,即可為第二代執行階段啟用特定隨附服務的存取權。如果設定「 使用這項設定指定下列任一支援的隨附服務:
範例: <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 程序旗標,或定義自己的程序來啟動。請注意,應用程式部署在 |
<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 政策來變更所使用的方法。以下是有效的選項:
|
<automatic-scaling> |
選用。如需完整說明,請參閱自動調整資源配置一節。 |
<basic-scaling> |
選用。如需完整說明,請參閱基本資源調度一節。 |
<env-variables> |
選用元素。 <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> 將 如要符合 60 秒的整體要求/網址擷取期限,請將其設為 這項閒置逾時設定與擴充的整體要求期限不同,也與您使用 |
<inbound-services> |
選用元素。應用程式必須先設定啟用服務,才能接收電子郵件。如要為 Java 應用程式啟用服務,請在 可用的內送服務如下:
|
<instance-class> |
選用元素。這個模組的執行個體類別大小。 指定不同的資源調度選項時,可使用下列執行個體類別:
|
<manual-scaling> |
選用。如需完整說明,請參閱手動調整資源配置一節。 |
<precompilation-enabled> |
選用元素。App Engine 會對應用程式的 Java 位元碼使用「預先編譯」程序,藉此提升應用程式在 Java 執行階段環境中的效能。預先編譯的程式碼與原始位元碼的功能相同。
如果因故不希望應用程式使用預先編譯功能,只要在 <precompilation-enabled>false</precompilation-enabled> |
<module> |
注意:模組現在稱為「服務」,而服務仍會在 如要建立服務,則必須提供這項資訊。預設服務的選用項目。 每項服務和每個版本都必須具有名稱。名稱可包含數字、字母和連字號,長度不得超過 63 個字元,開頭或結尾不得為連字號,且不得包含 `-dot` 字串。請為各項服務和各個版本選擇不重複的名稱。請勿在服務和版本之間重複使用名稱。 另請參閱「服務」。 |
<public-root> |
選用元素。
舉例來說,下列指令會將網址路徑 <public-root>/static</public-root> |
<resource-files> |
選用。應用程式程式碼可使用檔案系統,存取
App Engine 資源檔案是使用 |
<runtime> |
如要使用最新支援的 Java 版本,請將這個項目的值指定為 <runtime>java25</runtime> |
<service> |
服務先前稱為模組。 只有 gcloud app 指令支援將服務定義為: |
<service-account> |
選用。 <service-account>[SERVICE_ACCOUNT_NAME]@[PROJECT_ID].</service-account> |
<sessions-enabled> |
選用元素。App Engine 包含工作階段實作,使用 Servlet 工作階段介面。實作會將工作階段資料儲存在 Datastore 中,以便永久保存,並使用 memcache 提高速度。和其他大部分 Servlet 容器一樣,在要求期間透過「session.setAttribute()」設定的工作階段屬性於要求結束時仍會留存。
這項功能預設為關閉。如要啟用,請在 <sessions-enabled>true</sessions-enabled>
實作會建立
注意:App Engine 會將工作階段資料儲存在 Datastore 和 memcache 中,因此儲存在工作階段中的所有值都必須實作
請參閱 |
<ssl-enabled> |
選用元素。根據預設,任何使用者都可以使用 HTTP 或 HTTPS 存取任何網址。 您可以在 deployment descriptor 中,設定應用程式要求特定網址使用 HTTPS。詳情請參閱部署作業描述元:安全的網址。
如要禁止應用程式使用 HTTPS,請在 <ssl-enabled>false</ssl-enabled> 在 Java 執行階段環境中,無法只禁止部分網址路徑使用 HTTPS。 |
<static-error-handlers> |
選用元素。發生特定錯誤時,App Engine 會提供一般錯誤頁面。您可以設定應用程式,改為提供自訂靜態檔案,而不是提供上述一般錯誤頁面,但是自訂錯誤資料必須小於 10 KB。您可以在應用程式的 <static-error-handlers> <handler file="default_error.html" /> <handler file="over_quota.html" error-code="over_quota" /> </static-error-handlers> 警告:請確認錯誤回應檔案的路徑與靜態檔案處理常式路徑不重疊。
每個
您可以視需要指定提供自訂錯誤時要使用的 |
<static-files> |
選用元素。
<static-files> <include path="/my_static-files" > <http-header name="Access-Control-Allow-Origin" value="http://example.org" /> </include> </static-files> |
<system-properties> |
選用。 <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> <system-properties> <property name="appengine.use.virtualthreads" value="true"/> </system-properties> |
<url-stream-handler> |
選用。可能的值為 預設值為 如果將 <url-stream-handler>urlfetch</url-stream-handler> |
<version> |
版本名稱開頭應為英文字母,以便與一律以數字指定的數字執行個體區分。這樣可以避免 |
<warmup-requests-enabled> |
選用。預設值:true。Java 應用程式預設會啟用暖機要求。
啟用暖機要求後,App Engine 基礎架構會向
如要停用暖機要求,請為這個元素指定 <warmup-requests-enabled>false</warmup-requests-enabled> |
<vpc-access> |
選用。為服務設定直連虛擬私有雲輸出,讓應用程式能向虛擬私有雲網路中的內部資源傳送要求。您無法同時指定 這個元素包含下列元素:
如要進一步瞭解如何設定直連虛擬私有雲輸出及管理執行個體限制,請參閱「使用直連虛擬私有雲輸出連線至虛擬私有雲網路」和「配額與限制」。 範例<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 存取連接器,讓應用程式將要求傳送至虛擬私有雲網路中的內部資源。在 <vpc-access-connector>
<name>projects/[PROJECT_ID]/locations/[REGION]/connectors/[CONNECTOR_NAME]</name>
</vpc-access-connector>詳情請參閱「連線至虛擬私有雲網路中的內部資源」。 |
資源調度元素
下表列出的選項是用來定義您可以指定的應用程式資源調度方式。
如要比較不同資源調度類型的成效與特色,請參閱調整動態執行個體的資源配置。
| 元素 | 說明 |
|---|---|
<automatic-scaling> |
選用。除非另行指定,否則系統預設會採用自動調整資源配置設定,預設的執行個體類別為
這個元素可包含下列元素:
<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> |
選用元素。 這個元素可包含下列元素:
<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> |
選用元素。 這個元素可包含下列元素:
<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> |
選用。大多數應用程式都不需要變更預設行為。 如有部署需求,您可以使用暫存元素指定特定暫存設定。 這個元素可包含下列元素:
例如:
<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>