Migrazione a Cloud Endpoints Frameworks versione 2.0 per App Engine

In questa pagina viene descritta la migrazione di un'applicazione Cloud Endpoints versione 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.
Facoltativamente, nuove funzionalità di gestione delle API.

Endpoints Frameworks versione 2.0 non influisce sulle interfacce dell'API. I clienti 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 uno di questi requisiti, 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 Objective-C delle API di Google per le API REST.
ETag automatici
Campi di tipo automatici
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. La base richiesta in JAR è nell'artefatto endpoints-framework. Se vuoi utilizzare la configurazione di Guice, aggiungi l'artefatto endpoints-framework-guice.

Le istruzioni seguenti forniscono un esempio di come eseguire la migrazione da Endpoints Frameworks versione 1.0 alla versione 2.0 di Endpoints Frameworks utilizzando un documento di rilevamento:

Scarica e inizializza Google Cloud CLI.
Esegui questi comandi:
1. Assicurati che gcloud CLI sia autorizzato ad accedere a dati e servizi su Google Cloud:
```
gcloud auth login
```
2. Usa 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

Rimuovi la dipendenza legacy, che è l'artefatto appengine-endpoints:

<dependency>
      <groupId>com.google.appengine</groupId>
      <artifactId>appengine-endpoints</artifactId>
      <version>1.9.53</version>
</dependency>

Aggiungi la nuova dipendenza di Endpoints Frameworks:

<dependency>
    <groupId>com.google.endpoints</groupId>
    <artifactId>endpoints-framework</artifactId>
    <version>2.2.1</version>
</dependency>

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>

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. Devi utilizzare la nuova versione.

Aggiorna il punto di ingresso dell'API nel file web.xml del tuo progetto:

Rinomina tutte le occorrenze di SystemServiceServlet in EndpointsServlet
Sostituisci tutte le occorrenze del percorso /_ah/spi/ nel nuovo percorso richiesto /_ah/api/

Di seguito sono mostrati 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>

Dopo la modifica delle dipendenze pulisci il progetto:
```
mvn clean
```
Puoi generare un documento di rilevamento:
```
mvn endpoints-framework:discoveryDocs
```
Scopri di più sugli obiettivi dei plug-in di Maven Endpoints Frameworks.
Puoi eseguire il deployment di un progetto:
```
mvn appengine:deploy
```
Scopri di più sugli obiettivi dei plug-in di Maven App Engine.

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

Gradle

Rimuovi la dipendenza legacy, che è l'artefatto appengine-endpoints:

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

Aggiungi la nuova dipendenza di Endpoints Frameworks:

compile group: 'com.google.endpoints', name: 'endpoints-framework', version: '2.0.8'

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'
  }
}

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'

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"
}

Aggiorna il punto di ingresso dell'API nel file web.xml del tuo progetto:

Rinomina tutte le occorrenze di SystemServiceServlet in EndpointsServlet
Sostituisci tutte le occorrenze del percorso /_ah/spi/ nel nuovo percorso richiesto /_ah/api/

Di seguito sono mostrati 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>

Dopo la modifica delle dipendenze pulisci il progetto utilizzando:
```
gradle clean
```
Puoi generare un documento di rilevamento utilizzando:
```
gradle endpointsDiscoveryDocs
```
Scopri di più sulle attività dei plug-in di Gradle Endpoints Frameworks
Puoi eseguire il deployment di un progetto utilizzando:
```
gradle appengineDeploy
```
Scopri di più sulle attività dei plug-in di Gradle App Engine.

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

Utilizzo di Guice per la configurazione di Endpoints Frameworks per Java

Se vuoi utilizzare Guice:

Aggiungi la nuova dipendenza Guice per Framework di Endpoints:

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'

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 stia gestendo il traffico:

Invia alcune richieste al nuovo deployment.
Nella console Google Cloud, vai alla pagina Logging > Esplora log.

Vai alla pagina Esplora log
Se le richieste vengono visualizzate con percorsi che iniziano con /_ah/api, la versione 2.0 di Endpoints Frameworks gestisce l'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 continua a gestire le richieste.

Aggiunta della gestione dell'API Endpoints

Endpoints Frameworks versione 2.0 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 Aggiungere la gestione delle API.

Risoluzione dei problemi

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

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

Quando esegui la migrazione a Endpoints Frameworks versione 2.0, devi rimuovere la configurazione precedente di Endpoints Frameworks versione 1.0. Se la configurazione precedente è ancora presente nella configurazione dell'applicazione, il servizio Endpoints continua a trattare l'app come un'app della versione 1.0. Potresti notare delle richieste nei tuoi log di App Engine inviate a /_ah/spi, con il risultato di HTTP 404 errori inviati al client.

Rimuovi dal file web.xml le seguenti righe, se presenti:

<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>

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'artefatto endpoints-framework nell'applicazione, non il precedente JAR appengine-endpoints. Se esegui il deployment di un'applicazione con entrambi i JAR, potresti riscontrare errori di riflessione o errori di tipo di runtime, come 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 altre dipendenze dipendono da versioni precedenti di Guava, questo può manifestarsi anche come metodo TypeToken mancante. Devi assicurarti di utilizzare Guava v19 o di utilizzare l'artefatto endpoints-framework-all, che esegue lo shadowing delle dipendenze.

Le origini delle librerie client non vengono compilate

Se viene visualizzato un errore del tipo method does not override or implement a method from a supertype o cannot find symbol method setBatchPath(String), è probabile che l'applicazione client dipende da una versione precedente della libreria client Java di Google. 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 Datanucleus di alcun tipo. Se il progetto utilizza il supporto per il miglioramento Datanucleus JDO o JPA dal plug-in precedente, devi configurare separatamente il plug-in Datanucleus Maven di terze parti quando esegui la migrazione. Vai ai seguenti argomenti per ulteriori informazioni:

Gradle

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

Migrazione a Cloud Endpoints Frameworks versione 2.0 per App Engine

Vantaggi

Funzionalità e strumenti attualmente esclusi

Migrazione a Endpoints Frameworks versione 2.0

Esegui la migrazione utilizzando Maven o Gradle

Maven

Prima della migrazione

Dopo la migrazione

Gradle

Prima della migrazione

Dopo la migrazione

Utilizzo di Guice per la configurazione di Endpoints Frameworks per Java

Maven

Gradle

Verifica di un nuovo deployment

Aggiunta della gestione dell'API Endpoints

Risoluzione dei problemi

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

L'API genera errori di riflessione

Maven

Gradle

Le origini delle librerie client non vengono compilate

Maven

Gradle

Problemi con il miglioramento di Datanucleus JPA/JDO

Maven

Gradle

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