Migra al complemento de Gradle basado en el SDK de Cloud

Si usas el complemento basado en el SDK de Java de App Engine (com.google.appengine.appengine-gradle) y deseas pasar al SDK de Cloud nuevo, migra al complemento basado en el SDK de Cloud (com.google.cloud.tools.appengine-gradle).

Beneficios del complemento basado en el SDK de Cloud

La actualización al complemento nuevo brinda estos beneficios:

  • Usa las mismas credenciales de autenticación que todos los otros comandos basados en el SDK de Cloud, que se producen desde el flujo estándar gcloud auth login.

  • Es compatible con el entorno flexible de App Engine.

  • Actualiza de manera automática el servidor de desarrollo local como parte del flujo de actualización estándar del SDK de Cloud.

  • Admite la implementación de las configuraciones de servicio de App Engine (cron, colas, DoS, envío), de forma independiente de tu servicio.

Diferencias destacadas

Antes de migrar, ten en cuenta estas diferencias importantes:

Dependencia del SDK de Cloud
El complemento anterior se ejecuta sin dependencias específicas del entorno local, además de Java, pero el nuevo requiere que instales el SDK de Cloud.
Sin generación de documentos de descubrimiento de extremos
El complemento nuevo no genera documentos de descubrimiento de extremos; esta característica está disponible en un complemento distinto. La ejecución del backend de extremos ya no requiere la generación de este archivo en un paso de compilación, ya que ahora el servidor lo genera en el entorno de ejecución. Usa el complemento nuevo solo si necesitas generar bibliotecas cliente como las de iOS o Android. Si quieres obtener más información sobre los complementos nuevos, revisa la guía Migrar a marcos de trabajo de Endpoints para App Engine.
El formato de archivo EAR ya no es compatible
El complemento nuevo ya no admite el formato de archivo EAR para implementar y ejecutar varios servicios a la vez.
Comando de implementación nuevo
El complemento anterior llama al comando appcfg para implementar aplicaciones, mientras que el complemento nuevo implementa con el nuevo CLI gcloud.
Las mejoras de JPA/JDO de Datanucleus se deben configurar de forma manual
Si en el proyecto se usan las mejoras gradle-appengine-plugin de JPA/JDO de Datanucleus, tienes que configurarlas de forma manual luego de cambiar al complemento basado en el SDK de Cloud. Observa un ejemplo desde Stackoverflow.
Android Studio no es compatible
Puedes hacer que tu proyecto de Android Studio use el complemento nuevo, pero el servidor de desarrollo y la asistencia de implementación de App Engine para Android Studio no funcionan con él. Para implementar y ejecutar tu app, debes invocar a Gradle de forma directa.

Se admite el uso de los archivos de configuración XML, pero no los YAML.

Cómo migrar al complemento nuevo

  1. Quita la configuración anterior gradle-appengine-plugin y las importaciones del archivo build.gradle.

  2. Agrega el complemento nuevo a classpath de la sección buildscript de tu archivo build.gradle:

    buildscript {
        repositories {
            mavenCentral()
        }
    
        dependencies {
            classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.0.1'
        }
    }
    
  3. En la raíz de tu servicio, ejecuta el siguiente comando para verificar que puedas ejecutar tu aplicación de manera local:

    gradle appengineRun
    
  4. En la sección buildscript de tu archivo build.gradle, configura la implementación especificando tu ID del proyecto y la versión:

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

    La nueva herramienta ignora los elementos de la aplicación y la versión en tu archivo appengine-web.xml.

  5. En la raíz de tu servicio, ejecuta el siguiente comando para verificar que puedas implementar tu aplicación:

    gradle appengineDeploy
    

Cómo migrar configuraciones de varios servicios basadas en EAR

El complemento nuevo no admite paquetes de EAR. En su lugar, admite ejecutar varios servicios de forma local sin pasos de empaquetado especiales.

Para migrar tu proyecto Gradle basado en EAR:

  1. Elige un servicio principal que será responsable de ejecutar el resto de los servicios. Deberías seleccionar el servicio predeterminado, pero puede ser cualquiera de los servicios que se ejecutan en conjunto.

  2. En la configuración de appengine, modifica la entrada run.services para incluir todos los servicios que debe ejecutar el servidor de desarrollo local.

    Este es un ejemplo de la estructura del proyecto:

    ../{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
    

    Este es un ejemplo de 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
    }
    

Comandos de Gradle basados en el SDK de App Engine en comparación con los comandos basados en el SDK de Cloud

La siguiente tabla muestra las diferentes formas de invocar el complemento Gradle, según si usas el complemento Gradle basado en el SDK de App Engine o el complemento Gradle basado en el SDK de Cloud.

Acción Basado en el SDK de App Engine Basado en el SDK de Cloud
Ejecuta la app de forma local appengine:devserver appengineRun
Implementar una app, una versión o un servicio nuevo appengine:update appengineDeploy
Configurar la versión de la aplicación predeterminada appengine:set_default_version gcloud app services set-traffic o gcloud app versions migrate
Actualizar los trabajos cron de la aplicación appengine:update_cron appengineDeployCron
Actualiza la configuración de despacho de la aplicación. appengine:update_dispatch appengineDeployDispatch
Actualizar la configuración de protección contra DoS de la aplicación appengine:update_dos appengineDeployDos
Actualizar las definiciones de la lista de tareas en cola de la aplicación appengine:update_queues appengineDeployQueue
Actualizar los índices de Datastore appengine:update_indexes appengineDeployIndex
Borrar los índices sin uso de la aplicación appengine:vacuum_indexes gcloud datastore cleanup-indexes
Inicia la versión especificada del módulo. appengine:start_module_version gcloud app versions start
Finaliza la versión del módulo especificado. appengine:stop_module_version gcloud app versions stop
Revierte una actualización en curso. appengine:rollback gcloud app versions start, gcloud app versions stop

Próximos pasos

  • Ahora que migraste de forma correcta al complemento nuevo, puedes probar y, además, implementar tu aplicación.