Migrazione alla versione 2.0 di Cloud Endpoints Frameworks per App Engine

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

Nota: in questa pagina, Endpoints 1.0 viene indicato come Endpoints Frameworks versione 1.0, mentre il nuovo Endpoints Frameworks per App Engine viene indicato 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.

Endpoints Frameworks versione 2.0 non influisce sulle interfacce dell'API. I client esistenti continuano a funzionare dopo la migrazione senza modifiche al codice lato client.

Funzionalità e strumenti attualmente esclusi

Le seguenti funzionalità non sono attualmente disponibili. Se ne hai bisogno, invia una richiesta di funzionalità.

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

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

Migrazione a Endpoints Frameworks versione 2.0

Endpoints Frameworks versione 2.0 è stato spostato negli artefatti Maven nel gruppo com.google.endpoints. Il file JAR di base richiesto si trova nell'artefatto endpoints-framework. Se vuoi utilizzare la configurazione di Guice, aggiungi l'artefatto endpoints-framework-guice.

Le seguenti istruzioni forniscono un esempio di come eseguire la migrazione da Endpoints Frameworks versione 1.0 a Endpoints Frameworks versione 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 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 app-engine-java di Google Cloud SDK:

      gcloud components install app-engine-java

   4. Esegui l'aggiornamento all'ultima versione di Google Cloud SDK e di tutti i componenti:

      gcloud components update

Eseguire la migrazione utilizzando Maven o Gradle

Maven

1. Rimuovi la dipendenza legacy, ovvero l' appengine-endpoints artefatto:
   <dependency>
         <groupId>com.google.appengine</groupId>
         <artifactId>appengine-endpoints</artifactId>
         <version>1.9.53</version>
   </dependency>

2. Aggiungi la nuova dipendenza di 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 di 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 vecchio plug-in Maven di App Engine, con il gruppo com.google.appengine, non è compatibile con il plug-in Endpoints Frameworks plugin. Devi utilizzare la nuova versione.
5. Aggiorna il punto di ingresso dell'API nel file del progetto web.xml :
   • 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

   web.xml di Endpoints Frameworks versione 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>

   Dopo la migrazione

   web.xml di Endpoints Frameworks versione 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. Dopo aver modificato le dipendenze, pulisci il progetto:

   mvn clean

7. Puoi generare un documento di rilevamento:

   mvn endpoints-framework:discoveryDocs

   Scopri di più sugli obiettivi del plug-in Maven Endpoints Frameworks plugin goals.
8. Puoi eseguire il deployment di un progetto:

   mvn appengine:deploy

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

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

Gradle

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

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

2. Aggiungi la nuova dipendenza di 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 ed 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 file del progetto web.xml :
   • 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

   web.xml di Endpoints Frameworks versione 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>

   Dopo la migrazione

   web.xml di Endpoints Frameworks versione 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. Dopo aver modificato le dipendenze, pulisci il progetto utilizzando:

   gradle clean

8. Puoi generare un documento di rilevamento utilizzando:

   gradle endpointsDiscoveryDocs

   Scopri di più sulle attività del plug-in Gradle Endpoints Frameworks
9. Puoi eseguire il deployment di un progetto utilizzando:

   gradle appengineDeploy

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

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

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

Verificare un nuovo deployment

Puoi verificare che il nuovo framework stia gestendo il traffico:

1. Invia alcune richieste al nuovo deployment.

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

   Vai alla pagina Esplora log

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

Aggiungere la gestione delle 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 delle API
• Autenticazione degli utenti
• Metriche delle API
• Log delle API

Per iniziare a utilizzare queste funzionalità, consulta Aggiungere la gestione delle API.

Risoluzione dei problemi

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

L'API restituisce errori 404, ma API Explorer continua a elencare correttamente le API

Quando esegui la migrazione a Endpoints Frameworks versione 2.0, devi rimuovere la vecchia configurazione di Endpoints Frameworks versione 1.0. Se la vecchia configurazione è ancora presente nella configurazione dell'applicazione, il servizio Endpoints continua a trattare l'app come un'app versione 1.0. Potresti visualizzare richieste nei log di App Engine 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 reflection

Devi inserire nel pacchetto dell'applicazione solo l'artefatto endpoints-framework, non il vecchio file JAR appengine-endpoints. Se esegui il deployment di un'applicazione con entrambi i file JAR, potresti riscontrare errori di reflection o errori di tipo di runtime, come NoClassDefFoundError, NoSuchMethodError e ClassCastException. Se presenti, rimuovi le seguenti righe dal file di build:

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 v19 o l'artefatto endpoints-framework-all, che oscura le dipendenze.

Le origini della libreria client non vengono compilate

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'artefatto google-api-client sia 1.23.0 o versioni successive.

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

Maven

Il nuovo plug-in Maven di App Engine basato su Google Cloud CLI non supporta il miglioramento Datanucleus di alcun tipo. Se il tuo progetto utilizza il supporto per il miglioramento 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 JDO
• Istruzioni JPA

Gradle

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