如果您之前使用过基于 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。
迁移到新插件
移除
build.gradle
文件中旧的gradle-appengine-plugin
配置和导入项。将新插件添加到
build.gradle
文件的buildscript
部分的classpath
中:buildscript { repositories { mavenCentral() } dependencies { classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.0.1' } }
在服务的根目录下,运行以下命令以验证您是否可以在本地运行应用:
gradle appengineRun
在
build.gradle
文件的buildscript
部分中,通过指定项目 ID 和版本来配置部署:appengine { deploy { version = 'v1' project = "your GCP project ID" } }
新工具会忽略
appengine-web.xml
文件中的应用和版本元素。在服务的根目录下,运行以下命令以验证您是否可以部署应用:
gradle appengineDeploy
迁移基于 EAR 的多服务配置
新插件不支持 EAR 封装。取而代之的是,它支持在本地运行多种服务,而无需执行任何特殊的封装步骤。
要迁移基于 EAR 的 Gradle 项目,请执行以下操作:
选择一种主要服务来负责运行其余服务。建议您选择默认服务,但也可以选择一起运行的其他服务。
在
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 |