Utilizzo di Apache Maven e del plug-in App Engine (basato su Google Cloud CLI)

Questa pagina spiega come gestire un progetto App Engine per la tua API Cloud Endpoints Frameworks utilizzando Apache Maven. Apache Maven è uno strumento di comprensione e gestione di progetti software in grado di creare File WAR (Web Application Archive) per il deployment in App Engine. Google fornisce un plug-in e gli archetipi Maven supportati da Maven 3.3.9 o maggiori.

Maven scarica le librerie Java dall'SDK di App Engine. Puoi utilizzare Maven per testare l'app localmente ed eseguirne il deployment in App Engine.

Prima di iniziare

  1. Utilizza la console Google Cloud per creare e configurare il tuo progetto Google Cloud:

    Vai ad App Engine

    1. Seleziona o crea un nuovo progetto Google Cloud.
    2. Se devi creare un'applicazione App Engine per il tuo progetto, segui le istruzioni per selezionare la regione in cui vuoi che si trovi l'applicazione App Engine.
  2. Scarica e installa gcloud CLI, quindi inizializza Google Cloud CLI.

    Se hai già installato Google Cloud CLI e vuoi impostarla su utilizza un ID progetto Google Cloud diverso da quello inizializzato consulta Gestione dell'interfaccia alla gcloud CLI configurazioni.

  3. Installa il componente app-engine-java della gcloud CLI: 
    gcloud components install app-engine-java

    Nota: per assicurarti di avere l'ultima versione dell' gcloud CLI per Java, esegui gcloud components update.

  4. Se non hai Java, scarica, installa e configuralo.
  5. Imposta i flag del compilatore Java in pom.xml del progetto per specificare il codice a byte Java 8: 
    <properties>
  <maven.compiler.source>1.8</maven.compiler.source>
  <maven.compiler.target>1.8</maven.compiler.target>
</properties>
  6. Devi aver installato Apache Maven 3.3.9 o versioni successive. Per determinare la tua versione Maven, esegui questo comando: 
     mvn -v
  7. Se non hai installato la versione corretta di Maven:
    1. Scarica la versione 3.3.9 o successiva di Maven dal sito web di Maven.
    2. Installa Maven sulla tua macchina locale.

      Nota: gli utenti Linux potrebbero dover scaricare Maven anziché utilizzare apt-get install.

Aggiunta del plug-in Maven di App Engine a un progetto esistente (facoltativo)

Per utilizzare il plug-in Maven di App Engine in un progetto Maven esistente, aggiungi quanto segue alla sezione plugins del file pom.xml del progetto:

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

Scegliere un'archetipo App Engine

Gli archetipi Maven consentono agli utenti di creare progetti Maven utilizzando modelli che coprono scenari comuni. App Engine sfrutta questa funzionalità di Maven per fornire alcuni utili archetipi App Engine su Maven Central. Seleziona un'archetipo App Engine appropriato per la tua app:

Tipo di applicazione Artefatto Descrizione
Framework di Endpoints per App Engine endpoints-skeleton-archetype Genera un nuovo Endpoints Frameworks vuoto per il progetto API backend App Engine pronto per le tue classi e risorse, con i file e le directory richiesti.
Framework di Endpoints per App Engine hello-endpoints-archetype Genera un progetto di framework Endpoints di partenza per l'API backend App Engine, pronto per essere creato ed eseguito.

Creazione di un nuovo progetto mediante Maven

Durante la creazione del progetto, Maven ti chiede di fornire groupId, artifactId, version e package per il progetto.

Termine Significato
groupId Uno spazio dei nomi all'interno di Maven per tenere traccia dei tuoi artefatti. Quando gli utenti utilizzano il tuo progetto nel proprio progetto Maven, questo funge da attributo della dipendenza che finiscono per specificare.
artifactId Il nome del progetto in Maven. Viene inoltre specificato dai consumer del progetto quando dipendono da te nei propri progetti Maven.
version La versione Maven iniziale con cui vuoi generare il progetto. Ti consigliamo di aggiungere il suffisso version a -SNAPSHOT perché questo fornisce assistenza nel plug-in di release Maven per le versioni in fase di sviluppo. Per ulteriori informazioni, consulta la guida di Maven all'utilizzo del plug-in di release.
package Il pacchetto Java creato durante la generazione.

Creazione di una nuova app Endpoints Frameworks

In questa sezione viene descritta la creazione di un nuovo framework di Endpoints per la versione 2.0 progetto.

hello-endpoints-archetype fornisce un esempio di utilizzo dei plug-in, tra cui il plug-in Maven per App Engine e il plug-in Maven per Endpoints Frameworks.

hello-endpoints-archetype genera un'API Greetings di esempio utilizzando Endpoints Frameworks versione 2.0. Inoltre, funge da esempio per la migrazione delle applicazioni Endpoints Frameworks 1.0 alla versione 2.0.

Il valore README.md generato con l'archetipo fornisce informazioni su in cui è avvenuta la migrazione.

Per creare un progetto di archetipo di API di backend di App Engine per Frameworks Endpoints:

  1. Cambia directory in quella in cui vuoi compilare il progetto.

  2. Esegui il seguente comando Maven:

    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:

    Dove:

    • -Dgoogle-cloud-project è impostato sull'ID progetto.
    • -Dappengine-plugin sia impostato sulla versione più recente del plug-in Maven di App Engine.
    • -Dendpoints-frameworks sia impostato sulla versione più recente del framework Endpoints per App Engine per le dipendenze Maven.
    • -Dendpoints-plugin sia impostato sulla versione più recente del plug-in Maven Endpoints Framework per App Engine.

  3. Fornisci il numero corrispondente a hello-endpoints-archetype.

  4. Seleziona la versione più recente dall'elenco visualizzato delle versioni di archetipo disponibili.

  5. Quando viene richiesto a Define value for property 'groupId', fornisci lo spazio dei nomi per la tua app; ad esempio, fornisci il valore com.example.helloendpoints.

  6. Quando viene richiesto di Define value for property 'artifactId', fornisci il progetto nome; ad esempio, fornisci il valore helloendpoints.

  7. Quando ti viene chiesto di Define value for property 'version', accetta il valore predefinito valore.

  8. Quando ti viene chiesto di Define value for property 'package', accetta il valore predefinito.

  9. Quando ti viene chiesto di confermare le tue scelte, accetta il valore predefinito inserendo Y.

  10. Attendi il completamento della generazione del progetto. quindi cambia directory nuova directory del progetto, ad esempio helloendpoints/.

  11. Compila il progetto.

    mvn clean package

  12. Attendi il completamento della compilazione del progetto. Al termine del progetto, viene visualizzato un messaggio simile al seguente:

    [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. Per eseguire il test in locale ed eseguire il deployment del progetto nell'ambiente standard di App Engine ambiente, rivedere Gestione, test e deployment di un progetto Maven.

  14. Inoltre, puoi generare librerie client Java per l'API Greeting mediante il plug-in Maven per framework di endpoint:

    mvn endpoints-framework:clientLibs

Il seguente diagramma mostra il layout di base del progetto dell'API Greetings:

Layout del progetto Maven

  • README.md contiene informazioni sull'esempio generato.
  • Greetings.java contiene una definizione di API per un'API di saluti di esempio.
  • Constants.java contiene le costanti utilizzate dall'API di esempio Greetings.
  • HelloGreeting.java contiene un contenitore per i messaggi ricevuti e inviati dall'API di esempio Greetings.
  • index.html contiene un'interfaccia utente semplice per chiamare l'API di backend Greetings.
  • base.js contiene JavaScript necessario all'UI per effettuare richieste di backend.
  • build.gradle Una volta generato, l'esempio supporta anche Gradle e altre informazioni su questa funzionalità sono disponibili in README.md.

Compilazione e creazione dell'applicazione

Per compilare un'applicazione creata con gli archetipi Maven App Engine:

  1. Passa alla directory principale del progetto, ad esempio guestbook/.

  2. Esegui Maven:

    mvn clean package

  3. Attendi il completamento della compilazione del progetto. Al termine del progetto, appare un messaggio simile al seguente:

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

Test dell'applicazione con il server di sviluppo

Durante la fase di sviluppo, puoi eseguire e testare la tua applicazione in qualsiasi momento sul server di sviluppo eseguendo il plug-in Maven per App Engine.

Per testare l'app Endpoints Frameworks per App Engine:

  1. Se non l'hai ancora fatto, crea la tua app:

    mvn clean package

  2. Esegui l'esempio in locale:

    mvn appengine:run

    Attendi l'avvio del server. Quando il server è completamente avviato con la tua applicazione in esecuzione, viene visualizzato un messaggio simile al seguente:

    [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. Utilizza il browser per andare all'indirizzo http://localhost:8080/ per accedere all'app.

  4. Spegni l'applicazione e il server di sviluppo premendo Control+C.

Specifica di una porta per i test locali

Quando esegui l'applicazione nel server di sviluppo locale, la porta predefinita è 8080. Puoi modificare questo valore predefinito modificando la voce del plug-in per appengine-maven-plugin. Ad esempio, puoi specificare porta e indirizzo nel pom.xml della directory delle applicazioni:

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

In questo esempio, <devserver.port> imposta la porta su 8181 anziché è predefinito e l'indirizzo 0.0.0.0 è specificato, il che significa che lo sviluppo il server rimane in ascolto delle richieste provenienti dalla rete locale.

Il prefisso devserver è facoltativo; puoi utilizzare <port>8181</port>.

Debug sul server di sviluppo

Per eseguire il debug di un'applicazione in esecuzione in locale, imposta jvmFlags nella configurazione del plug-in per abilitare il debug sulla JVM sottostante, ad esempio:

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

Deployment dell'applicazione

Per eseguire il deployment della tua applicazione:

mvn appengine:deploy

L'obiettivo appengine:deploy e tutti gli altri obiettivi nel plug-in Maven di App Engine hanno parametri associati che puoi utilizzare. Per un elenco completo degli obiettivi e parametri, consulta gli Obiettivi e parametri del plug-in Maven per App Engine.

Passaggi successivi