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: questa pagina si riferisce a Endpoints 1.0 come Endpoints Frameworks versione 1.0 e ai nuovi 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 Guice.
• (Facoltativo) Nuove funzionalità di gestione delle API.

Endpoints Frameworks versione 2.0 non influisce sulle interfacce della tua 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 al momento disponibili. Se hai bisogno di uno di questi, invia una richiesta di funzionalità.

• Protocollo JSON-RPC, necessario per i client iOS legacy. Per creare client iOS per la tua API Endpoints Frameworks versione 2.0, ti consigliamo di utilizzare la libreria client Objective-C delle API di Google per le API REST.
• ETag automatici
• Campi automatici del tipo
• Integrazione con l'ambiente IDE
• fields risposte parziali
• 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 JAR di base richiesto si trova nell'artefatto endpoints-framework. Se vuoi utilizzare la configurazione 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 Discovery:

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 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'artefatto appengine-endpoints:
   <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 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. Devi utilizzare la nuova versione.
5. Aggiorna il punto di ingresso 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, 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.
8. Puoi eseguire il deployment di un progetto:

   mvn appengine:deploy

   Scopri di più sugli obiettivi del plug-in Maven 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.

Gradle

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

   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 e 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 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, 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 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.

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 nel seguente modo:
   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 stia gestendo 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 visualizzate con percorsi che iniziano con /_ah/api, significa che Endpoints Frameworks versione 2.0 ora gestisce la tua API. I log non devono mostrare richieste con percorsi che iniziano con /_ah/spi. Queste richieste indicano che il proxy Endpoints Frameworks versione 1.0 continua a gestire le richieste.

Aggiunta della gestione delle API Endpoints

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

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

Risoluzione dei problemi

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

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

Quando esegui la migrazione a Endpoints Frameworks versione 2.0, devi rimuovere la configurazione della vecchia versione 1.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 di versione 1.0. Potresti visualizzare richieste nei log di App Engine inviate a /_ah/spi, che comportano 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 includere nel pacchetto dell'applicazione solo l'artefatto endpoints-framework, non il vecchio JAR appengine-endpoints. Se esegui il deployment di un'applicazione con entrambi i file JAR, potresti riscontrare errori di reflection o di tipo di runtime, ad esempio NoClassDefFoundError, NoSuchMethodError e ClassCastException. Rimuovi le seguenti righe dal 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 una delle altre dipendenze dipende da versioni precedenti di Guava, questo può manifestarsi anche come metodo TypeToken mancante. Devi assicurarti di utilizzare Guava v19 o l'artefatto endpoints-framework-all, che ombreggia 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 Java di Google. 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 JPA/JDO Datanucleus

Maven

Il nuovo plug-in Maven di App Engine basato 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:

• Istruzioni JDO
• Istruzioni per JPA

Gradle

Se il tuo progetto utilizza il miglioramento gradle-appengine-plugin 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.