本頁面說明如何在 App Engine 標準環境中,搭配最新支援的 Java 版本安裝及使用內含服務。應用程式可以透過 App Engine API JAR 存取套裝組合服務。
事前準備
請參閱舊版服務套裝組合 API 清單,瞭解您可以在最新支援的 Java 版本中呼叫哪些 API。
本頁面要求您的應用程式執行支援的 Java 版本。如要將應用程式從第一代遷移至第二代執行階段,請參閱「從 Java 8 遷移至最新的 Java 執行階段」和「遷移考量事項」一節。
如果您使用舊版套裝服務,且想要升級至 Java 21,請參閱「升級現有應用程式」,進一步瞭解設定選項。
安裝 App Engine API JAR
如要在最新支援的 Java 應用程式中使用舊版內含服務,您必須使用 appengine-web.xml
檔案設定應用程式 (而非 app.yaml
檔案)。
以下範例說明如何在 appengine-web.xml
中新增設定,適用於 EE10 上的 21 以上版本 (預設)、EE8 上的 21 以上版本,以及 17 以下版本。如要在預設設定中使用最新支援的版本,您必須更新應用程式 servlet 和依附元件,以便納入 Jakarta
命名空間。如要進一步瞭解設定選項,請參閱「升級現有應用程式」。
請根據 Java 版本在 appengine-web.xml
檔案中新增下列設定:
v21 以上版本 (EE10)
<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
<runtime>java21</runtime> <!-- or another supported version -->
<app-engine-apis>true</app-engine-apis>
</appengine-web-app>
v21 (EE8)
<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
<runtime>java21</runtime>
<system-properties> <!-- run your apps on EE8 -->
<property name="appengine.use.EE8" value="true"/>
</system-properties>
<app-engine-apis>true</app-engine-apis>
</appengine-web-app>
v17 以下
<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
<runtime>java17</runtime> <!-- or another supported version -->
<app-engine-apis>true</app-engine-apis>
</appengine-web-app>
如要將舊版內含服務指定為依附元件,請在 pom.xml
檔案中新增以下行:
<dependency>
<groupId>com.google.appengine</groupId>
<artifactId>appengine-api-1.0-sdk</artifactId>
<version>2.0.31</version> <!-- or later-->
</dependency>
如果應用程式使用 web.xml
檔案,您必須新增 <app-engine-apis>
元素,並將其設為 true
:
<app-engine-apis>true</app-engine-apis>
如要部署 Java 21 應用程式,請在已編譯及階段化的網頁應用程式上執行 mvn appengine:deploy
指令,或 gcloud app deploy ~/my_app/WEB-INF/appengine-web.xml
指令。
Java 21 使用的預設進入點
啟動用於網頁應用程式的 JVM 時,Java 21 應用程式可從額外的使用者設定中受益。
用來啟動 JVM 的預設進入點是由 App Engine 建構包產生的。基本上,這等同於在 appengine-web.xml
檔案中定義這個進入點。例如:
java --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio.charset=ALL-UNNAMED -showversion -Xms32M -Xmx204M -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:+PrintCommandLineFlags -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
我們不建議變更這個預設進入點,因為記憶體設定會根據執行個體類型 (F1、F2、F4) 和可用記憶體計算。
根據預設,我們會使用 --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio.charset=ALL-UNNAMED
開啟一些必要的 JDK API。
進入點功能
第二代 Java 版本的進入點可透過使用者定義的環境變數進行自訂,這些變數會在 appengine-web.xml
設定檔中新增。
下表列出可用於啟用/停用/設定功能的環境變數,以及未設定的預設值:
環境變數 | 說明 | 類型 | 預設 |
---|---|---|---|
CPROF_ENABLE |
Stackdriver Profiler | 布林值 | false |
GAE_MEMORY_MB |
可用的記憶體 | 大小 | 由 App Engine 設定或為 /proc/meminfo -400M |
HEAP_SIZE_RATIO |
堆積的記憶體 | 百分比 | 80 |
HEAP_SIZE_MB |
可用的堆積 | 大小 | ${GAE_MEMORY_MB} 的 ${HEAP_SIZE_RATIO} % |
JAVA_HEAP_OPTS |
JVM heap 引數 | JVM 引數 | -Xms${HEAP_SIZE_MB}M -Xmx${HEAP_SIZE_MB}M |
JAVA_GC_OPTS |
JVM GC 引數 | JVM 引數 | -XX:+UseG1GC plus 設定 |
JAVA_USER_OPTS |
JVM 其他引數 | JVM 引數 | |
JAVA_OPTS |
JVM 引數 | JVM 引數 | 詳情請見下方 |
如果未明確設定,JAVA_OPTS
的預設值為:
JAVA_OPTS:=-showversion \
$JAVA_HEAP_OPTS \
$JAVA_GC_OPTS \
$JAVA_USER_OPTS
當 CPROF_ENABLE
為 true 時,預設的進入點會將 PROFILER_AGENT
新增為:
-agentpath:/opt/cprof/profiler_java_agent.so=--logtostderr
舉例來說,如果應用程式程式碼需要更多 -add-opens
旗標,您可以使用 appengine-web.xml
檔案中定義的 JAVA_USER_OPTS
環境變數:
<env-variables>
<env-var name="JAVA_USER_OPTS" value="--add-opens java.base/java.util=ALL-UNNAMED" />
</env-variables>
遷移注意事項
如果您要遷移至第二代 Java 執行階段,且應用程式使用舊版的內含服務,請注意下列事項:
- 如要測試第二代 Java 應用程式中的舊版套裝服務功能,您可以使用本機開發伺服器。
- 與 Java 8 執行階段不同,第二代 Java 執行階段會將 JVM 納入執行個體記憶體的一部分。如果記錄檔中顯示記憶體相關錯誤,請考慮在
appengine-web.xml
檔案中增加執行個體類別大小。 - 如果應用程式嘗試呼叫的 API 未針對第二代 Java 執行階段啟用,就會收到
com.google.apphosting.api.ApiProxy$FeatureNotEnabledException
錯誤。 - 系統會假設所有應用程式在第二代 Java 執行階段中具備執行緒安全性。從 Java 8 遷移至最新的 Java 執行階段時,您必須移除
app.yaml
或appengine-web.xml
檔案中的threadsafe
元素。
範例 (資料儲存庫)
如需在 Datastore 模式 (Datastore) 中使用 Firestore 的範例,請參閱 Java 11 的程式碼範例中的舊版套件服務。