Migra a Cloud Endpoints Frameworks versión 2.0 para App Engine

En esta página, se describe cómo migrar una aplicación existente 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 Endpoints Frameworks versión 1.0 y al nuevo Endpoints Frameworks para App Engine como Endpoints Frameworks versión 2.0.

Beneficios

El nuevo marco de trabajo cuenta con una serie de beneficios, incluidos los siguientes:

• Latencia de solicitud reducida
• Mejor integración con las características de App Engine, como los dominios personalizados
• Asistencia oficial para configuraciones de Guice.
• De forma opcional, nuevas características de administración de API

Endpoints Frameworks versión 2.0 no afecta las interfaces hacia tu API. Los clientes existentes continúan trabajando después de la migración sin ningún cambio en el código del lado del cliente.

Funciones y herramientas excluidas actualmente

Las siguientes funciones no están disponibles por el momento. Si necesitas alguna de ellas, envía una solicitud de función.

• Protocolo JSON-RPC, que se requiere para los clientes iOS heredados. Si deseas crear clientes iOS para tu API de Endpoints Frameworks versión 2.0, te recomendamos que uses la Biblioteca cliente Objective-C de la API de Google para las API de REST.
• ETags automáticos
• Campos de tipo automáticos
• Integración con IDE
• Respuestas parciales de fields
• Creación automática del método PATCH API

Además, la asistencia de Android Studio para Endpoints versión 1.0 actualmente no es compatible con la versión 2.0.

Migrar a Endpoints Frameworks versión 2.0

Endpoints Frameworks versión 2.0 ha pasado a los artefactos Maven en el grupo com.google.endpoints. El JAR base requerido está en el artefacto endpoints-framework. Si deseas usar la configuración de Guice, agrega el artefacto endpoints-framework-guice.

En las siguientes instrucciones, se proporciona un ejemplo de cómo migrar de la versión 1.0 de Endpoints Frameworks a la versión 2.0 de Endpoints Frameworks mediante un Documento de descubrimiento:

Nota: Si usas Endpoints Frameworks versión 1.0 con Eclipse, primero convierte tu proyecto en un proyecto Maven y, luego, sigue las instrucciones de Maven que se detallan a continuación.

1. Descarga e inicializa Google Cloud CLI.
2. Ejecuta los siguientes comandos:
   1. Asegúrate de que gcloud CLI esté autorizada para acceder a tus datos y servicios en Google Cloud:

      gcloud auth login

   2. Usa las credenciales predeterminadas de la aplicación:

      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

Migra con Maven o Gradle

Maven

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

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

3. Agrega el nuevo complemento de Endpoints Frameworks y define el nombre de host para 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. Agrega 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 complemento antiguo de App Engine Maven, con el grupo com.google.appengine, no es compatible con el complemento de 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:
   • Cambia el nombre de todos los casos de SystemServiceServlet a EndpointsServlet
   • Reemplaza todos los casos de la ruta de acceso /_ah/spi/por la nueva ruta de acceso obligatoria /_ah/api/
     

   El siguiente es 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 con el siguiente comando:

   mvn clean

7. Puedes generar un documento de descubrimiento con lo siguiente:

   mvn endpoints-framework:discoveryDocs

   Obtén más información sobre los objetivos de los complementos de Maven Endpoints Frameworks.
8. Puedes implementar un proyecto con lo siguiente:

   mvn appengine:deploy

   Obtén más información sobre los objetivos de los complementos de Maven App Engine.

   Nota: Durante la migración, debes implementar a una nueva versión de App Engine. Esto se hace de forma automática si no especificas una versión. Consulta Problemas conocidos.

Gradle

1. Quita la dependencia heredada, que es el artefacto appengine-endpoints, con el siguiente comando:

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

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

3. Agrega 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 extremo del nombre de host para 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:
   • Cambia el nombre de todos los casos de SystemServiceServlet a EndpointsServlet
   • Reemplaza todos los casos de la ruta de acceso /_ah/spi/por la nueva ruta de acceso obligatoria /_ah/api/
     

   El siguiente es 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 lo siguiente:

   gradle clean

8. Puedes generar un documento de descubrimiento mediante lo siguiente:

   gradle endpointsDiscoveryDocs

   Obtén más información sobre las tareas del complemento de Gradle Endpoints Frameworks.
9. Para implementar un proyecto, puedes usar lo siguiente:

   gradle appengineDeploy

   Obtén más información acerca de las tareas del complemento de Gradle App Engine.

   Nota: Durante la migración, debes implementar a una nueva versión de App Engine. Esto se hace de forma automática si no especificas una versión. Consulta Problemas conocidos.

Usa Guice a fin de configurar Endpoints Frameworks para Java

Si deseas usar Guice, haz lo siguiente:

1. Agrega la nueva dependencia de Endpoints Frameworks Guice:

   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));
     }
   }

Verifica una nueva implementación

Puedes verificar si el nuevo marco de trabajo esté entregando tráfico:

1. Envía algunas solicitudes a la implementación nueva.

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

   Ir a la página Explorador de registros

3. Si se muestran solicitudes con rutas que comienzan con /_ah/api, Endpoints Frameworks versión 2.0 está entregando a tu API. Los registros no deben mostrar ninguna solicitud con rutas que comiencen con /_ah/spi. Estas solicitudes indican que Endpoints Frameworks versión 1.0 todavía entrega solicitudes.

Agrega la administración de API para Endpoints

Con Endpoints Frameworks versión 2.0, también puedes activar las funciones de administración de API, incluidas las siguientes:

• Administración de claves de API
• Uso compartido de API
• Autenticación de usuarios
• Métricas de API
• Registros de API

Para comenzar a usar estas funciones, consulta Agrega administración de API.

Solución de problemas

En esta sección, se describen comportamientos erráticos comunes en la migración a Endpoints Frameworks versión 2.0 y las soluciones sugeridas.

La API muestra errores 404, pero el Explorador de API aún enumera las API correctamente

Debes quitar la configuración antigua de Endpoints Frameworks versión 1.0 cuando migres a Endpoints Frameworks versión 2.0. Si la configuración antigua todavía está presente en la configuración de la aplicación, en el servicio de Endpoints se continúa tratando la aplicación como una aplicación de la versión 1.0. Es posible que veas solicitudes en tus registros de App Engine enviados a /_ah/spi, lo que da como resultado el envío de errores HTTP 404 al cliente.

1. Quita las siguientes líneas de tu 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

Debes empaquetar solo el artefacto endpoints-framework en tu aplicación, no el JAR appengine-endpoints antiguo. Si implementas una aplicación con ambos JAR, puede que encuentres errores de reflexión o errores de tipo entorno de ejecución, como NoClassDefFoundError, NoSuchMethodError y ClassCastException. Quita las siguientes líneas de tu archivo de compilación, si están presentes:

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 cualquiera de tus otras dependencias depende de versiones antiguas de Guava, también se puede manifestar como un método TypeToken faltante. Debes asegurarte de usar Guava v19 o el artefacto endpoints-framework-all, que cubre las dependencias.

Las fuentes de la biblioteca cliente no se compilan

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

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 las mejoras de JPA/JDO Datanucleus

Maven

El nuevo complemento de Maven para App Engine basado en Google Cloud CLI no es compatible con mejoras de Datanucleus de ningún tipo. Si tu proyecto usa la asistencia de mejoras de Datanucleus JDO o JPA del complemento antiguo, debes configurar el complemento de terceros de Datanucleus Maven de forma separada cuando hagas la migración. Consulta los siguientes vínculos para obtener más información:

• Instrucciones de JDO
• Instrucciones de JPA

Gradle

Si en tu proyecto se usan las mejoras gradle-appengine-plugin de JPA/JDO de Datanucleus, tienes que configurarlas de forma manual después de cambiar al complemento nuevo de Gradle basado en gcloud CLI. Observa un ejemplo de Stackoverflow.