Questa pagina descrive come eseguire il versionamento dell'API e come eseguire il deployment in più versioni.
Consigli per la gestione delle versioni dell'API
Per la gestione delle versioni dell'API, tieni in considerazione questi consigli:
- Quando vuoi introdurre una modifica incrementale, ma non che comporti interruzioni, mantieni costante la versione dell'API ed esegui il deployment nell'API esistente.
- Quando introduci una modifica che provoca un errore nell'API, incrementa la versione dell'API.
- Per una maggiore protezione, incrementa anche la versione dell'applicazione App Engine, quindi esegui il deployment della nuova versione dell'API nella nuova versione dell'applicazione App Engine. In questo modo puoi utilizzare la flessibilità integrata di App Engine per passare rapidamente da una versione all'altra e eseguire il servizio dalle vecchie versioni funzionanti in caso di problemi imprevisti.
La tabella seguente mostra le versioni dell'API di backend in cascata per diverse versioni dell'applicazione App Engine.
| Versione dell'applicazione | Versione dell'API di backend |
|---|---|
| 1 |
|
| 2 |
|
| 3 |
|
Come mostrato nella tabella, vengono implementati aggiornamenti incrementali e non inversi alla versione 1 dell'API, ciascuno dei quali sovrascrive la versione precedente. Quando vengono introdotte modifiche che comportano interruzioni, la versione dell'API viene incrementata a v2 e viene eseguita il deployment in una nuova versione dell'applicazione App Engine. In questo modo, se necessario, puoi tornare alla versione precedente delle applicazioni.
Nella tabella, tieni presente che la versione 2 dell'applicazione supporta sia la versione v1 più recente sia la nuova versione v2 dell'API. Se non elimini il codice esistente della versione 1 dal progetto, quando esegui il deployment del progetto, sia v2 che vl (n) della tua API vengono eseguiti nella versione 2 dell'applicazione.
Deployment in più versioni dell'applicazione
Quando esegui il deployment dell'API di backend, lo esegui nell'ID progetto del progetto Google Cloud che hai creato per l'API e devi anche specificare la versione di App Engine in cui esegui il deployment.
La versione dell'app App Engine viene specificata nell'elemento <version> del
file /WEB-INF/appengine-web.xml. La versione dell'app App Engine non è la stessa del numero di versione dell'API di backend, che specifichi nell'attributo version dell'annotazione @Api.
Come mostrato nella figura precedente, puoi eseguire il deployment di più versioni dell'API nella stessa versione di App Engine. Inoltre, puoi avere molte versioni di App Engine per un'applicazione.
Accesso alle versioni dell'API di cui è stato eseguito il deployment in una versione di pubblicazione
La prima
versione di App Engine
in cui esegui il deployment dell'API è la versione di pubblicazione. Questa versione viene eseguita all'URL
http://YOUR_PROJECT_ID.appspot.com, dove
YOUR_PROJECT_ID rappresenta il tuo ID progetto
Google Cloud. Puoi accedere a tutte le versioni dell'API di cui è stato eseguito il deployment nella versione dell'applicazione App Engine utilizzando questo URL.
La versione pubblicata rimane invariata finché non la modifichi esplicitamente nella console Google Cloud.
Accesso alle versioni dell'API di cui è stato eseguito il deployment in una versione dell'applicazione non pubblicata
Se devi accedere alle versioni dell'API non di cui è stato eseguito il deployment nella versione di App Engine attualmente in esecuzione, utilizza un URL specifico per la versione, simile al seguente:
https://VERSION-dot-YOUR_PROJECT_ID.appspot.com
Sostituisci VERSION con la versione di App Engine e YOUR_PROJECT_ID con l'ID del progetto Google Cloud. Ad esempio, supponiamo che la versione di App Engine in cui viene eseguito il servizio sia 1, ma tu voglia accedere a una versione dell'API di cui è stato eseguito il deployment nella versione 2. Devi usare questo URL: https://2-dot-YOUR_PROJECT_ID.appspot.com.
Per ulteriori dettagli, consulta la documentazione di App Engine.
Accesso alle versioni dell'API di cui è stato eseguito il deployment in servizi non di pubblicazione (in precedenza moduli)
Se devi accedere a versioni dell'API non di cui è stato eseguito il deployment nel servizio App Engine predefinito, puoi utilizzare un URL specifico per il servizio utilizzando la sintassi con punti come segue:
https://SERVICE-NAME-dot-YOUR_PROJECT_ID.appspot.com/_ah/api/...
Per ulteriori dettagli, consulta la documentazione di App Engine.