Gestione del ciclo di vita delle API

Questa pagina descrive le funzionalità di gestione delle versioni dell'API Cloud Endpoints e fornisce le best practice per la gestione delle versioni e l'implementazione dell'API Endpoints. Le informazioni riportate in questa pagina sono applicabili alle API che utilizzano la specifica OpenAPI. Per le API che utilizzano framework Cloud Endpoints per l'ambiente standard App Engine, vedi Gestione del controllo delle versioni dell'API: Java o Gestione del controllo delle versioni dell'API: Python.

Ti consigliamo di seguire gli stessi principi di base utilizzati da Google per il versionamento delle API e lo staging dei servizi:

  • Includi quanto segue nel file di configurazione OpenAPI prima del deployment la versione iniziale:

    • Imposta il numero di versione nel campo info.version. Ti consigliamo di utilizzare una stringa di versione che includa una versione principale e una versione secondaria, ad esempio 1.0.
    • Imposta il campo basePath in modo che includa il numero della versione principale. Ti consigliamo di utilizzare un percorso di base formattato come la lettera v seguito dal numero della versione principale, ad esempio /v1.

  • Quando devi apportare una modifica compatibile con le versioni precedenti, ad esempio aggiungere una nuova , incrementa il numero di versione secondaria (1.2, 1.3, ecc.) nel info.version ed eseguire di nuovo il deployment. Consulta: Controllo delle versioni di un'API per maggiori dettagli.

  • Quando devi apportare una modifica a un metodo esistente che interrompe il codice del client, crea una copia del file di configurazione OpenAPI e apporta le seguenti modifiche:

    • Aumenta il numero della versione principale (2.0, 3.0 e così via) nell'info.version .
    • Incrementa il numero di versione principale (/v2, /v3 e così via) nel campo basePath.

    Esegui il deployment di entrambe le versioni dei file di configurazione OpenAPI e del backend, che ora contiene entrambe le versioni del metodo. Per informazioni dettagliate, consulta Eseguire il versionamento di un'API.

  • Implementa tutte le principali versioni dell'API in un unico backend. Questo consiglio:

    • Semplifica il routing perché le richieste a una versione specifica si basano sul percorso, come nell'esempio precedente.
    • Semplifica la configurazione e il deployment. Utilizzi lo stesso progetto e lo stesso backend Google Cloud per tutte le versioni principali dell'API ed esegui il deployment di tutte le versioni contemporaneamente.
    • Mantiene bassi i costi evitando di eseguire backend superflui.

  • Esegui lo staging dell'API in un progetto Google Cloud separato prima di eseguire il deployment nel progetto Google Cloud di produzione. Consulta: Servizi di gestione temporanea per maggiori dettagli.

L'utilizzo dei numeri di versione principale e secondaria in Endpoints corrisponde alle definizioni riportate nel controllo delle versioni semantico. Sebbene endpoint non richiede di incrementare il numero di versione File di configurazione OpenAPI ed esegui il deployment della configurazione quando esegui il deployment di un bug correggere il codice di backend, puoi scegliere di farlo se vuoi.

Funzionalità di gestione delle versioni dell'API Cloud Endpoints

Extensible Service Proxy (ESP) consente di gestire contemporaneamente più versioni principali dell'API in un singolo progetto e backend Google Cloud, a condizione che le API non abbiano percorsi sovrapposti. Ad esempio:

http://echo-api.endpoints.my-project.cloud.goog/v1/echo
http://echo-api.endpoints.my-project.cloud.goog/v2/echo

In questo modo i clienti possono scegliere la versione che vogliono utilizzare e controllare quando eseguono la migrazione alla nuova versione. L'ESP contrassegna ogni richiesta con il numero di versione prima di inoltrarla al metodo applicabile nel backend. Poiché ogni richiesta è codificata con un numero di versione:

  • I grafici e i log in Endpoint > I servizi mostrano le richieste provenienti da ogni versione principale dell'API e il totale aggregato per tutte le versioni. Puoi filtrare la visualizzazione in base a una versione specifica. Questo ti dà un'idea chiara di come il traffico ricevuto da ciascuna versione. I log possono anche indicare e la versione utilizzata dai client.

  • Quando esegui nuovamente il deployment dell'API con un aggiornamento secondario del numero di versione, l'attività viene etichettata con il nuovo numero di versione nei grafici e logaritmi. In questo modo, avrai una cronologia etichettata dei tuoi implementazioni.

  • Quando rimuovi una versione di un'API, i grafici e i log continuano a essere visualizzati nell'intervallo di tempo in cui l'API è stata attiva.

Esempio di ciclo di vita delle API

Questa sezione descrive l'evoluzione tipica di un servizio.

Versione 1

Inizialmente esegui il deployment della versione 1 del servizio API My Awesome Echo. L'API viene fornita da my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo. Nei grafici e log in Endpoint > Servizi, vedi tutto il traffico su 1.0.

Versione 1.1

I tuoi clienti richiedono una nuova funzionalità, quindi aggiungi un nuovo metodo. Nell'API OpenAPI di configurazione del deployment, aggiungi il nuovo metodo e incrementerai il campo info.version a 1.1. Incoraggi il numero di versione secondaria perché questa modifica non del codice client. Esegui il deployment e testa la modifica in un ambiente di staging per verificare che funzioni.

Successivamente, eseguirai il deployment della configurazione OpenAPI e del backend dell'API nell'ambiente di produzione completamente gestito di Google Cloud. L'API viene ancora pubblicata da my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo, ma ora i chiamanti possono effettuare richieste al nuovo metodo. Poiché non hai modificato l'interfaccia dei vecchi metodi, i tuoi clienti non devono modificare e eseguire nuovamente il deployment dei propri client. I client possono continuare a inviare richieste al vecchio metodo come prima.

In Endpoint > Servizi, il traffico gestito è ora alla versione 1.1. Se selezioni un intervallo di tempo precedente, verrà visualizzata la versione precedente grafici e log, che forniscono una cronologia etichettata dei tuoi deployment.

Versione 2.0

Nel tempo, ti rendi conto che devi apportare una modifica non compatibile con le versioni precedenti a un metodo esistente. Perché è importante non danneggiare i clienti codice client, decidi di mantenere due versioni dell'API. Lasci il vecchio così com'è e implementa la nuova versione del metodo. Crei un altro del file di configurazione OpenAPI per la versione 2.0 e configura la nuova versione offerto da my-api.endpoints.my‐awesomeproject.cloud.goog/v2/echo. Il file di configurazione OpenAPI originale fa ancora riferimento alla vecchia versione del metodo, mentre il nuovo file di configurazione OpenAPI fa riferimento alla nuova versione del metodo.

Esegui il deployment dei file di configurazione OpenAPI della versione 1 e della versione 2 contemporaneamente ed eseguire nuovamente il deployment del backend, che ora contiene entrambe le versioni del metodo. Per maggiori dettagli, consulta Eseguire il versionamento di un'API.

Dopo il deployment, Endpoints > Services (Endpoint > Servizi) mostra che stai pubblicando due versioni della tua API e puoi vedere quanto traffico riceve ciascuna versione. I client della versione 1 possono continuare a chiamare /v1, ma possono anche chiamare /v2 per utilizzare la nuova versione del metodo. Come gestisci il controllo delle versioni dipende dal framework API in uso. Per un esempio di utilizzo di servlet, consulta Esempio di endpoint e Java con più versioni.

Disabilitazione della versione 1

Nel tempo, man mano che i clienti eseguono la migrazione e noti che tutto il traffico verso la versione 1 si è interrotto, puoi smettere di pubblicarla. Per rimuovere la versione 1 dell'API, esegui il deployment solo del file di configurazione OpenAPI della versione 2 e esegui nuovamente il deployment del backend. Ora puoi rimuovere in sicurezza il codice che ha implementato la versione 1 dal tuo backend. Endpoint > Servizi conserva i dati storici della versione 1.x.

Servizi di gestione temporanea

Come best practice, ti consigliamo di posizionare temporaneamente gli aggiornamenti Servizio Endpoints per poter testare il servizio prima raggiunge i tuoi clienti. Ti consigliamo inoltre di creare un'immagine progetto Google Cloud per la gestione temporanea del servizio, in modo che sia isolato da e produzione. Ad esempio, le quote di Google sono generalmente condivise dalle risorse all'interno di un progetto. Pertanto, se inserisci il servizio di staging nello stesso progetto del servizio di produzione, un ciclo for errato, ad esempio, potrebbe causare un'interruzione del servizio di produzione.

Ti consigliamo di scegliere un nome per il progetto Google Cloud che indica che è per la gestione temporanea. Una strategia di denominazione comune è utilizzare lo stesso nome del progetto Google Cloud di produzione, ma con -staging alla fine. Ti consigliamo inoltre di inserire -prod nei progetti di produzione per chiarire che il progetto contiene servizi di produzione.

I nomi dei servizi su Google Cloud devono essere univoci. Poiché specifichi il nome del servizio nel file di configurazione OpenAPI, devi gestire file di configurazione API separati per i progetti di staging e di produzione oppure utilizzare un insieme di file di configurazione API e ideare un processo in cui modifichi il nome del servizio in modo che corrisponda al nome del progetto in cui esegui il deployment.

Passaggi successivi