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

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

以 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 強化功能
如果您的專案使用 gradle-appengine-plugin 的 JPA/JDO Datanucleus 強化功能,在改用以 Cloud SDK 為基礎的外掛程式之後,您必須手動設定 Datanucleus 強化功能。請參閱 Stackoverflow 中的示例
不支援 Android Studio
您可以讓 Android Studio 專案改用新外掛程式,但 Android Studio App Engine 開發伺服器和部署支援不適用於這個新外掛程式。如要執行及部署應用程式,您必須直接叫用 Gradle。

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

遷移至新外掛程式

  1. gradle-appengine-plugin 檔案中移除舊的 build.gradle 設定與匯入項目。

  2. 將新外掛程式新增至 classpath 檔案 build.gradle 區段的 buildscript 中:

    buildscript {
        repositories {
            mavenCentral()
        }
    
        dependencies {
            classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.0.1'
        }
    }
    
  3. 在服務的根目錄下,執行下列指令,確認您是否能在本機執行應用程式:

    gradle appengineRun
    
  4. build.gradle 檔案的 buildscript 區段中,指定專案 ID 與版本以設定部署:

    appengine {
        deploy {
            version = 'v1'
            project = "your GCP project ID"
        }
    }
    

    新工具會忽略 appengine-web.xml 檔案中的應用程式與版本元素。

  5. 在服務的根目錄下,執行下列指令,確認您是否能部署應用程式:

    gradle appengineDeploy
    

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

新外掛程式不支援 EAR 套件,而是支援在本機執行多項服務,而不需要執行任何特殊的套件步驟。

如何遷移以 EAR 為基礎的 Gradle 專案:

  1. 挑選將負責執行其餘服務的主要服務。建議您選取預設服務,但也可以選擇一起執行的任何服務。

  2. 在您的 appengine 設定中,修改 run.services 項目,加入應由本機開發伺服器執行的所有服務。

    示例專案結構如下:

    ../{projectRoot}/
      build.gradle
      settings.gradle (includes default-service & secondary-service)
           {your-default-service}/build.gradle {includes appengine-gradle-plugin}
              ….
           {your-default-service}/src/main/webapp/WEB-INF/appengine-web.xml
           {your-secondary-service}build.gradle {includes appengine-gradle-plugin}
              ….
           {your-secondary-service}/src/main/webapp/WEB-INF/appengine-web.xml
    

    範例 build.gradle buildscript 如下:

    appengine {
        run {
            // configure the app to point to the right service directories
            services = [
                    projectAsService(project),
                    projectAsService(":another-module")
            ]
        }
    }
    
    // helper method to obtain correct directory and set up dependencies
    def getExplodedAppDir(Project serverProject) {
        // if not 'this' module, then do some setup.
        if (serverProject != project) {
            // make sure we evaluate other modules first so we get the right value
            evaluationDependsOn(serverProject.path)
            // make sure we build "run" depends on the other modules exploding wars
            project.tasks.appengineRun.dependsOn serverProject.tasks.explodeWar
        }
        return serverProject.tasks.explodeWar.explodedAppDirectory
    }
    

以 App Engine SDK 為基礎及以 Cloud SDK 為基礎的 Gradle 指令比較

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

動作 以 App Engine SDK 為基礎 以 Cloud SDK 為基礎
在本機執行應用程式。 appengine:devserver appengineRun
部署新應用程式、版本或服務。 appengine:update appengineDeploy
設定預設應用程式版本。 appengine:set_default_version gcloud app services set-trafficgcloud app versions migrate
更新應用程式 Cron 工作。 appengine:update_cron appengineDeployCron
更新應用程式分派設定。 appengine:update_dispatch appengineDeployDispatch
更新應用程式 DoS 保護設定。 appengine:update_dos appengineDeployDos
更新應用程式工作佇列定義。 appengine:update_queues appengineDeployQueue
更新資料儲存庫索引。 appengine:update_indexes appengineDeployIndex
刪除應用程式中未使用的索引。 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

後續步驟

  • 現在您已成功遷移至新外掛程式,接下來可以測試部署應用程式。
本頁內容對您是否有任何幫助?請提供意見:

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

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