迁移到基于 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 的 Gradle 命令与基于 gcloud CLI 的 Gradle 命令

下表展示了调用基于 App Engine SDK 的 Gradle 插件或基于 gcloud CLI 的 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
更新 Datastore 索引。	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

后续步骤

• 现在，您已成功迁移到新插件。接下来，您可以测试和部署您的应用。