Usa Apache Maven y el complemento de App Engine (basado en Google Cloud CLI)

En esta página, se explica cómo administrar un proyecto de App Engine para tu API de Cloud Endpoints Frameworks con Apache Maven. Apache Maven es una herramienta de administración y comprensión de proyectos de software capaz de compilar archivos de tipo archivo de app web (WAR) para su implementación en App Engine. Google proporciona un complemento y arquetipos de Maven que son compatibles con Maven 3.3.9 y versiones superiores.

Maven descarga las bibliotecas Java desde el SDK de App Engine. Puedes usar Maven para probar tu aplicación de manera local y, también, implementarla en App Engine.

Antes de comenzar

  1. Usa la consola de Google Cloud para crear y configurar tu proyecto de Google Cloud:

    Ir a App Engine

    1. Selecciona o crea un proyecto de Google Cloud nuevo.
    2. Si necesitas crear una aplicación de App Engine para tu proyecto, sigue las indicaciones y selecciona la región donde quieres ubicar tu aplicación de App Engine.
  2. Descarga e instala Google Cloud CLI de gcloud y, luego, iníciala.

    Si ya tienes Google Cloud CLI instalada y deseas configurarla para que use un ID del proyecto de Google Cloud distinto del que usaste en su inicialización, consulta Administra gcloud CLI de gcloud.

  3. Instala el componente app-engine-java de la CLI de gcloud: 
    gcloud components install app-engine-java

    Nota: Ejecuta gcloud components update para asegurarte de tener la versión más reciente de gcloud CLI para Java.

  4. Si no tienes Java, debes descargarlo, instalarlo y configurarlo.
  5. Configura las marcas del compilador de Java en el pom.xml de tu proyecto para especificar el código de bytes de Java 8: 
    <properties>
  <maven.compiler.source>1.8</maven.compiler.source>
  <maven.compiler.target>1.8</maven.compiler.target>
</properties>
  6. Debes tener instalado Apache Maven 3.3.9 o una versión posterior. Para determinar tu versión de Maven, ejecuta el siguiente comando: 
     mvn -v
  7. Si no tienes instalada la versión correcta de Maven, haz lo siguiente:
    1. Descarga Maven 3.3.9 o una versión posterior desde el sitio web de Maven.
    2. Instala Maven en tu equipo local.

      Nota: Es posible que los usuarios de Linux necesiten descargar Maven en lugar de usar apt-get install.

Agrega el complemento App Engine Maven a un proyecto existente (opcional)

Para usar el complemento de Maven de App Engine en un proyecto de Maven existente, agrega lo siguiente en la sección plugins del archivo pom.xml del proyecto:

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

Elige un arquetipo de App Engine

Los arquetipos de Maven permiten a los usuarios crear proyectos de Maven con plantillas que abarcan situaciones comunes. App Engine aprovecha esta característica de Maven para proporcionar algunos arquetipos de App Engine útiles en Maven Central. Selecciona un arquetipo de App Engine adecuado para tu app:

Tipo de aplicación Artefacto Descripción
Endpoints Frameworks para App Engine endpoints-skeleton-archetype Genera un proyecto nuevo y vacío de Endpoints Frameworks para la API de backend de App Engine, listo para tus propias clases y recursos, con los archivos y directorios requeridos.
Endpoints Frameworks para App Engine hello-endpoints-archetype Genera un proyecto de inicio de marcos de trabajo de Endpoints destinado a la API de backend de App Engine, listo para compilarse y ejecutarse.

Crea un proyecto nuevo con Maven

Durante la creación del proyecto, en Maven se solicita que proporciones groupId, artifactId, version y package para el proyecto.

Término Significado
groupId Un espacio de nombres en Maven para hacer un seguimiento de tus artefactos. Cuando las personas consumen tu proyecto en su propio Proyecto Maven, tu proyecto sirve como un atributo de la dependencia que especificarán.
artifactId El nombre de tu proyecto en Maven. Los consumidores de tu proyecto también lo especifican cuando dependen de tí en sus propios proyectos de Maven.
version La versión inicial de Maven con la que deseas generar tu proyecto. Te recomendamos usar version con el sufijo -SNAPSHOT, ya que esto proporcionará compatibilidad para el complemento de actualización de Maven para las versiones en desarrollo. Para obtener más información, consulta la guía de Maven que explica cómo usar el complemento de actualización.
package El paquete de Java creado durante la generación.

Crea una aplicación nueva de marcos de trabajo de Endpoints

En esta sección, se describe cómo crear un proyecto nuevo en Endpoints Frameworks versión 2.0.

El hello-endpoints-archetype proporciona un ejemplo del uso de complementos, incluido el complemento de Maven de App Engine y el complemento de Maven de Endpoints Frameworks.

El hello-endpoints-archetype genera un ejemplo de API de saludo con Endpoints Frameworks versión 2.0. También actúa como ejemplo para migrar tus aplicaciones de Endpoints Frameworks versión 1.0 a Endpoints Frameworks versión 2.0.

El README.md que se genera con el arquetipo proporciona información sobre dónde se produjo la migración.

Si deseas crear un proyecto de arquetipo de marcos de trabajo de Endpoints para la API de backend de App Engine, haz lo siguiente:

  1. Cambia el directorio a uno donde desees compilar el proyecto.

  2. Ejecuta el siguiente comando de 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:

    Aquí:

    • -Dgoogle-cloud-project se configura en tu ID del proyecto.
    • -Dappengine-plugin se configura en la versión más reciente del complemento de Maven de App Engine.
    • -Dendpoints-frameworks se configura en la versión más reciente de las dependencias de Endpoints Frameworks para App Engine para Maven.
    • -Dendpoints-plugin se configura en la versión más reciente del complemento de Maven de Endpoints Frameworks para App Engine.

  3. Proporciona el número correspondiente a hello-endpoints-archetype.

  4. Selecciona la versión más reciente de la lista que se muestra de las versiones de arquetipos disponibles.

  5. Cuando se te solicite Define value for property 'groupId', proporciona el espacio de nombres para tu app; por ejemplo, proporciona el valor com.example.helloendpoints.

  6. Cuando se te solicite Define value for property 'artifactId', proporciona el nombre del proyecto; por ejemplo, proporciona el valor helloendpoints.

  7. Cuando debas configurar Define value for property 'version', acepta el valor predeterminado.

  8. Cuando debas configurar Define value for property 'package', acepta el valor predeterminado.

  9. Cuando se te solicite confirmar tus elecciones, ingresa Y para aceptar el valor predeterminado.

  10. Espera a que el proyecto termine de generarse y, luego, cambia de directorio al directorio del proyecto nuevo, por ejemplo, helloendpoints/.

  11. Compila el proyecto.

    mvn clean package

  12. Espera a que se compile el proyecto. Cuando el proyecto finaliza con éxito, se muestra un mensaje similar al siguiente:

    [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. Para realizar una prueba local y, luego, implementar el proyecto en el entorno estándar de App Engine, consulta Administrar, probar y, luego, implementar un proyecto de Maven.

  14. Además, puedes generar bibliotecas cliente de Java para la API de saludo con el complemento de Maven de Endpoints Frameworks:

    mvn endpoints-framework:clientLibs

En el siguiente diagrama, se muestra el diseño básico del proyecto de la API de saludo:

Diseño de proyecto de Maven

  • README.md contiene información sobre el ejemplo generado.
  • Greetings.java contiene una definición de la API para una API de saludo de ejemplo.
  • Constants.java contiene las constantes que se usan en la API de saludo de ejemplo.
  • HelloGreeting.java contiene un contenedor para los mensajes recibidos y enviados desde la API de saludo de ejemplo.
  • index.html contiene una IU simple para llamar a la API de saludo del backend.
  • base.js contiene los elementos de JavaScript necesarios para que la IU realice solicitudes de backend.
  • Una vez generado build.gradle, en el ejemplo también se muestra la compatibilidad con Gradle. Puedes obtener más información sobre esta funcionalidad en README.md.

Compila tu aplicación

Si deseas compilar una aplicación creada con los arquetipos de Maven para App Engine, haz lo siguiente:

  1. Cambia al directorio principal de tu proyecto, por ejemplo, guestbook/.

  2. Ejecuta Maven:

    mvn clean package

  3. Espera a que se compile el proyecto. Cuando el proyecto finaliza con éxito, se muestra un mensaje similar al siguiente:

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

Prueba tu aplicación con el servidor de desarrollo

Durante la fase de desarrollo, puedes ejecutar y probar tu aplicación en cualquier momento en el servidor de desarrollo ejecutando el complemento de Maven de App Engine.

Si deseas probar tu aplicación de marcos de trabajo de Endpoints para App Engine, haz lo siguiente:

  1. Compila tu aplicación si aún no lo has hecho con el siguiente comando:

    mvn clean package

  2. Ejecuta el ejemplo de manera local con:

    mvn appengine:run

    Espera a que inicie el servidor. Cuando el servidor se inicie por completo con la aplicación en ejecución, verás un mensaje similar al siguiente:

    [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. Usa tu navegador para ir a http://localhost:8080/ y acceder a tu app.

  4. Presiona Control+C para cerrar la aplicación y el servidor de desarrollo.

Especifica un puerto para pruebas locales

Cuando ejecutes tu aplicación en el servidor de desarrollo local, el puerto predeterminado es 8080. Puedes modificar la entrada del complemento para appengine-maven-plugin a fin de cambiar este valor predeterminado. Por ejemplo, puedes especificar el puerto y la dirección en el archivo pom.xml del directorio de tu aplicación de la siguiente forma:

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

En este ejemplo, <devserver.port> configura el puerto en 8181 en lugar de en el valor predeterminado, y se especifica la dirección 0.0.0.0, lo que significa que el servidor de desarrollo recibe solicitudes provenientes de la red local.

El prefijo devserver es opcional; puedes usar <port>8181</port> en su lugar.

Realizar la depuración en el servidor de desarrollo

Para depurar una aplicación que se ejecuta de manera local, configura jvmFlags en la configuración del complemento a fin de habilitar la depuración en la JVM subyacente, por ejemplo:

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

Implementar tu aplicación

Para implementar tu aplicación:

mvn appengine:deploy

El objetivo de appengine:deploy y todos los demás objetivos del complemento de Maven de App Engine tienen parámetros asociados que puedes usar. Para obtener una lista completa de objetivos y parámetros, consulta Objetivos y parámetros del complemento de App Engine para Maven (basado en el SDK de Cloud).

¿Qué sigue?