Migrazione ai framework di Cloud Endpoints versione 2.0 per App Engine

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

Nota: in questa pagina si fa riferimento a Endpoints 1.0 come Endpoints Frameworks versione 1.0 e nuove Endpoints Frameworks per App Engine come Endpoints Frameworks versione 2.0.

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.
• Facoltativamente, 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 iOS per l'API Endpoints Frameworks versione 2.0, di utilizzare Libreria client Objective-C delle API di Google per API REST.
• ETag automatici
• Campi del tipo automatico
• Integrazione con l'ambiente IDE
• fields risposta parziale
• Creazione automatica del metodo dell'API PATCH

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

Migrazione a Endpoints Frameworks versione 2.0

Endpoints Frameworks versione 2.0 è stato spostato negli elementi Maven del gruppo com.google.endpoints. Il file 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:

Nota: se utilizzi Endpoints Frameworks versione 1.0 con Eclipse, prima converti il progetto in un progetto Maven e poi segui le istruzioni di Maven riportate di seguito.

1. Scarica e inizializza Google Cloud CLI.
2. Esegui questi comandi:
   1. Assicurati che gcloud CLI sia autorizzato 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 Google Cloud SDK app-engine-java:

      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 legacy, ovvero appengine-endpoints artefatto:
   <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 rilevamento 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>

   Nota: il plug-in Maven precedente di App Engine con gruppo com.google.appengine non è compatibile con Endpoints Frameworks . Devi utilizzare la nuova versione.
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 vengono mostrati i contenuti di web.xml prima e dopo 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ù su Maven Endpoints Frameworks obiettivi del plug-in.
8. Puoi eseguire il deployment di un progetto:

   mvn appengine:deploy

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

   Nota: quando esegui la migrazione, devi eseguire il deployment in una nuova versione di App Engine. Questa operazione viene eseguita automaticamente se non specifichi una versione. Consulta la sezione Problemi noti.

Gradle

1. Rimuovi la dipendenza legacy, ovvero appengine-endpoints artefatto:

   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 ingresso dell'API nel progetto web.xml file:
   • Rinomina tutte le occorrenze di SystemServiceServlet a EndpointsServlet
   • Sostituisci tutte le occorrenze del percorso /_ah/spi/ con il nuovo percorso richiesto /_ah/api/
     

   Di seguito vengono mostrati i contenuti di web.xml prima e dopo 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 task del plug-in
9. Puoi eseguire il deployment di un progetto utilizzando:

   gradle appengineDeploy

   Scopri di più sull'App Engine Gradle attività dei plug-in.

   Nota: durante la migrazione, devi eseguire il deployment in una nuova versione di App Engine. L'operazione viene eseguita automaticamente se non specifichi un completamente gestita. Vedi Problemi noti.

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 estende 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 a 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 con la versione 2.0 di Endpoints Frameworks. 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

Endpoints Frameworks versione 2.0 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 delle API

Per iniziare a utilizzare queste funzioni, consulta Aggiunta della gestione delle 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 404 errori, ma Explorer API elenca comunque le API correttamente

È necessario rimuovere la versione precedente di Endpoints Frameworks 1.0 durante la migrazione a Endpoints Frameworks versione 2.0. 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. Rimuovi le seguenti righe del file di build, se presenti:

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 altre dipendenze dipendono da versioni precedenti di Guava, questo può anche manifestarsi come metodo TypeToken mancante. Devi assicurarti di utilizzare Guava v19 o l'artefatto endpoints-framework-all, che le dipendenze shadow.

Le origini della libreria client non vengono compilate

Se viene visualizzato un errore simile a method does not override or implement a method from a supertype o cannot find symbol method setBatchPath(String): l'applicazione client dipende probabilmente da una versione precedente di Google Java libreria client. Devi assicurarti che l'artefatto 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 basato su App Engine basato su Google Cloud CLI supportare il miglioramento di qualsiasi tipo Datanucleus. 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:

• Istruzioni per JDO
• Istruzioni per l'JPA

Gradle

Se il progetto utilizza il metodo JPA/JDO gradle-appengine-plugin Miglioramento Datanucleus, devi configurare manualmente Datanucleus miglioramento dopo il passaggio al nuovo Gradle basato su gcloud CLI . Consulta un un esempio da Stack Overflow.