Migrazione a Cloud Endpoints Frameworks versione 2.0

Cloud Endpoints Frameworks in precedenza era chiamato Endpoints. Per distinguere le due versioni, questa pagina fa riferimento alla nuova versione come Endpoints Frameworks versione 2.0 e alla versione precedente come Endpoints versione 1.0. Questa pagina descrive come eseguire la migrazione di un'applicazione Cloud Endpoints versione 1.0 a Endpoints Frameworks versione 2.0. La migrazione prevede una modifica della libreria e della configurazione dell'applicazione, ma non è necessario apportare modifiche al codice.

Vantaggi

La versione 2.0 di Endpoints offre una serie di vantaggi, tra cui:

• Latenza delle richieste ridotta.
• Migliore integrazione con le funzionalità di App Engine, come i domini personalizzati.
• Nuove funzionalità di gestione delle API.

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

Panoramica delle funzioni

Le seguenti funzionalità sono compatibili con le versioni precedenti di Endpoints 1.0:

• Protocollo JSON-REST, utilizzato da tutte le librerie client di Google.
• Servizio di rilevamento
• Tutte le funzionalità di autenticazione esistenti (OAuth2/OpenID Connect)
• Supporto della libreria client per i client generati
• CORS (per i chiamanti JavaScript che non utilizzano la libreria client JavaScript di Google)
• Explorer API

La suddivisione del traffico non è disponibile.

Funzionalità attualmente escluse

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

• Protocollo JSON-RPC, obbligatorio 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 kind automatici
• Integrazione con l'ambiente IDE
• fields risposta parziale
• Creazione automatica del metodo API PATCH

Migrazione da Endpoints versione 1.0

Importante: devi scaricare i pacchetti collegati e importarli nella tua applicazione. Devi rimuovere le dipendenze precedenti.

Per eseguire la migrazione dalla versione 1.0:

1. Crea una sottocartella denominata /lib nella directory principale dell'applicazione.

2. Installa la libreria dalla directory principale dell'applicazione:

    pip install -t lib google-endpoints --ignore-installed
   

3. Rimuovi le voci - name: endpoints e version 1.0 dal file app.yaml dell'applicazione nella sezione libraries. Ad esempio:

   libraries:
   - name: endpoints   #Remove
     version: 1.0      #Remove
   

4. Nella sezione libraries del file app.yaml, aggiungi quanto segue:

   libraries:
   - name: pycrypto
     version: 2.6
   - name: ssl
     version: 2.7.11
   

   Endpoints Frameworks richiede queste versioni delle librerie pycrypto e ssl.

5. Nella sezione handlers del file app.yaml, modifica l'istruzione url da - url: /_ah/spi/.* a - url: /_ah/api/.*.

6. Nella directory root dell'applicazione, crea o modifica un file denominato appengine_config.py per includere quanto segue:

   from google.appengine.ext import vendor
   
   vendor.add('lib')
   

7. Controlla la stringa della versione API. La stringa della versione, specificata nel decorator @endpoints.api(version='v1', ...), viene visualizzata nel percorso dell'API. Se specifichi una stringa di versione compatibile con lo standard SemVer, nel percorso dell'API viene visualizzato solo il numero di versione principale quando esegui il deployment dell'API. Ad esempio, un'API denominata echo con versione 2.1.0 avrà un percorso come /echo/v2. Se aggiorni l'API echo alla versione 2.2.0 ed esegui il deployment di una modifica compatibile con le versioni precedenti, il percorso rimane /echo/v2. Ciò ti consente di aggiornare il numero di versione dell'API quando apporti una modifica compatibile con le versioni precedenti senza interrompere i percorsi esistenti per i tuoi client. Tuttavia, se aggiorni l'API echo alla versione 3.0.0 (perché stai eseguendo il deployment di una modifica che provoca un errore), il percorso viene modificato in /echo/v3.

8. Esegui di nuovo il deployment dell'applicazione Endpoints Frameworks.

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

Verifica di un nuovo deployment

Per verificare che il nuovo framework gestisca il traffico:

1. Invia alcune richieste al nuovo deployment.
2. Visita la pagina di Cloud Logging per il tuo progetto.
   

   Vai alla pagina Esplora log

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

Aggiunta della gestione delle API

Endpoints Frameworks versione 2.0 aggiunge funzionalità di gestione delle API, tra cui:

• Gestione delle chiavi API
• Condivisione dell'API
• Autenticazione degli utenti
• Metriche delle API
• Log API

Per iniziare, vai alla pagina Introduzione a Endpoints Frameworks per Python.

Risoluzione dei problemi

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

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

Devi rimuovere la configurazione degli endpoint della versione precedente 1.0 durante la migrazione a Endpoints Frameworks versione 2.0. Se la configurazione precedente è ancora presente nella configurazione dell'applicazione, il servizio endpoint continua a trattare l'app come un'app di versione 1.0. Potresti vedere richieste nei log di App Engine inviate a /_ah/spi, che provocheranno errori HTTP 404 inviati al client.

1. Se presenti, rimuovi le seguenti righe dal file app.yaml:

   handlers:
   - url: /_ah/spi/.*
     script: ...
   

2. Assicurati che la sezione handlers del file app.yaml abbia il percorso corretto:

   handlers:
   # The endpoints handler must be mapped to /_ah/api.
   - url: /_ah/api/.*
     script: ...
   

Messaggio di errore: ImportError: cannot import name locked_file

Questo accade se le dipendenze contengono una versione della libreria oauth2client incompatibile con App Engine. Consulta il problema noto.