Utiliser Apache Maven et le plug-in App Engine (basé sur le SDK Cloud)

Cette page explique comment gérer un projet App Engine pour votre API Cloud Endpoints Frameworks à l'aide d'Apache Maven. Apache Maven est un outil de gestion et de compréhension de projets logiciels capable de créer des fichiers WAR (Web Application Archive) à déployer dans App Engine. Google fournit un plug-in et des archétypes Maven compatibles avec Maven version 3.3.9 ou ultérieure.

Maven télécharge les bibliothèques Java à partir du SDK App Engine. Vous pouvez l'utiliser pour tester votre application localement et la déployer dans App Engine.

Avant de commencer

  1. Utilisez Google Cloud Console pour créer et configurer votre projet Cloud :

    Accéder à App Engine

    1. Sélectionnez ou créez un projet Cloud.
    2. Si vous devez créer une application App Engine pour votre projet, suivez les instructions qui s'affichent pour sélectionner la région dans laquelle vous souhaitez placer cette dernière.
  2. Téléchargez et installez le SDK Cloud , puis initialisez l'outil de ligne de commande gcloud.

    Si vous avez déjà installé l'outil de ligne de commande gcloud et que vous souhaitez qu'il utilise un ID de projet Cloud différent de celui que vous avez initialisé, consultez la section Gérer les configurations du SDK Cloud.

  3. Installez le composant app-engine-java du SDK Cloud :
    gcloud components install app-engine-java

    Remarque : Pour vérifier que vous disposez de la dernière version du SDK Cloud pour Java, exécutez gcloud components update.

  4. Si vous n'avez pas encore Java, téléchargez, installez et configurez Java.
  5. Définissez les indicateurs de compilation Java du fichier pom.xml de votre projet de manière à spécifier l'utilisation du code d'octet Java 8 :
    <properties>
      <maven.compiler.source>1.8</maven.compiler.source>
      <maven.compiler.target>1.8</maven.compiler.target>
    </properties>
  6. Apache Maven version 3.3.9 ou ultérieure doit être installé. Pour déterminer votre version de Maven, exécutez la commande suivante :
     mvn -v
  7. Si la version installée de Maven ne convient pas :
    1. Téléchargez la version 3.3.9 ou ultérieure de Maven depuis le site Web Maven.
    2. Installez Maven sur votre ordinateur local.

      Remarque : Les utilisateurs de Linux devront peut-être télécharger Maven au lieu d'utiliser la commande apt-get install.

Ajouter le plug-in App Engine Maven à un projet existant (facultatif)

Pour utiliser le plug-in App Engine Maven dans un projet Maven existant, ajoutez le code suivant à la section plugins du fichier pom.xml du projet :

<plugin>
   <groupId>com.google.cloud.tools</groupId>
   <artifactId>appengine-maven-plugin</artifactId>
   <version>2.2.0</version>
</plugin>

Choisir un archétype App Engine

Les archétypes Maven permettent aux utilisateurs de créer des projets Maven à l'aide de modèles couvrant des scénarios courants. App Engine exploite cette fonctionnalité Maven pour fournir des archétypes App Engine utiles dans le dépôt central de Maven. Sélectionnez un archétype App Engine adapté à votre application :

Type d'application Artefact Description
Endworks Frameworks pour App Engine endpoints-skeleton-archetype Génère un projet d'API Endpoints Frameworks pour App Engine vide et prêt avec vos propres classes et ressources, et avec l'ensemble des fichiers et répertoires requis.
Endworks Frameworks pour App Engine hello-endpoints-archetype Génère un projet d'API Endpoints Frameworks pour App Engine prêt à être créé et exécuté.

Créer un projet avec Maven

Lors de la création d'un projet, Maven vous invite à fournir les éléments suivants : groupId, artifactId, version et package.

Terme Signification
groupId Espace de noms au sein de Maven permettant le suivi vos artefacts. Lorsque des personnes utilisent votre projet dans leur propre projet Maven, cet espace de noms sert d'attribut de la dépendance qu'elles doivent spécifier.
artifactId Nom de votre projet au sein de Maven. Celui-ci est également spécifié par les utilisateurs de votre projet lorsque leurs propres projets Maven en dépendent.
version Version initiale de Maven à partir de laquelle vous souhaitez générer votre projet. Il est recommandé de choisir un élément version dont le suffixe est -SNAPSHOT, car cela garantit la compatibilité de votre plug-in Maven avec les versions en cours de développement. Pour plus d'informations, consultez le guide Maven sur l'utilisation de la dernière version du plug-in.
package Package Java créé lors de la génération du projet.

Créer une application Endpoints Frameworks

Cette section décrit la création d'un projet Endpoints Frameworks version 2.0.

L'archétype hello-endpoints-archetype fournit un exemple d'utilisation de plug-ins, y compris du plug-in App Engine Maven et du plug-in Endpoints Frameworks Maven.

hello-endpoints-archetype génère un exemple d'API Greetings à l'aide d'Endpoints Frameworks version 2.0. Il sert également d'exemple pour la migration de vos applications Endpoints Frameworks version 1.0 vers Endpoints Frameworks version 2.0.

Le fichier README.md généré avec l'archétype fournit des informations sur les modalités de la migration.

Pour créer un projet d'API backend Endpoints Frameworks pour App Engine en vous basant sur un archétype, procédez comme suit :

  1. Remplacez le répertoire actuel par celui dans lequel vous voulez créer le projet.

  2. Exécutez la commande Maven suivante :

    mvn archetype:generate -Dgoogle-cloud-project=[YOUR-PROJECT-ID] -Dappengine-plugin=2.2.0 -Dendpoints-frameworks=2.0.7 -Dendpoints-plugin=1.0.0 -Dappengine-sdk=1.9.81 -Dfilter=com.google.appengine.archetypes:
    

    Où :

    • -Dgoogle-cloud-project est défini sur l'ID du projet.
    • -Dappengine-plugin est défini sur la version la plus récente du plug-in App Engine Maven.
    • -Dendpoints-frameworks est défini sur la version la plus récente des dépendances Endpoints Frameworks pour App Engine Maven.
    • -Dendpoints-plugin est défini sur la version la plus récente du plug-in Endpoints Frameworks pour App Engine Maven.
  3. Saisissez le numéro correspondant à hello-endpoints-archetype.

  4. Sélectionnez la version la plus récente dans la liste des versions d'archétypes disponibles qui s'affiche.

  5. Lorsque l'invite Define value for property 'groupId' s'affiche, indiquez l'espace de noms de votre application, par exemple com.example.helloendpoints.

  6. Lorsque l'invite Define value for property 'artifactId' s'affiche, indiquez le nom du projet, par exemple helloendpoints.

  7. Lorsque l'invite Define value for property 'version' s'affiche, acceptez la valeur par défaut.

  8. Lorsque l'invite Define value for property 'package' s'affiche, acceptez la valeur par défaut.

  9. Lorsque vous êtes invité à confirmer vos choix, acceptez la valeur par défaut en saisissant Y.

  10. Attendez la fin de la génération du projet, puis remplacez les répertoires par le nouveau répertoire du projet, par exemple helloendpoints/.

  11. Créez le projet.

    mvn clean package
    
  12. Attendez que le projet se crée. Une fois la création terminée, un message semblable à celui-ci s'affiche :

    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 4.062 s
    [INFO] Finished at: 2017-02-28T00:28:03-08:00
    [INFO] Final Memory: 27M/485M
    [INFO] ------------------------------------------------------------------------
    
  13. Pour effectuer des tests en local et déployer le projet dans l'environnement standard App Engine, consultez la section Gérer, tester et déployer un projet Maven.

  14. En outre, vous pouvez générer des bibliothèques clientes Java pour l'API Greetings à l'aide du plug-in Endpoints Frameworks Maven :

    mvn endpoints-framework:clientLibs
    

Le schéma suivant illustre la structure de projet de base de l'API Greetings :

Arborescence projet de Maven

  • README.md contient des informations sur l'exemple généré.
  • Greetings.java contient une définition de l'API pour l'exemple d'API Greetings.
  • Constants.java contient les constantes utilisées par l'exemple d'API Greetings.
  • HelloGreeting.java comporte un conteneur pour les messages reçus et envoyés à partir de l'exemple d'API Greetings.
  • index.html contient une interface utilisateur simple pour appeler l'API backend Greetings.
  • base.js contient le JavaScript nécessaire à l'interface utilisateur pour effectuer des requêtes en backend.
  • build.gradle : une fois généré, l'exemple est également compatible avec Gradle. Vous trouverez davantage d'informations sur cette fonctionnalité dans le fichier README.md.

Compiler et créer une application

Pour créer une application basée sur les archétypes App Engine Maven, procédez comme suit :

  1. Accédez au répertoire principal de votre projet, par exemple guestbook/.

  2. Exécutez Maven :

    mvn clean package
    
  3. Attendez que le projet se crée. Une fois la création terminée, un message semblable à celui-ci s'affiche :

    BUILD SUCCESS
     Total time: 10.724s
     Finished at: 2016-08-04T16:18:24-07:00
     Final Memory: 24M/213M
    

Tester votre application avec un serveur de développement

À tout moment pendant la phase de développement, vous pouvez exécuter et tester votre application sur le serveur de développement en appelant le plug-in App Engine Maven.

Pour tester votre application Endpoints Frameworks pour App Engine, procédez comme suit :

  1. Si ce n'est pas déjà fait, créez votre application à l'aide de la commande suivante :

    mvn clean package
    
  2. Exécutez l'exemple localement :

    mvn appengine:run
    

    Attendez que le serveur démarre. Une fois le serveur complètement démarré et votre application en cours d'exécution, un message semblable à celui-ci s'affiche :

    [INFO] GCLOUD: INFO ### devappserver2.py:764] Skipping SDK update check.
    [INFO] GCLOUD: INFO ### api_server.py:268] Starting API server at: http://localhost:34199
    [INFO] GCLOUD: INFO ### dispatcher.py:199] Starting module "default" running at: http://localhost:8080
    [INFO] GCLOUD: INFO ### admin_server.py:116] Starting admin server at: http://localhost:8000
    [INFO] GCLOUD: ### com.google.appengine.tools.development.SystemPropertiesManager setSystemProperties
    
  3. Ouvrez http://localhost:8080/ dans votre navigateur pour accéder à votre application.

  4. Arrêtez l'application et le serveur de développement en appuyant sur Control+C.

Spécifier un port pour les tests locaux

Lorsque vous exécutez votre application sur le serveur de développement local, le port par défaut est 8080. Vous pouvez changer cette valeur par défaut en modifiant l'entrée du plug-in pour appengine-maven-plugin. Par exemple, vous pouvez spécifier le port et l'adresse comme suit dans le fichier pom.xml du répertoire de votre application :

<plugins>
   <plugin>
     <groupId>com.google.cloud.tools</groupId>
     <artifactId>appengine-maven-plugin</artifactId>
     <version>2.2.0</version>
     <configuration>
       <devserver.host>0.0.0.0</devserver.host>
       <devserver.port>8181</devserver.port>
     </configuration>
  </plugin>
</plugins>

Dans cet exemple, <devserver.port> définit le port sur 8181 au lieu du port par défaut, et l'adresse 0.0.0.0 est spécifiée, ce qui signifie que le serveur de développement écoute les requêtes issues du réseau local.

Le préfixe devserver est facultatif. Vous pouvez utiliser <port>8181</port> à la place.

Déboguer votre application sur un serveur de développement

Pour déboguer une application en cours d'exécution localement, définissez jvmFlags dans la configuration du plug-in de manière à activer le débogage sur la JVM sous-jacente, par exemple :

<configuration>
  <jvmFlags>
    <jvmFlag>-Xdebug</jvmFlag>
    <jvmFlag>-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005</jvmFlag>
  </jvmFlags>
</configuration>

Déployer l'application

Pour déployer votre application, procédez comme suit :

mvn appengine:deploy

L'objectif appengine:deploy et tous les autres objectifs du plug-in App Engine Maven sont associés à des paramètres que vous pouvez utiliser. Pour obtenir la liste complète des objectifs et des paramètres, consultez la page Objectifs et paramètres du plug-in App Engine Maven.

Étapes suivantes