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

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. Maven vous permet de tester votre application localement et de la déployer sur App Engine.

Avant de commencer

Utilisez la console Google Cloud pour créer et configurer votre projet Google Cloud:

Accéder à App Engine
1. Sélectionnez ou créez un projet Google 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.
Téléchargez et installez la gcloud CLI, puis initialisez-Google Cloud CLI.
Si la Google Cloud CLI est déjà installée et que vous souhaitez la configurer pour utiliser un ID de projet Google Cloud différent de celui avec lequel vous l'avez initialisée, consultez la page Gérer les configurations de gcloud CLI.
Installez le composant gcloud CLI app-engine-java :
```
gcloud components install app-engine-java
```
Remarque:Pour vous assurer que vous disposez de la dernière version de gcloud CLI pour Java, exécutez gcloud components update.
Si vous n'avez pas encore Java, téléchargez, installez et configurez Java.

Définissez les indicateurs de compilation Java du fichier pom.xml de votre projet de manière à spécifier l'octet Java 8:

<properties>
  <maven.compiler.source>1.8</maven.compiler.source>
  <maven.compiler.target>1.8</maven.compiler.target>
</properties>

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
```
Si la version appropriée de Maven n'est pas installée :
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.7.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 :

Remplacez le répertoire actuel par celui dans lequel vous voulez créer le projet.
Exécutez la commande Maven suivante :
```
mvn archetype:generate -Dgoogle-cloud-project=[YOUR-PROJECT-ID] -Dappengine-plugin=2.7.0 -Dendpoints-frameworks=2.1.0 -Dendpoints-plugin=1.0.2 -Dappengine-sdk=1.9.98 -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.
Remarque :Les archétypes Endpoints Framework pour App Engine sont compatibles avec Gradle et utilisent la dernière version de chaque dépendance.
Saisissez le numéro correspondant à hello-endpoints-archetype.

Remarque :Pour créer un projet vide contenant la structure de répertoires et les fichiers requis pour vos propres classes, indiquez le numéro correspondant à endpoints-skeleton-archetype.
Sélectionnez la version la plus récente dans la liste des versions d'archétypes disponibles qui s'affiche.
Lorsque l'invite Define value for property 'groupId' s'affiche, indiquez l'espace de noms de votre application, par exemple com.example.helloendpoints.
Lorsque l'invite Define value for property 'artifactId' s'affiche, indiquez le nom du projet, par exemple helloendpoints.
Lorsque l'invite Define value for property 'version' s'affiche, acceptez la valeur par défaut.
Lorsque l'invite Define value for property 'package' s'affiche, acceptez la valeur par défaut.
Lorsque vous êtes invité à confirmer vos choix, acceptez la valeur par défaut en saisissant Y.
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/.
Créez le projet.
```
mvn clean package
```

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] ------------------------------------------------------------------------

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

Accédez au répertoire principal de votre projet, par exemple guestbook/.
Exécutez Maven :
```
mvn clean package
```
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 :

Si ce n'est pas déjà fait, créez votre application à l'aide de la commande suivante :
```
mvn clean package
```

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

Ouvrez http://localhost:8080/ dans votre navigateur pour accéder à votre application.
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.7.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

Explorez le code du plug-in App Engine Maven et signalez les problèmes sur GitHub.
Apprenez à spécifier des paramètres pour les objectifs en vous reportant à la page Objectifs et paramètres App Engine Maven.
Explorez le code du plug-in Endpoints Frameworks Maven et signalez les problèmes sur GitHub.
Apprenez à spécifier des paramètres pour les objectifs en vous reportant à la page Plug-in Cloud Endpoints Frameworks Maven.