Gestione del controllo delle versioni dell'API

Questa pagina descrive come eseguire il controllo delle versioni per l'API e come eseguire il deployment su più versioni.

Suggerimenti per la gestione delle versioni API

Quando gestisci le versioni API, tieni presente questi suggerimenti:

Se vuoi introdurre una modifica incrementale, ma non irreversibile, mantieni costante la versione API ed esegui il deployment sull'API esistente.
Quando introduci una modifica irreversibile all'API, incrementa la versione API.
Per una maggiore protezione, incrementa anche la versione dell'applicazione App Engine, quindi esegui il deployment della nuova versione 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 di App Engine all'altra e utilizzare le versioni precedenti funzionanti in caso di problemi imprevisti.

La tabella seguente illustra le versioni API del backend a cascata per le diverse versioni dell'applicazione App Engine.

Versione dell'applicazione	Versione API del backend
1	v1 --> v1 (2) --> v1 (n)
2	v1 (n) v2 --> v2 (2) --> v2 (n)
3	v1 (n) v2 (n) v3 --> v3 (2) --> v3 (n)

Come mostrato nella tabella, vengono implementati aggiornamenti incrementali e non irreversibili alla versione v1 dell'API, ognuno dei quali sovrascrive la versione precedente. Quando vengono introdotte modifiche irreversibili, la versione API viene incrementata a v2 e viene eseguito il deployment in una nuova versione dell'applicazione App Engine. In questo modo, se necessario, puoi tornare alla versione precedente dell'applicazione.

Nella tabella, tieni presente che la versione 2 dell'applicazione supporta sia l'ultima versione v1 sia la nuova versione v2 dell'API. Se non elimini il codice v1 esistente dal progetto, quando esegui il deployment del progetto, sia v2 sia vl (n) dell'API vengono sottoposte a deployment nella versione 2 dell'applicazione.

Eseguire il deployment su più versioni dell'applicazione

Quando esegui il deployment dell'API del backend, devi farlo nell'ID progetto del Google Cloud progetto che hai creato per l'API e devi anche specificare la versione di App Engine in cui eseguire il deployment. Specifica la versione dell'app App Engine nell'elemento <version> del /WEB-INF/appengine-web.xml file. La versione dell'app App Engine non è la stessa cosa del numero di versione dell'API del backend, che specifichi nell'attributo version dell'annotazione @Api.

apiversions

Come mostrato nella figura precedente, puoi eseguire il deployment di più versioni API nella stessa versione di App Engine. Inoltre, puoi avere molte versioni di App Engine per un'applicazione.

Accedere alle versioni API sottoposte a 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 l'ID Google Cloud progetto. Puoi accedere a tutte le versioni API sottoposte a deployment in quella versione dell'applicazione App Engine utilizzando questo URL.

La versione di pubblicazione rimane la stessa finché non la modifichi esplicitamente nella Google Cloud console.

Accesso alle versioni API sottoposte a deployment in una versione dell'applicazione non di pubblicazione

Se devi accedere alle versioni API che non sono sottoposte a deployment nella versione di App Engine attualmente in pubblicazione, utilizza un URL specifico della 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' Google Cloud ID progetto. Supponiamo, ad esempio, che la versione di pubblicazione di App Engine sia 1, ma vuoi accedere a una versione API sottoposta a deployment nella versione 2. Utilizzerai questo URL: https://2-dot-YOUR_PROJECT_ID.appspot.com.

Per maggiori dettagli, consulta la documentazione di App Engine.

Accesso alle versioni API sottoposte a deployment in servizi non di pubblicazione (in precedenza moduli)

Se devi accedere alle versioni API che non sono sottoposte a deployment nel servizio App Engine predefinito, puoi utilizzare un URL specifico del servizio utilizzando la sintassi con punti come segue:

https://SERVICE-NAME-dot-YOUR_PROJECT_ID.appspot.com/_ah/api/...