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.

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 :

  1. Téléchargez et initialisez le SDK Cloud.
  2. Exécutez les commandes suivantes :
    1. Assurez-vous que le SDK Cloud est autorisé à 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 du SDK Cloud :
      gcloud components install app-engine-java
    4. Installez la dernière version du SDK Cloud 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>
  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

    Fichier 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

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

    Fichier 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

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 Cloud Console, accédez à la page Stackdriver Logging > Journaux (Visionneuse de journaux).

    Accéder à la page "Visionneuse 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 le SDK Cloud 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.

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 le SDK Cloud. Consultez un exemple sur Stack Overflow.