Migrazione alla versione 2.0 di Cloud Endpoints Frameworks per App Engine

Questa pagina descrive la migrazione di un'applicazione Cloud Endpoints 1.0 esistente a Endpoints Frameworks per App Engine in Java.

Vantaggi

Il nuovo framework offre una serie di vantaggi, tra cui:

  • Latenza delle richieste ridotta.
  • Migliore integrazione con le funzionalità di App Engine, come i domini personalizzati.
  • Supporto ufficiale per le configurazioni di Guice.
  • Se vuoi, nuove funzionalità di gestione delle API.

La versione 2.0 di Endpoints Frameworks non influisce sulle interfacce della tua API. I client esistenti continuano a funzionare dopo la migrazione senza alcuna modifica al codice lato client.

Funzionalità e strumenti attualmente esclusi

Le seguenti funzionalità non sono al momento disponibili. Se hai bisogno di una di queste funzionalità, invia una richiesta di funzionalità.

  • Protocollo JSON-RPC, obbligatorio per i client iOS precedenti. Per creare client iOS per l'API Endpoints Frameworks versione 2.0, ti consigliamo di utilizzare la libreria client Objective-C per le API di Google per le API REST.
  • ETag automatici
  • Campi tipo automatici
  • Integrazione con l'ambiente IDE
  • fields risposte parziali
  • Creazione automatica del metodo dell'API PATCH

Inoltre, il supporto di Android Studio per la versione 1.0 di Endpoints non è attualmente supportato per la versione 2.0.

Migrazione alla versione 2.0 di Endpoints Frameworks

La versione 2.0 di Endpoints Frameworks è stata spostata negli elementi Maven del gruppo com.google.endpoints. Il JAR di base richiesto si trova nell'artefatto endpoints-framework. Se vuoi utilizzare la configurazione Guice, aggiungi l'artifact endpoints-framework-guice.

Le istruzioni riportate di seguito forniscono un esempio di come eseguire la migrazione da Endpoints Frameworks 1.0 a Endpoints Frameworks 2.0 utilizzando un documento di rilevamento:

  1. Scarica e inizializza Google Cloud CLI.
  2. Esegui i seguenti comandi:
    1. Assicurati che gcloud CLI sia autorizzata ad accedere ai tuoi dati e servizi su Google Cloud: 
      gcloud auth login
    2. Utilizza le credenziali predefinite dell'applicazione: 
      gcloud auth application-default login
    3. Installa il componente app-engine-java di Google Cloud SDK: 
      gcloud components install app-engine-java
    4. Esegui l'aggiornamento alla versione più recente di Google Cloud SDK e di tutti i componenti: 
      gcloud components update

Esegui la migrazione utilizzando Maven o Gradle

Maven

  1. Rimuovi la dipendenza precedente, ovvero l'elemento appengine-endpoints: 
    <dependency>
      <groupId>com.google.appengine</groupId>
      <artifactId>appengine-endpoints</artifactId>
      <version>1.9.53</version>
</dependency>
  2. Aggiungi la nuova dipendenza Endpoints Frameworks: 
    <dependency>
    <groupId>com.google.endpoints</groupId>
    <artifactId>endpoints-framework</artifactId>
    <version>2.2.1</version>
</dependency>
  3. Aggiungi il nuovo plug-in Endpoints Frameworks e definisci il nome host per un documento di discovery generato: 
    <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. Aggiungi il nuovo plug-in Maven App Engine: 
    <plugin>
    <groupId>com.google.cloud.tools</groupId>
    <artifactId>appengine-maven-plugin</artifactId>
    <version>1.3.2</version>
    <configuration>
        <!-- deploy configuration -->
    </configuration>
</plugin>
  5. Aggiorna il punto di contatto dell'API nel file web.xml del progetto:
    • Rinomina tutte le occorrenze di SystemServiceServlet in EndpointsServlet
    • Sostituisci tutte le occorrenze del percorso /_ah/spi/ con il nuovo percorso richiesto /_ah/api/

    Di seguito sono riportati i contenuti di web.xml prima e dopo la migrazione:

    Prima della migrazione

    Endpoints Frameworks versione 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>

    Dopo la migrazione

    Endpoints Frameworks versione 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. Dopo aver modificato le dipendenze, esegui la pulizia del progetto: 
    mvn clean
  7. Puoi generare un documento di rilevamento: 
    mvn endpoints-framework:discoveryDocs
     Scopri di più sugli obiettivi dei plug-in dei framework Maven Endpoints.
  8. Puoi eseguire il deployment di un progetto: 
    mvn appengine:deploy

    Scopri di più sugli obiettivi del plug-in Maven App Engine.

Gradle

  1. Rimuovi la dipendenza precedente, ovvero l'elemento appengine-endpoints: 
    compile group: 'com.google.appengine', name: 'appengine-endpoints', version: '+'
  2. Aggiungi la nuova dipendenza Endpoints Frameworks: 
    compile group: 'com.google.endpoints', name: 'endpoints-framework', version: '2.0.8'
  3. Aggiungi i nuovi plug-in App Engine ed 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. Applica i nuovi plug-in App Engine e Endpoints Frameworks: 
    apply plugin: 'com.google.cloud.tools.appengine'
apply plugin: 'com.google.cloud.tools.endpoints-framework-server'
  5. Definisci l'endpoint del nome host per i documenti di rilevamento generati: 
    endpointsServer {
  // Endpoints Framework Plugin server-side configuration
  hostname = "YOUR-PROJECT-ID.appspot.com"
}
  6. Aggiorna il punto di contatto dell'API nel file web.xml del progetto:
    • Rinomina tutte le occorrenze di SystemServiceServlet in EndpointsServlet
    • Sostituisci tutte le occorrenze del percorso /_ah/spi/ con il nuovo percorso richiesto /_ah/api/

    Di seguito sono riportati i contenuti di web.xml prima e dopo la migrazione:

    Prima della migrazione

    Endpoints Frameworks versione 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>

    Dopo la migrazione

    Endpoints Frameworks versione 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. Dopo aver modificato le dipendenze, ripulisci il progetto utilizzando: 
    gradle clean
  8. Puoi generare un documento di rilevamento utilizzando: 
    gradle endpointsDiscoveryDocs
     Scopri di più sui framework di endpoint di Gradle Attività del plug-in
  9. Puoi eseguire il deployment di un progetto utilizzando: 
    gradle appengineDeploy

    Scopri di più sulle attività del plug-in Gradle App Engine.

Utilizzo di Guice per configurare Endpoints Frameworks per Java

Se vuoi utilizzare Guice:

  1. Aggiungi la nuova dipendenza Guice di 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. Dichiara un nuovo modulo che espande EndpointsModule e configuralo come segue: 
    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 di un nuovo deployment

Puoi verificare che il nuovo framework gestisca il traffico:

  1. Invia alcune richieste al nuovo deployment.

  2. Nella console Google Cloud, vai alla pagina Logging > Esplora log.

    Vai alla pagina Esplora log

  3. Se le richieste vengono mostrate con percorsi che iniziano con /_ah/api, significa che la tua API è ora pubblicata da Endpoints Frameworks 2.0. I log non devono mostrare richieste con percorsi che iniziano con /_ah/spi. Queste richieste indicano che il proxy di Endpoints Frameworks 1.0 sta ancora gestendo le richieste.

Aggiunta della gestione dell'API Endpoints

La versione 2.0 di Endpoints Frameworks ti consente anche di attivare le funzionalità di gestione delle API, tra cui:

  • Gestione delle chiavi API
  • Condivisione API
  • Autenticazione degli utenti
  • Metriche delle API
  • Log API

Per iniziare a utilizzare queste funzionalità, consulta Aggiunta della gestione API.

Risoluzione dei problemi

Questa sezione descrive i comportamenti erratici comuni durante la migrazione alla versione 2.0 di Endpoints Frameworks e le soluzioni suggerite.

L'API restituisce errori 404, ma Explorer API le elenca comunque correttamente

Devi rimuovere la configurazione della vecchia versione 1.0 di Endpoints Frameworks durante la migrazione alla versione 2.0 di Endpoints Frameworks. Se la vecchia configurazione è ancora presente nella configurazione dell'applicazione, il servizio Endpoints continua a trattare l'app come un'app della versione 1.0. Nei log di App Engine potresti visualizzare richieste inviate a /_ah/spi, che generano errori HTTP 404 inviati al client.

  1. Se presenti, rimuovi le seguenti righe dal file 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. Assicurati che il file web.xml contenga quanto segue:

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

L'API genera errori di riflessione

Devi pacchettizzare solo l'elemento endpoints-framework nell'applicazione, non il vecchio JAR appengine-endpoints. Se esegui il deployment di un'applicazione con entrambi i file JAR, potresti riscontrare errori di riflessione o errori di tipo di runtime, ad esempio NoClassDefFoundError, NoSuchMethodError e ClassCastException. Se presenti, rimuovi le seguenti righe dal file di compilazione:

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

Inoltre, se una delle altre dipendenze dipende da versioni precedenti di Guava, questo può anche manifestarsi come un metodo TypeToken mancante. Devi assicurarti di utilizzare Guava 19 o l'artefatto endpoints-framework-all, che oscura le dipendenze.

I file sorgente della libreria client non vengono compilati

Se visualizzi un errore come method does not override or implement a method from a supertype o cannot find symbol method setBatchPath(String), è probabile che la tua applicazione client dipenda da una versione precedente della libreria client Google Java. Devi assicurarti che l'elemento google-api-client sia 1.23.0 o superiore.

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'

Problemi con il miglioramento di Datanucleus JPA/JDO

Maven

Il nuovo plug-in Maven di App Engine basato su Google Cloud CLI non supporta il miglioramento di Datanucleus di alcun tipo. Se il tuo progetto utilizza il supporto per il miglioramento di Datanucleus JDO o JPA del vecchio plug-in, devi configurare separatamente il plug-in Maven Datanucleus di terze parti durante la migrazione. Vai ai seguenti argomenti per ulteriori informazioni:

Gradle

Se il tuo progetto utilizza il miglioramento gradle-appengine-plugin JPA/JDO Datanucleus, devi configurare manualmente il miglioramento Datanucleus dopo aver eseguito la transizione al nuovo plug-in Gradle basato su gcloud CLI. Guarda un esempio di Stackoverflow.