遷移至以 gcloud CLI 為基礎的 Gradle 外掛程式

如果您先前使用以 Java App Engine SDK 為基礎的外掛程式 (com.google.appengine.appengine-gradle)，但想改用新的 Google Cloud CLI，請遷移到以 gcloud CLI 為基礎 (com.google.cloud.tools.appengine-gradle) 的外掛程式。

以 gcloud CLI 為基礎的外掛程式的優點

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

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

  • 支援 App Engine 彈性環境。

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

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

重要差異

在您遷移之前，請注意以下重要差異：

gcloud CLI 依附元件
除了 Java 之外，舊外掛程式會在沒有任何特定本機環境依附元件的情況下執行，但新外掛程式會要求安裝 gcloud CLI。
不會產生 Endpoints 探索文件
新外掛程式不會產生 Endpoints 探索文件，這是單獨外掛程式的一個特色。執行 Endpoints 後端不再需要在建構步驟中產生這個檔案，因為伺服器現在會在執行階段產生這個檔案。只有當您需要為 iOS 或 Android 等作業系統產生用戶端程式庫時，才應使用新外掛程式。如要進一步瞭解新外掛程式，請參閱遷移至 App Engine 適用的 Endpoints Frameworks 指南。
目前已停止支援 EAR 檔案格式
新外掛程式已不再支援 EAR 檔案格式，無法同時執行及部署多項服務。
新部署指令
舊外掛程式會呼叫 appcfg 指令來部署應用程式，而新外掛程式則會使用新 gcloud CLI 來部署應用程式。
必須手動設定 JPA/JDO Datanucleus 強化功能
如果您的專案使用 gradle-appengine-plugin 的 JPA/JDO Datanucleus 強化功能，在改用以 gcloud CLI 為基礎的外掛程式之後，您必須手動設定 Datanucleus 強化功能。請參閱 Stackoverflow 中的示例。
不支援 Android Studio
您可以讓 Android Studio 專案改用新外掛程式，但 Android Studio App Engine 開發伺服器和部署支援不適用於這個新外掛程式。如要執行及部署應用程式，您必須直接叫用 Gradle。

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

遷移至新外掛程式

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

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

    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 為基礎和以 gcloud CLI 為基礎的 Gradle 指令比較

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

動作 以 App Engine SDK 為基礎 以 gcloud CLI 為基礎
在本機執行應用程式 appengine:devserver appengineRun
部署新應用程式、版本或服務。 appengine:update appengineDeploy
設定預設應用程式版本。 appengine:set_default_version gcloud app services set-traffic 或 gcloud 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 indexes cleanup
啟動指定的模組版本。 appengine:start_module_version gcloud app versions start
停止指定的模組版本 appengine:stop_module_version gcloud app versions stop
復原進行中的更新。 appengine:rollback gcloud app versions start、gcloud app versions stop

後續步驟

  • 現在您已成功遷移至新外掛程式，接下來可以測試及部署應用程式。