Migrar al complemento de Gradle basado en la CLI de gcloud
Organiza tus páginas con colecciones
Guarda y categoriza el contenido según tus preferencias.
Si ya usaste el complemento del SDK de App Engine para Java (com.google.appengine.appengine-gradle) y deseas pasar a la nueva Google Cloud CLI, migra al complemento basado en la CLI de gcloud (com.google.cloud.tools.appengine-gradle).
Beneficios del complemento basado en la CLI de gcloud
La actualización al complemento nuevo brinda estos beneficios:
Usa las mismas credenciales de autenticación que usan todos los otros comandos basados en la CLI de gcloud, que se producen a partir del flujo gcloud auth login estándar.
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 de la CLI de gcloud.
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 de la CLI de gcloud
- El complemento anterior se ejecuta sin dependencias específicas del entorno local, además de Java, pero el nuevo requiere que instales la CLI de gcloud.
- Sin generación de documentos de descubrimiento de extremos
- El complemento nuevo no genera documentos de descubrimiento de Endpoints. 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 Migra a Endpoints Frameworks 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 la nueva CLI de gcloud .
- Las mejoras de JPA/JDO de Datanucleus se deben configurar de forma manual
- Si tu proyecto usa la mejora Datanucleus de JPA/JDO de
gradle-appengine-plugin, debes configurar manualmente la mejora de Datanucleus después de cambiar al complemento basado en la CLI de gcloud. Observa un ejemplo de 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.
Migra al complemento nuevo
Quita la configuración gradle-appengine-plugin anterior y las importaciones del archivo build.gradle.
Agrega el nuevo complemento a la classpath de la sección buildscript del archivo build.gradle:
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.0.1'
}
}
En la raíz de tu servicio, ejecuta el siguiente comando para verificar que puedas ejecutar tu aplicación de manera local:
gradle appengineRun
En la sección buildscript del archivo build.gradle, configura la implementación mediante la especificación del ID del proyecto y la versión:
appengine {
deploy {
version = 'v1'
project = "your GCP project ID"
}
}
Las herramientas nuevas ignoran los elementos de la aplicación y la versión en el archivo appengine-web.xml.
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:
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.
En tu configuración appengine, modifica la entrada run.services para incluir todos los servicios que el servidor de desarrollo local debe ejecutar.
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 buildscript build.gradle:
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
}
Comparación de los comandos basados en el SDK de App Engine y los comandos de Gradle basados en la CLI de gcloud
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 la CLI de gcloud.
| Acción |
Basado en el SDK de App Engine |
Basado en la CLI de gcloud |
| 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 |
Limpieza de índices de Datastore de gcloud |
| 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.
Salvo que se indique lo contrario, el contenido de esta página está sujeto a la licencia Atribución 4.0 de Creative Commons, y los ejemplos de código están sujetos a la licencia Apache 2.0. Para obtener más información, consulta las políticas del sitio de Google Developers. Java es una marca registrada de Oracle o sus afiliados.
Última actualización: 2025-09-04 (UTC)
[[["Fácil de comprender","easyToUnderstand","thumb-up"],["Resolvió mi problema","solvedMyProblem","thumb-up"],["Otro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Información o código de muestra incorrectos","incorrectInformationOrSampleCode","thumb-down"],["Faltan la información o los ejemplos que necesito","missingTheInformationSamplesINeed","thumb-down"],["Problema de traducción","translationIssue","thumb-down"],["Otro","otherDown","thumb-down"]],["Última actualización: 2025-09-04 (UTC)"],[[["\u003cp\u003eMigrate from the Java App Engine SDK-based plugin (\u003ccode\u003ecom.google.appengine.appengine-gradle\u003c/code\u003e) to the gcloud CLI-based plugin (\u003ccode\u003ecom.google.cloud.tools.appengine-gradle\u003c/code\u003e) for enhanced benefits, including unified authentication, flexible environment support, and automatic updates.\u003c/p\u003e\n"],["\u003cp\u003eThe new gcloud CLI-based plugin requires the gcloud CLI to be installed and no longer supports Endpoints discovery doc generation within the plugin, as it's now handled at runtime, nor does it support the EAR file format for multiple services.\u003c/p\u003e\n"],["\u003cp\u003eManual configuration of Datanucleus enhancement is necessary if your project uses JPA/JDO, and Android Studio's built-in App Engine support is incompatible, requiring direct Gradle invocation.\u003c/p\u003e\n"],["\u003cp\u003eMigrating from EAR-based multi-service configurations to the new plugin involves selecting a primary service and configuring the \u003ccode\u003erun.services\u003c/code\u003e entry in your \u003ccode\u003ebuild.gradle\u003c/code\u003e to include all services for local development, replacing EAR packaging entirely.\u003c/p\u003e\n"],["\u003cp\u003eThe gcloud CLI-based plugin uses new Gradle commands like \u003ccode\u003eappengineRun\u003c/code\u003e for local development and \u003ccode\u003eappengineDeploy\u003c/code\u003e for deployment, replacing the old SDK-based commands such as \u003ccode\u003eappengine:devserver\u003c/code\u003e and \u003ccode\u003eappengine:update\u003c/code\u003e.\u003c/p\u003e\n"]]],[],null,["# Migrating to the gcloud CLI-based Gradle plugin\n\nIf you previously used the Java App Engine SDK-based plugin\n(`com.google.appengine.appengine-gradle`) and want to move to the new\n[Google Cloud CLI](/sdk/downloads), migrate to the gcloud CLI-based\n(`com.google.cloud.tools.appengine-gradle`) plugin.\n\nBenefits of the gcloud CLI-based plugin\n---------------------------------------\n\nUpgrading to the new plugin provides the following benefits:\n\n- Uses the same authentication credentials as all other gcloud CLI\n -based commands, which are produced from the standard `gcloud auth login`\n flow.\n\n- Supports the App Engine flexible environment.\n\n- Updates the local development server automatically as part of the standard\n gcloud CLI update flow.\n\n- Supports deploying App Engine service (cron, queues, dos, dispatch)\n configurations, independently from your service.\n\nNotable differences\n-------------------\n\nBefore you migrate, be aware of these notable differences:\n\ngcloud CLI dependency\n: The old plugin runs without any specific local environment dependencies,\n besides Java, but the new plugin requires that you have the\n gcloud CLI installed.\n\nNo Endpoints discovery doc generation\n: The new plugin does not generate Endpoints discovery docs, a\n feature available in a separate plugin. Running your Endpoints\n backend no longer requires generating this file in a build step as the server\n now generates it at runtime. You should use the new plugin only if you need\n to generate client libraries such as for iOS or Android. Learn more about the\n new plugins by reviewing the [Migrating to Endpoints Frameworks for\n App Engine](/endpoints/docs/frameworks/legacy/v1/java/migrating)\n guide.\n\nEAR file format no longer supported\n: The new plugin no longer supports the\n EAR file format for running and deploying multiple services at the same time.\n\nNew deployment command\n: The old plugin calls the `appcfg` command to deploy\n applications, while the new plugin deploys using the new gcloud CLI.\n\nJPA/JDO Datanucleus enhancement must be manually configured\n: If your project\n uses the `gradle-appengine-plugin`'s JPA/JDO Datanucleus enhancement, you must\n manually configure Datanucleus enhancement after switching to the\n gcloud CLI-based plugin. See an [example from Stackoverflow](https://stackoverflow.com/questions/29279503/how-can-i-run-datanucleus-enhancer-from-gradle).\n\nAndroid Studio is not supported\n: You can switch your Android Studio project to use the new plugin, but the\n Android Studio App Engine development server and deployment support\n does not work with this new plugin. To run and deploy your app, you have to\n invoke Gradle directly.\n\nUse of XML configuration files is supported, but not YAML.\n\nMigrating to the new plugin\n---------------------------\n\n1. Remove the old `gradle-appengine-plugin` configuration and imports from your\n `build.gradle` file.\n\n2. Add the new plugin to the `classpath` of your `build.gradle` file's\n `buildscript` section:\n\n buildscript {\n repositories {\n mavenCentral()\n }\n\n dependencies {\n classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.0.1'\n }\n }\n\n3. At the root of your service, run the following command to verify that you can\n run your app locally:\n\n gradle appengineRun\n\n4. In your `build.gradle` file's `buildscript` section, configure your\n deployment by specifying your project ID and version:\n\n appengine {\n deploy {\n version = 'v1'\n project = \"your GCP project ID\"\n }\n }\n\n The new tooling ignores the application and version elements in your\n `appengine-web.xml` file.\n5. At the root of your service, run the following command to verify that you can\n deploy your application:\n\n gradle appengineDeploy\n\nMigrating EAR based multi-service configurations\n------------------------------------------------\n\nThe new plugin does not support EAR packaging. Instead, it supports running\nmultiple services locally without any special packaging steps.\n\nTo migrate your EAR-based Gradle project:\n\n1. Pick a primary service that will be responsible for running the rest of the\n services. You should select your default service, but it can be any of the\n services that are run together.\n\n2. In your `appengine` configuration, modify the `run.services` entry to include\n all the services that should be run by the local development server.\n\n An example project structure: \n\n ../{projectRoot}/\n build.gradle\n settings.gradle (includes default-service & secondary-service)\n {your-default-service}/build.gradle {includes appengine-gradle-plugin}\n ....\n {your-default-service}/src/main/webapp/WEB-INF/appengine-web.xml\n {your-secondary-service}build.gradle {includes appengine-gradle-plugin}\n ....\n {your-secondary-service}/src/main/webapp/WEB-INF/appengine-web.xml\n\n An example `build.gradle` buildscript: \n\n appengine {\n run {\n // configure the app to point to the right service directories\n services = [\n projectAsService(project),\n projectAsService(\":another-module\")\n ]\n }\n }\n\n // helper method to obtain correct directory and set up dependencies\n def getExplodedAppDir(Project serverProject) {\n // if not 'this' module, then do some setup.\n if (serverProject != project) {\n // make sure we evaluate other modules first so we get the right value\n evaluationDependsOn(serverProject.path)\n // make sure we build \"run\" depends on the other modules exploding wars\n project.tasks.appengineRun.dependsOn serverProject.tasks.explodeWar\n }\n return serverProject.tasks.explodeWar.explodedAppDirectory\n }\n\nApp Engine SDK-based vs gcloud CLI-based Gradle commands\n--------------------------------------------------------\n\nThe following table shows the different ways you invoke the Gradle plugin,\ndepending on whether you use the App Engine SDK-based Gradle plugin or\nthe [gcloud CLI-based Gradle](/appengine/docs/legacy/standard/java/using-gradle)\nplugin.\n\nWhat's next\n-----------\n\n- Now that you have migrated to the new plugin successfully, you can [test](/appengine/docs/legacy/standard/java/using-gradle#testing_gradle_app) and [deploy](/appengine/docs/legacy/standard/java/using-gradle#deploying_gradle_app) your application."]]
