Questa pagina fornisce procedure dettagliate di configurazione e deployment per modificare il numero di versione dell'API. La procedura da utilizzare dipende dalla compatibilità delle modifiche all'API con le versioni precedenti.
- Se la nuova versione dell'API contiene modifiche compatibili con le versioni precedenti, ad esempio l'aggiunta di nuovi campi o metodi, consulta Modifiche compatibili con le versioni precedenti.
- Se la nuova API presenta modifiche a un metodo esistente che danneggia il codice client dei tuoi clienti, consulta Modifiche non compatibili con le versioni precedenti.
Per ulteriori informazioni e best practice, consulta Gestione del ciclo di vita delle API.
Modifiche compatibili con le versioni precedenti
Quando apporti modifiche all'API che sono compatibili con le versioni precedenti al codice client esistente, come best practice, incrementa il numero di versione secondaria dell'API prima di eseguire il deployment della nuova versione. Sebbene Cloud Endpoints esegua solo una versione secondaria di un'API alla volta, i grafici e i log in Endpoint > Servizi mostrano il numero di versione. Aumentando il numero di versione minore prima del deployment, i grafici e i log forniscono una cronologia etichettata dei deployment.
Per incrementare il numero di versione secondaria:
In
openapi.yaml
, incrementa il numero di versione secondaria del campoinfo.version
. Ad esempio, se la versione corrente è1.1
, impostainfo.version
su1.2
:info: description: "A simple Cloud Endpoints API example." title: "Endpoints Example" version: "1.2" host: "echo-api.endpoints.example-project-12345.cloud.goog"
Utilizza Google Cloud CLI per eseguire il deployment della configurazione API:
gcloud endpoints services deploy openapi.yaml
Esegui il deployment del backend API utilizzando l'ID configurazione restituito dal passaggio precedente. Per maggiori dettagli, consulta Deployment del backend dell'API.
Modifiche non compatibili con le versioni precedenti
Quando apporti modifiche all'API che danneggiano il codice client dei tuoi clienti, come best practice, incrementa il numero di versione principale dell'API. Gli endpoint possono eseguire contemporaneamente più di una versione principale di un'API. Se fornisci entrambe le versioni dell'API, i tuoi clienti possono scegliere quale versione utilizzare e controllare quando eseguono la migrazione alla nuova versione.
Per eseguire contemporaneamente la versione nuova ed esistente di un'API:
Crea file di configurazione OpenAPI separati per ogni versione da pubblicare. Questa procedura utilizza i nomi di file
openapi-v1.yaml
eopenapi-v2.yaml
a scopo di esempio.Copia i contenuti di
openapi-v1.yaml
inopenapi-v2.yaml
.In
openapi-v1.yaml
, configura quanto segue:- Imposta il campo
info.version
sul numero di versione esistente. - Lascia invariato il campo
basePath
.
Ad esempio:
info: description: "A simple Cloud Endpoints API example." title: "Endpoints Example" version: "1.1" host: "echo-api.endpoints.example-project-12345.cloud.goog" basePath: "/v1"
- Imposta il campo
In
openapi-v2.yaml
, configura quanto segue:- Apporta modifiche incompatibili con le versioni precedenti.
- Imposta il campo
info.version
sul nuovo numero di versione. - Imposta il campo
basePath
in modo da includere il nuovo numero di versione principale. - Rimuovi la sezione
x-google-endpoints
. Questa sezione è necessaria se vuoi specificare l'indirizzo IP DNS o il flagallowCors
. Quando esegui il deployment di due versioni dell'API con due file di configurazione YAML, solo una di queste può averex-google-endpoints
, ma la sua configurazione verrà applicata a entrambe le versioni.
Ad esempio:
info: description: "A simple Google Cloud Endpoints API example." title: "Endpoints Example" version: "2.0" host: "echo-api.endpoints.example-project-12345.cloud.goog" basePath: "/v2"
Utilizza Google Cloud CLI per eseguire il deployment di entrambi i file di configurazione API:
gcloud endpoints services deploy openapi-v1.yaml openapi-v2.yaml
Esegui il deployment di un singolo backend che gestisce entrambe le versioni dell'API utilizzando l'ID di configurazione restituito dal passaggio precedente. Per maggiori dettagli, consulta Deployment del backend dell'API.