Passer au plug-in Gradle basé sur le SDK Cloud

Si vous utilisez le plug-in basé sur le SDK Java App Engine (com.google.appengine.appengine-gradle) et que vous souhaitez passer au nouveau SDK Cloud, migrez vers le plug-in basé sur le SDK Cloud (com.google.cloud.tools.appengine-gradle).

Avantages du plug-in basé sur le SDK Cloud

La mise à niveau vers le nouveau plug-in offre les avantages suivants :

  • Il utilise les mêmes identifiants que toutes les autres commandes basées sur le SDK Cloud, qui sont générés à partir du flux gcloud auth login standard.

  • Il est compatible avec l'environnement flexible App Engine.

  • Il met à jour automatiquement le serveur de développement local dans le cadre du flux de mise à jour standard du SDK Cloud.

  • 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 au SDK Cloud
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 du SDK Cloud.
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, une fonctionnalité 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 se déploie à l'aide de la nouvelle CLI gcloud.
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 la configurer manuellement après être passé au plug-in basé sur le SDK Cloud. 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

  1. Supprimez l'ancienne configuration gradle-appengine-plugin et les importations à partir du fichier build.gradle.

  2. Ajoutez le nouveau plug-in au chemin de classe (classpath) de la section buildscript du fichier build.gradle :

    buildscript {
        repositories {
            mavenCentral()
        }
    
        dependencies {
            classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.0.1'
        }
    }
    
  3. À la racine de votre service, exécutez la commande suivante pour vérifier que vous pouvez exécuter votre application en local :

    gradle appengineRun
    
  4. Dans la section buildscript du fichier build.gradle, configurez le déploiement en spécifiant votre ID de projet et votre 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.

  5. À 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 :

  1. 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.

  2. 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 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
    }
    

Comparaison entre les commandes Gradle basées sur le SDK App Engine et celles basées sur le SDK Cloud

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 le SDK Cloud.

Action Basée sur le SDK App Engine Basé sur le SDK Cloud
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 cleanup-indexes
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.