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:
- Assicurati che gcloud CLI sia autorizzato ad accedere a dati e servizi su Google Cloud:
gcloud auth login
- Usa le credenziali predefinite dell'applicazione:
gcloud auth application-default login
- Installa il componente
app-engine-java
di Google Cloud SDK:gcloud components install app-engine-java
- Esegui l'aggiornamento alla versione più recente di Google Cloud SDK e di tutti i componenti:
gcloud components update
- Assicurati che gcloud CLI sia autorizzato ad accedere a dati e servizi su Google Cloud:
Esegui la migrazione utilizzando Maven o Gradle
Maven
- Rimuovi la dipendenza legacy, che è l'artefatto
appengine-endpoints
: - Aggiungi la nuova dipendenza di Endpoints Frameworks:
- Aggiungi il nuovo plug-in Endpoints Frameworks e definisci il nome host per un documento di rilevamento generato:
- Aggiungi il nuovo plug-in Maven di App Engine:
- Aggiorna il punto di ingresso dell'API nel file
web.xml
del tuo progetto:- Rinomina tutte le occorrenze di
SystemServiceServlet
inEndpointsServlet
- 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.0web.xml
:Dopo la migrazione
Endpoints Frameworks versione 2.0web.xml
: - Rinomina tutte le occorrenze di
- 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.
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:
- Aggiungi i nuovi plug-in App Engine ed Endpoints Frameworks:
- Applica i nuovi plug-in App Engine ed Endpoints Frameworks:
- Definisci l'endpoint del nome host per i documenti di rilevamento generati:
- Aggiorna il punto di ingresso dell'API nel file
web.xml
del tuo progetto:- Rinomina tutte le occorrenze di
SystemServiceServlet
inEndpointsServlet
- 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.0web.xml
:Dopo la migrazione
Endpoints Frameworks versione 2.0web.xml
: - Rinomina tutte le occorrenze di
- 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.
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
Gradle
- Dichiara un nuovo modulo che estende
EndpointsModule
e configuralo come segue:
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.
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
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.