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 sono 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 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. Aumentando il minore prima del deployment, i grafici e i log forniscono una dei tuoi deployment.

Per incrementare il numero di versione secondaria:

  1. In openapi.yaml, incrementa il numero di versione secondaria dell' 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 dalla passaggio precedente. Per maggiori dettagli, vedi Deployment del backend dell'API.

Modifiche non compatibili con le versioni precedenti

Quando apporti modifiche all'API che danneggiano cliente 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 clienti possono scegliere la versione da utilizzare e controllare durante la migrazione alla nuova versione.

Per eseguire contemporaneamente la versione esistente e quella nuova di un'API:

  1. Creare file di configurazione OpenAPI separati per ogni versione di cui hai bisogno vengono pubblicate. Questa procedura utilizza i nomi file openapi-v1.yaml e openapi-v2.yaml per scopi 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 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 della 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 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