Gestione delle versioni di un'API

Questa pagina fornisce procedure di configurazione e deployment dettagliate per modificare il numero di versione dell'API. La procedura da utilizzare dipende dal fatto che le modifiche all'API siano compatibili con le versioni precedenti.

Per ulteriori informazioni e best practice, consulta la sezione 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 del codice client esistente, come best practice, incrementa il numero della versione minore dell'API prima di eseguire il deployment della nuova versione. Sebbene Cloud Endpoints esegua solo una versione minore di un'API alla volta, i grafici e i log in Endpoints > Servizi mostrano il numero di versione. Se aumenti il numero della versione minore prima di eseguire il deployment, i grafici e i log forniscono una cronologia etichettata dei deployment.

Per incrementare il numero della versione secondaria:

  1. In openapi.yaml, incrementa il numero della versione secondaria del campo info.version. Ad esempio, se la versione corrente è 1.1, imposta info.version su 1.2:

    info:
  description: "A simple Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.2"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

  2. Utilizza Google Cloud CLI per eseguire il deployment della configurazione dell'API:

    gcloud endpoints services deploy openapi.yaml

  3. Esegui il deployment del backend dell'API utilizzando l'ID configurazione restituito dal passaggio precedente. Per maggiori dettagli, consulta Eseguire il deployment del backend dell'API.

Modifiche non compatibili con le versioni precedenti

Quando apporti modifiche all'API che causano un malfunzionamento del codice client dei clienti, come best practice incrementa il numero della versione principale dell'API. Endpoints può eseguire più di una versione principale di un'API contemporaneamente. Fornendo entrambe le versioni dell'API, i clienti possono scegliere la versione che vogliono utilizzare e controllare quando eseguire la migrazione alla nuova versione.

Per eseguire contemporaneamente le versioni esistenti e nuove di un'API:

  1. Crea file di configurazione OpenAPI separati per ogni versione che devi pubblicare. Questa procedura utilizza i nomi file openapi-v1.yaml e openapi-v2.yaml a scopo di esempio.

  2. Copia i contenuti di openapi-v1.yaml in openapi-v2.yaml.

  3. 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"

  4. In openapi-v2.yaml, configura quanto segue:

    • Apportare modifiche non compatibili con le versioni precedenti.
    • Imposta il campo info.version sul nuovo numero di versione.
    • Imposta il campo basePath in modo che includa il nuovo numero di versione principale.
    • Rimuovi la sezione x-google-endpoints. Questa sezione è necessaria se vuoi specificare l'indirizzo IP DNS o il flag allowCors. Quando esegui il deployment di due versioni dell'API con due file di configurazione YAML, solo una di queste può avere x-google-endpoints, ma la relativa 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"

  5. Utilizza Google Cloud CLI per eseguire il deployment di entrambi i file di configurazione dell'API:

    gcloud endpoints services deploy openapi-v1.yaml openapi-v2.yaml

  6. Esegui il deployment di un singolo backend che gestisce entrambe le versioni dell'API utilizzando l'ID configurazione restituito dal passaggio precedente. Per maggiori dettagli, consulta Eseguire il deployment del backend dell'API.

Passaggi successivi