Effectuer la migration vers le plug-in Gradle basé sur gcloud CLI
Restez organisé à l'aide des collections
Enregistrez et classez les contenus selon vos préférences.
Si vous avez déjà utilisé le plug-in basé sur le SDK Java App Engine (com.google.appengine.appengine-gradle) et que vous souhaitez passer au nouvel outil Google Cloud CLI, migrez vers le plug-in basé sur la CLI gcloud (com.google.cloud.tools.appengine-gradle).
Avantages du plug-in basé sur la CLI gcloud
La mise à niveau vers le nouveau plug-in offre les avantages suivants :
Le plug-in utilise les mêmes identifiants d'authentification que toutes les autres commandes basées sur gcloud CLI, qui sont générées à partir du flux gcloud auth login standard.
Il est compatible avec l'environnement flexible App Engine.
Il met automatiquement à jour le serveur de développement local lors du flux de mise à jour standard de gcloud CLI.
Il accepte le déploiement des configurations de services App Engine (Cron, files d'attente, DoS, distribution), indépendamment de votre service.
Différences notables
Avant d'effectuer la migration, veuillez prendre en compte les différences notables suivantes :
- Dépendance de gcloud CLI
- L'ancien plug-in s'exécute sans aucune dépendance spécifique à l'environnement local, hors Java, mais le nouveau plug-in nécessite l'installation de gcloud CLI.
- Aucune génération de documents de découverte Endpoints
- Le nouveau plug-in ne génère pas de documents de découverte Endpoints. Cette fonctionnalité est disponible dans un plug-in distinct. L'exécution du backend Endpoints n'exige plus de générer ce fichier lors d'une étape de compilation, car le serveur le génère désormais au moment de l'exécution. Vous ne devez utiliser le nouveau plug-in que si vous devez générer des bibliothèques clientes, comme celles pour iOS ou Android. Pour en savoir plus sur les nouveaux plug-ins, consultez le guide Migrer vers Endpoints Frameworks pour App Engine.
- Le format de fichier EAR n'est plus accepté.
- Le nouveau plug-in n'accepte plus le format de fichier EAR pour l'exécution et le déploiement de plusieurs services en même temps.
- Nouvelle commande de déploiement
- L'ancien plug-in appelle la commande
appcfg pour déployer des applications, alors que le nouveau plug-in utilise la nouvelle CLI gcloud pour les déploiements.
- L'amélioration de JPA/JDO Datanucleus doit être configurée manuellement
- Si votre projet utilise l'amélioration JPA/JDO Datanucleus de
gradle-appengine-plugin, vous devez configurer manuellement l'amélioration Datanucleus après le passage au plug-in basé sur la CLI gcloud. Consultez un exemple sur Stack Overflow.
- Android Studio n'est pas compatible
- Vous pouvez indiquer à votre projet Android Studio d'utiliser le nouveau plug-in, mais le serveur de développement et l'assistance de déploiement App Engine d'Android Studio ne fonctionnent pas avec celui-ci. Pour exécuter et déployer votre application, vous devez appeler directement Gradle.
L'utilisation des fichiers de configuration au format XML est acceptée, mais pas au format YAML.
Migrer vers le nouveau plug-in
Supprimez l'ancienne configuration gradle-appengine-plugin et les importations précédentes à partir de votre fichier build.gradle.
Ajoutez le nouveau plug-in au chemin de classe classpath de la section buildscript de votre fichier build.gradle :
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.0.1'
}
}
À la racine de votre service, exécutez la commande suivante pour vérifier que vous pouvez exécuter votre application en local :
gradle appengineRun
Dans la section buildscript du fichier build.gradle, configurez le déploiement en spécifiant l'ID de votre projet et sa version :
appengine {
deploy {
version = 'v1'
project = "your GCP project ID"
}
}
Le nouvel outil ignore les éléments d'application et de version du fichier appengine-web.xml.
À la racine de votre service, exécutez la commande suivante pour vérifier que vous pouvez déployer votre application :
gradle appengineDeploy
Migrer des configurations multiservices basées sur EAR
Le nouveau plug-in n'est pas compatible avec l'empaquetage EAR. À la place, il accepte l'exécution de plusieurs services en local sans aucune étape de création de package particulière.
Pour migrer un projet Gradle basé sur EAR, procédez comme suit :
Choisissez un service principal qui sera chargé de l'exécution du reste des services. Vous devez sélectionner le service par défaut, mais il peut s'agir de l'un des services exécutés ensemble.
Dans la configuration appengine, modifiez l'entrée run.services afin d'inclure tous les services devant être exécutés par le serveur de développement local.
Exemple de structure de projet :
../{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
Exemple de script de compilation 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
}
Comparaison entre les commandes Gradle basées sur le SDK App Engine et celles basées sur la CLI gcloud
Dans le tableau suivant, vous pouvez découvrir les différentes manières d'appeler le plug-in Gradle, selon que vous utilisez le plug-in Gradle basé sur le SDK App Engine ou le plug-in Gradle basé sur la CLI gcloud.
| Action |
Basée sur le SDK App Engine |
Basée sur gcloud CLI |
| Exécuter l'application en local |
appengine:devserver |
appengineRun |
| Déployer une nouvelle application, une nouvelle version ou un nouveau service |
appengine:update |
appengineDeploy |
| Définir la version de l'application par défaut |
appengine:set_default_version |
gcloud app services set-traffic ou gcloud app versions migrate |
| Mettre à jour les tâches Cron de l'application |
appengine:update_cron |
appengineDeployCron |
| Mettre à jour la configuration de distribution de l'application. |
appengine:update_dispatch |
appengineDeployDispatch |
| Mettre à jour la configuration de la protection DoS pour l'application |
appengine:update_dos |
appengineDeployDos |
| Mettre à jour les définitions de la file d'attente de tâches de l'application |
appengine:update_queues |
appengineDeployQueue |
| Mettre à jour les index Datastore |
appengine:update_indexes |
appengineDeployIndex |
| Supprimer les index non utilisés de l'application |
appengine:vacuum_indexes |
gcloud datastore indexes cleanup |
| Lance la version de module spécifiée. |
appengine:start_module_version |
gcloud app versions start |
| Arrêter la version de module spécifiée |
appengine:stop_module_version |
gcloud app versions stop |
| Effectuer un rollback de la mise à jour en cours d'exécution |
appengine:rollback |
gcloud app versions start, gcloud app versions stop |
Étape suivante
- Après avoir migré vers le nouveau plug-in, vous pouvez tester et déployer votre application.
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/09/04 (UTC).
[[["Facile à comprendre","easyToUnderstand","thumb-up"],["J'ai pu résoudre mon problème","solvedMyProblem","thumb-up"],["Autre","otherUp","thumb-up"]],[["Difficile à comprendre","hardToUnderstand","thumb-down"],["Informations ou exemple de code incorrects","incorrectInformationOrSampleCode","thumb-down"],["Il n'y a pas l'information/les exemples dont j'ai besoin","missingTheInformationSamplesINeed","thumb-down"],["Problème de traduction","translationIssue","thumb-down"],["Autre","otherDown","thumb-down"]],["Dernière mise à jour le 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."]]
