存取 Java 11 以上版本的舊版套裝組合服務

本頁面說明如何在 App Engine 標準環境中，搭配最新支援的 Java 版本安裝及使用內含服務。應用程式可以透過 App Engine API JAR 存取套裝組合服務。

事前準備

安裝 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 的程式碼範例中的舊版套件服務。