Migrar a la versión 2.0 de Cloud Endpoints Frameworks para App Engine

En esta página se describe cómo migrar una aplicación de Cloud Endpoints versión 1.0 a Endpoints Frameworks para App Engine en Java.

Nota: En esta página se hace referencia a Endpoints 1.0 como versión 1.0 de Endpoints Frameworks y a la nueva versión de Endpoints Frameworks para App Engine como versión 2.0 de Endpoints Frameworks.

Ventajas

El nuevo marco ofrece varias ventajas, entre las que se incluyen las siguientes:

• Se ha reducido la latencia de las solicitudes.
• Mejor integración con las funciones de App Engine, como los dominios personalizados.
• Compatibilidad oficial con las configuraciones de Guice.
• Opcionalmente, nuevas funciones de gestión de APIs.

La versión 2.0 de Endpoints Frameworks no afecta a las interfaces de tu API. Los clientes actuales seguirán funcionando después de la migración sin necesidad de cambiar el código del lado del cliente.

Funciones y herramientas excluidas actualmente

Las siguientes funciones no están disponibles en este momento. Si necesita alguna de estas funciones, envíe una solicitud de función.

• Protocolo JSON-RPC, que es obligatorio para los clientes de iOS antiguos. Para crear clientes de iOS para tu API de Endpoints Frameworks versión 2.0, te recomendamos que uses la biblioteca de cliente de APIs de Google para Objective-C para APIs REST.
• ETags automáticas
• Campos de tipo automático
• Integración en IDE
• fields respuestas parciales
• Creación automática de métodos de API PATCH

Además, Android Studio no admite la versión 1.0 de Endpoints en la versión 2.0.

Migrar a la versión 2.0 de Endpoints Frameworks

La versión 2.0 de Endpoints Frameworks se ha trasladado a los artefactos de Maven del grupo com.google.endpoints. El archivo JAR base obligatorio se encuentra en el artefacto endpoints-framework. Si quieres usar la configuración de Guice, añade el artefacto endpoints-framework-guice.

Las siguientes instrucciones muestran un ejemplo de cómo migrar de la versión 1.0 de Endpoints Frameworks a la versión 2.0 mediante un documento de descubrimiento:

Nota: Si utilizas la versión 1.0 de Endpoints Frameworks con Eclipse, primero convierte tu proyecto en un proyecto de Maven y, a continuación, sigue las instrucciones de Maven que se indican más abajo.

1. Descarga e inicializa Google Cloud CLI.
2. Ejecuta los siguientes comandos:
   1. Asegúrate de que la CLI de gcloud tenga autorización para acceder a tus datos y servicios en Google Cloud:

      gcloud auth login

   2. Usa las credenciales de aplicación predeterminadas:

      gcloud auth application-default login

   3. Instala el componente app-engine-java del SDK de Google Cloud:

      gcloud components install app-engine-java

   4. Actualiza a la versión más reciente del SDK de Google Cloud y de todos los componentes:

      gcloud components update

Migrar con Maven o Gradle

Maven

1. Elimina la dependencia antigua, que es el artefacto appengine-endpoints:
   <dependency>
         <groupId>com.google.appengine</groupId>
         <artifactId>appengine-endpoints</artifactId>
         <version>1.9.53</version>
   </dependency>

2. Añade la nueva dependencia de Endpoints Frameworks:
   <dependency>
       <groupId>com.google.endpoints</groupId>
       <artifactId>endpoints-framework</artifactId>
       <version>2.2.1</version>
   </dependency>

3. Añade el nuevo complemento Endpoints Frameworks y define el nombre de host de un documento de descubrimiento generado:
   <plugin>
       <groupId>com.google.cloud.tools</groupId>
       <artifactId>endpoints-framework-maven-plugin</artifactId>
       <version>1.0.2</version>
       <configuration>
           <!-- plugin configuration -->
           <hostname>YOUR-PROJECT-ID.appspot.com</hostname>
       </configuration>
   </plugin>

4. Añade el nuevo complemento de Maven de App Engine:
   <plugin>
       <groupId>com.google.cloud.tools</groupId>
       <artifactId>appengine-maven-plugin</artifactId>
       <version>1.3.2</version>
       <configuration>
           <!-- deploy configuration -->
       </configuration>
   </plugin>

   Nota: El antiguo complemento App Engine Maven, con el grupo com.google.appengine, no es compatible con el complemento Endpoints Frameworks. Debes usar la nueva versión.
5. Actualiza el punto de entrada de la API en el archivo web.xml de tu proyecto:
   • Cambiar todas las instancias de SystemServiceServlet por EndpointsServlet
   • Sustituye todas las instancias de la ruta /_ah/spi/ por la nueva ruta obligatoria /_ah/api/
     .

   A continuación, se muestra el contenido de web.xml antes y después de la migración:

   Antes de la migración

   Endpoints Frameworks versión 1.0 web.xml:

   <servlet>
       <servlet-name>SystemServiceServlet</servlet-name>
       <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class>
       <init-param>
           <param-name>services</param-name>
           <param-value>com.example.helloendpoints.Greetings</param-value>
       </init-param>
       <init-param>
           <param-name>restricted</param-name>
           <param-value>false</param-value>
       </init-param>
   </servlet>
   <servlet-mapping>
       <servlet-name>SystemServiceServlet</servlet-name>
       <url-pattern>/_ah/spi/*</url-pattern>
   </servlet-mapping>

   Después de la migración

   Endpoints Frameworks versión 2.0 web.xml:

   <servlet>
       <servlet-name>EndpointsServlet</servlet-name>
       <servlet-class>com.google.api.server.spi.EndpointsServlet</servlet-class>
       <init-param>
           <param-name>services</param-name>
           <param-value>com.example.helloendpoints.Greetings</param-value>
       </init-param>
       <init-param>
           <param-name>restricted</param-name>
           <param-value>false</param-value>
       </init-param>
   </servlet>
   <servlet-mapping>
       <servlet-name>EndpointsServlet</servlet-name>
       <url-pattern>/_ah/api/*</url-pattern>
   </servlet-mapping>

6. Después de modificar las dependencias, limpia el proyecto:

   mvn clean

7. Puedes generar un documento de descubrimiento:

   mvn endpoints-framework:discoveryDocs

   Consulta más información sobre los objetivos del complemento de Maven Endpoints Frameworks.
8. Puedes desplegar un proyecto:

   mvn appengine:deploy

   Más información sobre los objetivos del complemento de Maven App Engine

   Nota: Cuando migres, debes implementar una nueva versión de App Engine. Esto se hace automáticamente si no especificas una versión. Consulta los problemas conocidos.

Gradle

1. Elimina la dependencia antigua, que es el artefacto appengine-endpoints:

   compile group: 'com.google.appengine', name: 'appengine-endpoints', version: '+'

2. Añade la nueva dependencia de Endpoints Frameworks:
   compile group: 'com.google.endpoints', name: 'endpoints-framework', version: '2.0.8'

3. Añade los nuevos complementos de App Engine y Endpoints Frameworks:
   buildscript {    // Configuration for building
     repositories {
       mavenCentral()
       jcenter()    // Bintray's repository - a fast Maven Central mirror & more
     }
     dependencies {
       // App Engine Gradle plugin
       classpath 'com.google.cloud.tools:appengine-gradle-plugin:1.3.3'
   
       // Endpoints Frameworks Gradle plugin
       classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:1.0.2'
     }
   }

4. Aplica los nuevos complementos de App Engine y Endpoints Frameworks:
   apply plugin: 'com.google.cloud.tools.appengine'
   apply plugin: 'com.google.cloud.tools.endpoints-framework-server'

5. Define el endpoint del nombre de host de los documentos de descubrimiento generados:
   endpointsServer {
     // Endpoints Framework Plugin server-side configuration
     hostname = "YOUR-PROJECT-ID.appspot.com"
   }

6. Actualiza el punto de entrada de la API en el archivo web.xml de tu proyecto:
   • Cambiar todas las instancias de SystemServiceServlet por EndpointsServlet
   • Sustituye todas las instancias de la ruta /_ah/spi/ por la nueva ruta obligatoria /_ah/api/
     .

   A continuación, se muestra el contenido de web.xml antes y después de la migración:

   Antes de la migración

   Endpoints Frameworks versión 1.0 web.xml:

   <servlet>
       <servlet-name>SystemServiceServlet</servlet-name>
       <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class>
       <init-param>
           <param-name>services</param-name>
           <param-value>com.example.helloendpoints.Greetings</param-value>
       </init-param>
       <init-param>
           <param-name>restricted</param-name>
           <param-value>false</param-value>
       </init-param>
   </servlet>
   <servlet-mapping>
       <servlet-name>SystemServiceServlet</servlet-name>
       <url-pattern>/_ah/spi/*</url-pattern>
   </servlet-mapping>

   Después de la migración

   Endpoints Frameworks versión 2.0 web.xml:

   <servlet>
       <servlet-name>EndpointsServlet</servlet-name>
       <servlet-class>com.google.api.server.spi.EndpointsServlet</servlet-class>
       <init-param>
           <param-name>services</param-name>
           <param-value>com.example.helloendpoints.Greetings</param-value>
       </init-param>
       <init-param>
           <param-name>restricted</param-name>
           <param-value>false</param-value>
       </init-param>
   </servlet>
   <servlet-mapping>
       <servlet-name>EndpointsServlet</servlet-name>
       <url-pattern>/_ah/api/*</url-pattern>
   </servlet-mapping>

7. Después de modificar las dependencias, limpia el proyecto con el siguiente comando:

   gradle clean

8. Puedes generar un documento de descubrimiento de las siguientes formas:

   gradle endpointsDiscoveryDocs

   Consulta más información sobre las tareas del complemento de Gradle Endpoints Frameworks.
9. Puedes desplegar un proyecto de las siguientes formas:

   gradle appengineDeploy

   Consulta más información sobre las tareas del complemento de Gradle App Engine.

   Nota: Cuando migres, debes implementar una nueva versión de App Engine. Esto se hace automáticamente si no especificas una versión. Consulta los problemas conocidos.

Usar Guice para configurar Endpoints Frameworks para Java

Si quieres usar Guice, sigue estos pasos:

1. Añade la nueva dependencia de Guice de Endpoints Frameworks:

   Maven

   <dependency>
       <groupId>com.google.endpoints</groupId>
       <artifactId>endpoints-framework-guice</artifactId>
       <version>2.2.1</version>
   </dependency>

   Gradle

   compile 'com.google.endpoints:endpoints-framework-guice:2.0.9'

2. Declara un nuevo módulo que extienda EndpointsModule y configúralo de la siguiente manera:
   public class EchoEndpointModule extends EndpointsModule {
     @Override
     public void configureServlets() {
       super.configureServlets();
   
       bind(ServiceManagementConfigFilter.class).in(Singleton.class);
       filter("/_ah/api/*").through(ServiceManagementConfigFilter.class);
   
       Map<String, String> apiController = new HashMap<String, String>();
       apiController.put("endpoints.projectId", "YOUR-PROJECT-ID");
       apiController.put("endpoints.serviceName", "YOUR-PROJECT-ID.appspot.com");
   
       bind(GoogleAppEngineControlFilter.class).in(Singleton.class);
       filter("/_ah/api/*").through(GoogleAppEngineControlFilter.class, apiController);
   
       bind(Echo.class).toInstance(new Echo());
       configureEndpoints("/_ah/api/*", ImmutableList.of(Echo.class));
     }
   }

Verificar una nueva implementación

Para comprobar que el nuevo framework está sirviendo tráfico, sigue estos pasos:

1. Envía algunas solicitudes al nuevo despliegue.

2. En la Google Cloud consola, ve a la página Registro > Explorador de registros.

   Ir a la página Explorador de registros

3. Si las solicitudes se muestran con rutas que empiezan por /_ah/api, significa que Endpoints Frameworks versión 2.0 está sirviendo tu API. Los registros no deberían mostrar ninguna solicitud con rutas que empiecen por /_ah/spi. Estas solicitudes indican que el proxy de la versión 1.0 de Endpoints Frameworks sigue atendiendo solicitudes.

Añadir gestión de APIs de Endpoints

Endpoints Frameworks 2.0 también te permite activar funciones de gestión de APIs, como las siguientes:

• Gestión de claves de API
• Compartir APIs
• Autenticación de usuarios
• Métricas de APIs
• Registros de la API

Para empezar a usar estas funciones, consulta el artículo Añadir gestión de APIs.

Solución de problemas

En esta sección se describen los comportamientos erráticos habituales que se producen al migrar a Endpoints Frameworks 2.0 y las soluciones sugeridas.

La API devuelve errores 404, pero el Explorador de APIs sigue mostrando las APIs correctamente

Debes eliminar la configuración de la versión 1.0 de Endpoints Frameworks al migrar a la versión 2.0. Si la configuración antigua sigue presente en la configuración de la aplicación, el servicio Endpoints seguirá tratando la aplicación como una aplicación de la versión 1.0. Puede que veas solicitudes en tus registros de App Engine enviadas a /_ah/spi, lo que provocará que se envíen errores HTTP 404 al cliente.

1. Elimine las siguientes líneas de su archivo web.xml, si están presentes:

   <servlet>
       <servlet-name>SystemServiceServlet</servlet-name>
       <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class>
       <init-param>
           <param-name>services</param-name>
           <param-value>...</param-value>
       </init-param>
   </servlet>
   <servlet-mapping>
       <servlet-name>SystemServiceServlet</servlet-name>
       <url-pattern>/_ah/spi/*</url-pattern>
   </servlet-mapping>
   

2. Asegúrate de que tu archivo web.xml contenga lo siguiente:

   <servlet-mapping>
       <servlet-name>EndpointsServlet</servlet-name>
       <url-pattern>/_ah/api/*</url-pattern>
   </servlet-mapping>
   

La API genera errores de reflexión

Solo debes empaquetar el artefacto endpoints-framework en tu aplicación, no el antiguo JAR appengine-endpoints. Si implementas una aplicación con ambos archivos JAR, es posible que se produzcan errores de reflexión o errores de tipo de tiempo de ejecución, como NoClassDefFoundError, NoSuchMethodError y ClassCastException. Elimina las siguientes líneas del archivo de compilación, si las hay:

Maven

<dependency>
      <groupId>com.google.appengine</groupId>
      <artifactId>appengine-endpoints</artifactId>
      <version>1.9.53</version>
</dependency>

Gradle

compile group: 'com.google.appengine', name: 'appengine-endpoints', version: '+'

Además, si alguna de tus otras dependencias depende de versiones anteriores de Guava, esto también puede manifestarse como un método TypeToken que falta. Debes asegurarte de usar Guava v19 o el artefacto endpoints-framework-all, que oculta las dependencias.

No se compilan las fuentes de la biblioteca de cliente

Si ves un error como method does not override or implement a method from a supertype o cannot find symbol method setBatchPath(String), es probable que tu aplicación cliente dependa de una versión antigua de la biblioteca cliente de Java de Google. Debes asegurarte de que tu artefacto google-api-client sea 1.23.0 o una versión posterior.

Maven

<dependency>
    <groupId>com.google.api-client</groupId>
    <artifactId>google-api-client</artifactId>
    <version>1.23.0</version>
</dependency>

Gradle

compile group: 'com.google.api-client', name: 'google-api-client', version: '1.23.0'

Problemas con la mejora de Datanucleus de JPA o JDO

Maven

El nuevo complemento de Maven de App Engine basado en la CLI de Google Cloud no admite la mejora de Datanucleus de ningún tipo. Si tu proyecto usa la compatibilidad con la mejora de Datanucleus JDO o JPA del antiguo complemento, debes configurar el complemento de Maven de Datanucleus de terceros por separado al migrar. Consulta las siguientes secciones para obtener más información:

• Instrucciones de JDO
• Instrucciones de JPA

Gradle

Si tu proyecto usa la mejora gradle-appengine-plugin JPA/JDO Datanucleus, debes configurar manualmente la mejora Datanucleus después de cambiar al nuevo complemento de Gradle basado en la CLI de gcloud. Consulta un ejemplo de Stack Overflow.