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 da utilizzare dipende dalla compatibilità delle modifiche all'API 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:

  1. In openapi.yaml, incrementa il numero di 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 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, 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:

  1. Crea file di configurazione OpenAPI separati per ogni versione da pubblicare. Questa procedura utilizza i nomi di 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:

    • 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 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 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 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 di configurazione restituito dal passaggio precedente. Per maggiori dettagli, consulta Deployment del backend dell'API.

Passaggi successivi