遷移至以 Cloud SDK 為基礎的 Maven 外掛程式

如果您使用以 Java App Engine SDK 為基礎的外掛程式 (com.google.appengine.appengine-maven),想改用新的 Cloud SDK,請遷移到以 Cloud SDK 為基礎的 (com.google.cloud.tools.appengine-maven) 外掛程式。

以 Cloud SDK 為基礎的外掛程式的優點

升級至新的外掛程式可提供下列優點:

  • 使用的驗證憑證與所有其他以 Cloud SDK 為基礎的指令相同,這些憑證是從標準 gcloud auth login 流程產生的。

  • 支援 App Engine 彈性環境。

  • 在標準 Cloud SDK 更新流程中自動更新本機開發伺服器。

  • 支援部署 App Engine 服務 (Cron、佇列、DoS 保護、分派) 設定,而且不會影響到您的服務。

重要差異

在您遷移之前,請注意以下重要差異:

Cloud SDK 依附元件
除了 Java 之外,舊外掛程式會在沒有任何特定本機環境依附元件的情況下執行,但新外掛程式會要求安裝 Cloud SDK。
不會產生 Endpoints 探索文件
新外掛程式不會產生 Endpoints 探索文件,這是單獨外掛程式的一個特色。執行 Endpoints 後端不再需要在建構步驟中產生這個檔案,因為伺服器現在會在執行階段產生這個檔案。只有當您需要為 iOS 或 Android 等作業系統產生用戶端程式庫時,才應使用新外掛程式。如要進一步瞭解新外掛程式,請參閱遷移至 App Engine 適用的 Endpoints Frameworks 指南。
目前已停止支援 EAR 檔案格式
新外掛程式已不再支援 EAR 檔案格式來同時執行及部署多項服務。
新部署指令
舊外掛程式會呼叫 appcfg 指令來部署應用程式,而新外掛程式則會使用新 gcloud CLI 來部署應用程式。
目前已不再包含 JPA/JDO Datanucleus 強化工作
新外掛程式不支援任何類型的 Datanucleus 強化功能。如果您的專案使用舊外掛程式的 Datanucleus JDO 或 JPA 強化支援功能,則必須在遷移時單獨設定第三方 Datanucleus (JDO 指令JPA 指令) 及 Maven 外掛程式。

系統支援使用 YAML 設定檔,但不支援 XML。

遷移至新外掛程式

如要遷移至新外掛程式,請執行下列步驟:

  1. 將以 Cloud SDK 為基礎的外掛程式新增至您的 pom.xml 檔案。

    <build>
        <plugins>
           [...]
              <plugin>
                <groupId>com.google.cloud.tools</groupId>
                <artifactId>appengine-maven-plugin</artifactId>
                <version>2.0.0</version>
                <configuration>
                    <projectId>your-project-ID-goes-here</projectId>
                    <version>1</version>
                </configuration>
            </plugin>
           [...]
        </plugins>
    </build>
    
  2. 在外掛程式設定中指定目標 Google Cloud Platform 專案 ID 以及服務和版本。新工具會忽略 appengine-web.xml 檔案中的應用程式與版本元素。

  3. 依照以下步驟執行及部署應用程式,藉此測試您的新設定:

    1. 使用外掛程式的完整名稱來執行應用程式:

        mvn com.google.cloud.tools:appengine-maven-plugin:run
      
    2. 使用外掛程式的完整名稱來部署應用程式:

        mvn com.google.cloud.tools:appengine-maven-plugin:deploy
      

      如果您的 pom.xml 中仍然使用舊的 appengine 外掛程式,請務必為外掛程式目標叫用建立命名空間。

如果您的設定自訂程度較高,則應在新外掛程式中尋找對等的測試環境、本機執行及部署標記

確認各方面都依照預期正常運作之後,請從 pom.xml 中移除 com.google.appengine appengine-maven-plugin,並從 appengine-web.xml 檔案中移除應用程式與版本元素。

您現在可以使用縮短的標記法叫用新外掛程式的目標了:

mvn package appengine:deploy

遷移以 EAR 為基礎的多服務設定

有了新外掛程式之後,您就不用在 EAR 套件中匯總服務了,而是可以指定從任何 App Engine 服務的 appengine-maven-plugin 設定中執行的服務清單

您可以將這些服務設定為在預設服務中執行,因為所有 App Engine 專案都需要預設服務。

如何將以 EAR 為基礎的 App Engine 專案遷移至新工具:

  1. 針對 EAR 套件的 application.xml 中的每個 context-root,將服務元素新增至您的預設服務 appengine-maven-plugin 執行設定。例如:

    <plugin>
        <groupId>com.google.cloud.tools</groupId>
        <artifactId>appengine-maven-plugin</artifactId>
        <version>2.0.0</version>
        <configuration>
            <deploy.projectId>your-project-name</deploy.projectId>
            <deploy.version>your-project-version</deploy.version>
            <services>
                <!-- your default service -->
                <service>${project.build.directory}/${project.name}-${project.version}
                </service>
                <!-- for each service in your EARs application.xml -->
                <service>
                    ${project.parent.basedir}/service-name/target/service-artifact-${project.version}
                </service>
            </services>
        </configuration>
    </plugin>
    
  2. 從您的預設服務目錄中執行以下指令,確認您的新設定能夠正常運作:

    mvn package appengine:run
    
  3. 確認您的預設服務能夠在本機執行所有服務之後,請完全移除 EAR 套件。

如果專案的根目錄只包含您的服務,則可使用一個 Maven 指令來部署所有服務。您必須先將 appengine-maven-plugin 新增至父項 pom.xml 檔案,才能執行 mvn appengine:deploy 指令。

部署指令會反覆查詢專案的每個服務,找出其設定檔,然後部署每個服務。

以 App Engine SDK 為基礎及以 Cloud SDK 為基礎的 Maven 指令

下表根據您使用的是以 App Engine SDK 為基礎的 Maven 外掛程式,還是以 Cloud SDK 為基礎的 Maven 外掛程式,列出了叫用 Maven 外掛程式的不同方式。

動作 以 App Engine SDK 為基礎 以 Cloud SDK 為基礎
在本機執行應用程式 appengine:devserver appengine:run
部署新應用程式、版本或服務。 appengine:update appengine:deployappengine:deployAll
設定預設應用程式版本。 appengine:set_default_version gcloud app services set-trafficgcloud app versions migrate
更新應用程式 Cron 工作。 appengine:update_cron appengine:deployCron
更新應用程式分派設定。 appengine:update_dispatch appengine:deployDispatch
更新應用程式 DoS 保護設定。 appengine:update_dos appengine:deployDos
更新應用程式工作佇列定義。 appengine:update_queues appengine:deployQueue
更新資料儲存庫索引。 appengine:update_indexes appengine:deployIndex
從應用程式中刪除未使用的索引。 appengine:vacuum_indexes gcloud datastore cleanup-indexes
啟動指定版本。 appengine:start_module_version gcloud app versions start
停止指定版本。 appengine:stop_module_version gcloud app versions stop
復原進行中的更新。 appengine:rollback
請注意,您也可以將流量遷移回較舊版本
gcloud app versions startgcloud app versions stop,或使用 gcloud app services set-traffic) 遷移回較舊版本。
本頁內容對您是否有任何幫助?請提供意見:

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

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