迁移到基于 gcloud CLI 的 Maven 插件

如果您之前使用过基于 Java App Engine SDK 的插件 (com.google.appengine.appengine-maven)，并且想要改为使用新的 Google Cloud CLI，请迁移到基于 gcloud CLI 的 (com.google.cloud.tools.appengine-maven) 插件。

基于 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 增强任务

新插件不支持任何类型的 Datanucleus 增强功能。如果您的项目使用旧插件中支持的 Datanucleus JDO 或 JPA 增强功能，则必须在迁移时单独配置第三方 Datanucleus（JDO 说明和 JPA 说明）Maven 插件。

支持使用 XML 配置文件，但不支持 YAML。

迁移到新插件

注意：您应该先添加新插件并验证新插件是否有效，然后再将旧插件从 pom.xml 文件中移除。

要迁移到新插件，请执行以下操作：

1. 将基于 gcloud CLI 的插件添加到您的 pom.xml 文件中。

   <build>
       <plugins>
          [...]
             <plugin>
               <groupId>com.google.cloud.tools</groupId>
               <artifactId>appengine-maven-plugin</artifactId>
               <version>2.7.0</version>
               <configuration>
                   <projectId>your-project-ID-goes-here</projectId>
                   <version>1</version>
               </configuration>
           </plugin>
          [...]
       </plugins>
   </build>
   

2. 在插件配置中指定目标 Google Cloud 项目 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 包中。 相反，如果您要在本地测试服务，则可以单独运行每项服务，或采取一些额外步骤通过一个命令来运行多项服务。当您准备好部署服务时，可以单独部署这些服务，也可以根据项目的组织方式使用单个命令部署所有服务。

如需在本地运行多项服务，请使用您要运行的服务列表更新 appengine-maven-plugin。如果您的服务共享父级 POM，则可以将此列表添加到父级 POM 中的 appengine-maven-plugin。否则，请将列表添加到默认服务的 POM 中的 appengine-maven-plugin。

要将服务列表添加到 appengine-maven-plugin，请执行以下操作：

1. 为 EAR 软件包的 application.xml 中的每个 context-root，将 service 元素添加到 appengine-maven-plugin。

   在每个 service 元素中，指定包含服务的爆炸式 WAR 的 target 子目录。

   例如：

   <plugin>
       <groupId>com.google.cloud.tools</groupId>
       <artifactId>appengine-maven-plugin</artifactId>
       <version>2.7.0</version>
       <configuration>
           <deploy.projectId>your-project-name</deploy.projectId>
           <deploy.version>your-project-version</deploy.version>
           <services>
               <!-- for each service in your EARs application.xml -->
               <service>
                   ${project.parent.basedir}/service-name/target/service-name-${project.version}
               </service>
               <service>
                   ${project.parent.basedir}/another-service/target/another-service-${project.version}
               </service>
           </services>
       </configuration>
   </plugin>
   

   如果您的目录结构如下所示：

    ~/my-ear/default-service/
    ~/my-ear/another-service/
   

   则 service 元素中的路径名称需要按以下方式呈现：

    <service>~/my-ear/default-service/target/default-service-1.0-SNAPSHOT</service>
    <service>~/my-ear/another-service/target/another-service-1.0-SNAPSHOT</service>
   

2. 通过从默认服务目录运行以下命令来确认新配置是否有效：

   mvn package appengine:run
   

3. 验证您的默认服务是否在本地运行所有服务后，请完全移除您的 EAR 包。

如果项目的根目录仅包含您的服务，您可以使用一个 mvn appengine:deploy 命令部署所有这些服务。您必须先将 appengine-maven-plugin 添加到父级 pom.xml 文件中。当您运行 mvn appengine:deploy 时，该命令会遍历每个项目的服务以查找其配置文件，然后部署每项服务。

注意：项目的根目录不得包含不能定义 App Engine 服务的其他 Maven 模块、EAR 包或 .jar 文件。部署命令会将这些文件视为服务，而且会在找不到配置文件时失败。

基于 App Engine SDK 的 Maven 命令与基于 gcloud CLI 的 Maven 命令

下表展示了调用 Maven 插件的不同方式，具体取决于您使用的是基于 App Engine SDK 的 Maven 插件还是基于 gcloud CLI 的 Maven 插件。

操作	基于 App Engine SDK	基于 gcloud CLI
在本地运行应用	appengine:devserver	appengine:run
部署新的应用、版本或服务。	appengine:update	appengine:deploy 或 appengine:deployAll
设置默认的应用版本。	appengine:set_default_version	gcloud app services set-traffic 或 gcloud 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
更新 Datastore 索引。	appengine:update_indexes	appengine:deployIndex
删除应用中未使用的索引	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 或者使用 gcloud app services set-traffic 迁移回旧版本。