Migrer vers Cloud Endpoints Frameworks version 2.0 pour App Engine

Cette page décrit la migration d'une application Cloud Endpoints version 1.0 existante vers Endpoints Frameworks pour App Engine en Java.

Remarque : Cette page fait référence à Endpoints 1.0 en tant qu'Endpoints Frameworks version 1.0, et au nouveau framework Endpoints Frameworks pour App Engine en tant qu'Endpoints Frameworks version 2.0.

Avantages

Le nouveau framework présente de nombreux avantages, par exemple :

• Latence réduite des requêtes
• Meilleure intégration aux fonctionnalités d'App Engine (telles que les domaines personnalisés)
• Compatibilité officielle avec les configurations Guice
• En option, de nouvelles fonctionnalités de gestion de l'API

Endpoints Frameworks version 2.0 n'a pas d'incidence sur les interfaces avec l'API. Les clients existants continuent de fonctionner après la migration sans aucune modification du code côté client.

Fonctionnalités et outils actuellement exclus

Les fonctionnalités suivantes ne sont pas disponibles actuellement. Si vous en avez besoin, veuillez soumettre une demande de fonctionnalité.

• Protocole JSON-RPC, requis pour les anciens clients iOS. Si vous souhaitez créer des clients iOS pour l'API Endpoints Frameworks version 2.0, nous vous recommandons d'employer la bibliothèque cliente Objective-C d'API Google pour les API REST.
• ETags automatiques
• Champs de genre automatiques
• Intégration avec l'IDE
• Réponses partielles grâce au paramètre fields
• Création automatique de méthodes API PATCH

De plus, si Android Studio est compatible avec Endpoints version 1.0, il ne l'est pas pour le moment avec la version 2.0.

Migrer vers Endpoints Frameworks version 2.0

Endpoints Frameworks version 2.0 a été transféré dans les artefacts Maven du groupe com.google.endpoints. Le fichier JAR de base requis se trouve dans l'artefact endpoints-framework. Si vous souhaitez utiliser la configuration Guice, ajoutez l'artefact endpoints-framework-guice.

Les instructions suivantes fournissent un exemple de migration d'Endpoints Frameworks version 1.0 vers Endpoints Frameworks version 2.0 à l'aide d'un document de découverte :

Remarque :Si vous utilisez Endpoints Frameworks version 1.0 avec Eclipse, commencez par convertir votre projet en projet Maven, puis suivez les instructions Maven ci-dessous.

1. Téléchargez et initialisez Google Cloud CLI.
2. Exécutez les commandes suivantes :
   1. Assurez-vous que gcloud CLI est autorisée à accéder à vos données et services sur Google Cloud:

      gcloud auth login

   2. Utilisez les identifiants par défaut de l'application :

      gcloud auth application-default login

   3. Installez le composant app-engine-java de Google Cloud SDK:

      gcloud components install app-engine-java

   4. Installez la dernière version de Google Cloud SDK et de tous ses composants:

      gcloud components update

Procéder à la migration à l'aide de Maven ou de Gradle

Maven

1. Supprimez l'ancienne dépendance, à savoir l'artefact appengine-endpoints:
   <dependency>
         <groupId>com.google.appengine</groupId>
         <artifactId>appengine-endpoints</artifactId>
         <version>1.9.53</version>
   </dependency>

2. Ajoutez la nouvelle dépendance Endpoints Frameworks:
   <dependency>
       <groupId>com.google.endpoints</groupId>
       <artifactId>endpoints-framework</artifactId>
       <version>2.2.1</version>
   </dependency>

3. Ajoutez le nouveau plug-in Endpoints Frameworks, puis définissez le nom d'hôte d'un document de découverte généré:
   <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. Ajoutez le nouveau plug-in App Engine Maven:
   <plugin>
       <groupId>com.google.cloud.tools</groupId>
       <artifactId>appengine-maven-plugin</artifactId>
       <version>1.3.2</version>
       <configuration>
           <!-- deploy configuration -->
       </configuration>
   </plugin>

   Remarque : L'ancien plug-in App Engine Maven, avec le groupe com.google.appengine, est incompatible avec le plug-in Endpoints Frameworks. Vous devez utiliser la nouvelle version.
5. Mettez à jour le point d'entrée de l'API dans le fichier web.xml de votre projet :
   • Renommez toutes les occurrences de SystemServiceServlet en EndpointsServlet.
   • Remplacez toutes les occurrences du chemin d'accès /_ah/spi/ par le nouveau chemin d'accès requis /_ah/api/
     .

   Voici le contenu du fichier web.xml avant et après la migration :

   Avant la migration

   web.xml Endpoints Frameworks version 1.0:

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

   Après la migration

   Fichier web.xml Endpoints Frameworks version 2.0:

   <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. Après avoir modifié les dépendances, nettoyez le projet :

   mvn clean

7. Vous pouvez générer un document de découverte :

   mvn endpoints-framework:discoveryDocs

   En savoir plus sur les objectifs du plug-in Maven Endpoints Frameworks
8. Vous pouvez déployer un projet :

   mvn appengine:deploy

   En savoir plus sur les objectifs du plug-in Maven App Engine

   Remarque : Lors de la migration, vous devez procéder au déploiement vers une nouvelle version d'App Engine. Si vous ne spécifiez pas de version, cette opération s'effectue automatiquement. Consultez la page Problèmes connus.

Gradle

1. Supprimez l'ancienne dépendance, à savoir l'artefact appengine-endpoints :

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

2. Ajoutez la nouvelle dépendance Endpoints Frameworks:
   compile group: 'com.google.endpoints', name: 'endpoints-framework', version: '2.0.8'

3. Ajoutez les nouveaux plug-ins App Engine et 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. Appliquez les nouveaux plug-ins App Engine et Endpoints Frameworks:
   apply plugin: 'com.google.cloud.tools.appengine'
   apply plugin: 'com.google.cloud.tools.endpoints-framework-server'

5. Définissez le point de terminaison du nom d'hôte pour les documents de découverte générés:
   endpointsServer {
     // Endpoints Framework Plugin server-side configuration
     hostname = "YOUR-PROJECT-ID.appspot.com"
   }

6. Mettez à jour le point d'entrée de l'API dans le fichier web.xml de votre projet :
   • Renommez toutes les occurrences de SystemServiceServlet en EndpointsServlet.
   • Remplacez toutes les occurrences du chemin d'accès /_ah/spi/ par le nouveau chemin d'accès requis /_ah/api/
     .

   Voici le contenu du fichier web.xml avant et après la migration :

   Avant la migration

   web.xml Endpoints Frameworks version 1.0:

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

   Après la migration

   Fichier web.xml Endpoints Frameworks version 2.0:

   <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. Après avoir modifié les dépendances, nettoyez le projet à l'aide de la commande suivante :

   gradle clean

8. Vous pouvez générer un document de découverte à l'aide de la commande suivante :

   gradle endpointsDiscoveryDocs

   En savoir plus sur les tâches du plug-in Gradle Endpoints Frameworks
9. Vous pouvez déployer un projet à l'aide de la commande suivante :

   gradle appengineDeploy

   En savoir plus sur les tâches du plug-in Gradle App Engine

   Remarque : Lors de la migration, vous devez procéder au déploiement vers une nouvelle version d'App Engine. Si vous ne spécifiez pas de version, cette opération s'effectue automatiquement. Consultez la page Problèmes connus.

Utiliser Guice pour configurer Endpoints Frameworks en Java

Si vous souhaitez faire appel à Guice :

1. Ajoutez la nouvelle dépendance Guice d'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. Déclarez un nouveau module qui étend EndpointsModule, puis configurez-le comme suit:
   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));
     }
   }

Valider un nouveau déploiement

Pour confirmer que le nouveau framework diffuse le trafic, procédez comme suit :

1. Envoyez des requêtes au nouveau déploiement.

2. Dans la console Google Cloud, accédez à la page Journalisation > Explorateur de journaux.

   Accéder à la page "Explorateur de journaux"

3. Si les requêtes sont affichées avec des chemins commençant par /_ah/api, cela signifie qu'Endpoints Frameworks version 2.0 diffuse maintenant votre API. Les journaux ne doivent afficher aucune requête dont le chemin commence par /_ah/spi. Ces requêtes indiquent que le proxy Endpoints Frameworks version 1.0 les diffuse toujours.

Ajouter la gestion des API Endpoints

Endpoints Frameworks version 2.0 vous permet également d'activer les fonctionnalités de gestion de l'API, par exemple :

• Gestion des clés API
• Partage de l'API
• Authentification des utilisateurs
• Métriques de l'API
• Journaux de l'API

Pour commencer à utiliser ces fonctionnalités, consultez la page Ajouter la gestion d'API :

Dépannage

Cette section décrit les sources d'instabilité courantes lors de la migration vers Endpoints Frameworks version 2.0, ainsi que les solutions suggérées.

L'API renvoie des erreurs 404, mais l'explorateur d'API répertorie toujours correctement les API

Vous devez supprimer l'ancienne configuration d'Endpoints Frameworks version 1.0 lors de la migration vers Endpoints Frameworks version 2.0. Si l'ancienne configuration est toujours présente dans la configuration de l'application, le service Endpoints continue à traiter l'application comme s'il s'agissait d'une application version 1.0. Il se peut que des requêtes figurant dans les journaux App Engine soient envoyées à /_ah/spi, ce qui entraîne l'envoi d'erreurs HTTP 404 au client.

1. Le cas échéant, supprimez les lignes suivantes de votre fichier 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>...</param-value>
       </init-param>
   </servlet>
   <servlet-mapping>
       <servlet-name>SystemServiceServlet</servlet-name>
       <url-pattern>/_ah/spi/*</url-pattern>
   </servlet-mapping>
   

2. Assurez-vous que votre fichier web.xml contient les éléments suivants :

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

L'API génère des erreurs de réflexion

Vous ne devez packager que l'artefact endpoints-framework dans l'application, pas l'ancien fichier JAR appengine-endpoints. Si vous déployez une application avec les deux fichiers JAR, il se peut que vous rencontriez des erreurs de réflexion ou des erreurs de typage à l'exécution, telles que NoClassDefFoundError, NoSuchMethodError et ClassCastException. Le cas échéant, supprimez les lignes suivantes du fichier de version :

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: '+'

De plus, si l'une des autres dépendances dépend d'anciennes versions de Guava, cela peut également se manifester par l'absence de la méthode TypeToken. Vous devez vous assurer que vous employez Guava v19 ou l'artefact endpoints-framework-all, qui masque les dépendances.

Les sources de la bibliothèque cliente ne sont pas compilées

Si vous voyez une erreur telle que method does not override or implement a method from a supertype ou cannot find symbol method setBatchPath(String), cela signifie que votre application cliente dépend probablement d'une ancienne version de la bibliothèque cliente Java de Google. Vous devez vous assurer que l'artefact google-api-client est de la version 1.23.0 ou d'une version supérieure.

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'

Problèmes liés à l'amélioration de JPA/JDO Datanucleus

Maven

Le nouveau plug-in Maven App Engine basé sur la Google Cloud CLI n'est compatible avec aucun type d'amélioration Datanucleus. Si votre projet bénéficie de la compatibilité avec l'amélioration JDO ou JPA Datanucleus de l'ancien plug-in, vous devez configurer le plug-in Maven Datanucleus tiers séparément lors de la migration. Pour en savoir plus, lisez les informations ci-après.

• Instructions concernant la norme JDO
• Instructions concernant la norme JPA

Gradle

Si votre projet utilise l'amélioration JPA/JDO Datanucleus de gradle-appengine-plugin, vous devez configurer celle-ci manuellement après être passé au nouveau plug-in Gradle basé sur gcloud CLI. Consultez un exemple sur Stack Overflow.