Gestione delle versioni di un'API

Questa pagina fornisce procedure dettagliate di configurazione e deployment per modificare il numero di versione dell'API. La procedura che utilizzi 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 alla tua API che sono compatibili con il 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 una sola versione secondaria di un'API alla volta, i grafici e i log in Endpoints > Servizi mostrano il numero di versione. Se incrementi il numero di versione secondaria prima del deployment, i grafici e i log forniscono una cronologia etichettata dei tuoi deployment.

Per incrementare il numero di versione secondaria:

  1. In openapi.yaml, incrementa il numero di versione secondaria del campo info.version. Ad esempio, se la versione attuale è 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 API utilizzando l'ID configurazione restituito dal passaggio precedente. Per maggiori dettagli, vedi Esegui il deployment del backend dell'API.

Modifiche non compatibili con le versioni precedenti

Quando apporti modifiche all'API che interrompono il codice client dei tuoi clienti, come best practice, incrementa il numero di versione principale dell'API. Endpoints può eseguire più di una versione principale di un'API contemporaneamente. Fornendo entrambe le versioni dell'API, i tuoi clienti possono scegliere quale versione 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 esemplificativo.

  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:

    • Apporta modifiche incompatibili 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 uno di questi può avere x-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"

  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, vedi Esegui il deployment del backend dell'API.

Passaggi successivi