Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
OpenAPI | gRPC
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.
Se la nuova versione dell'API presenta modifiche compatibili con le versioni precedenti, ad esempio l'aggiunta di nuovi campi o metodi, consulta 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:
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"
Utilizza Google Cloud CLI per eseguire il deployment della configurazione dell'API:
gcloud endpoints services deploy openapi.yaml
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:
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.
Copia i contenuti di openapi-v1.yaml in openapi-v2.yaml.
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"
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"
Utilizza Google Cloud CLI per eseguire il deployment di entrambi i file di configurazione dell'API:
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.
[[["Facile da capire","easyToUnderstand","thumb-up"],["Il problema è stato risolto","solvedMyProblem","thumb-up"],["Altra","otherUp","thumb-up"]],[["Difficile da capire","hardToUnderstand","thumb-down"],["Informazioni o codice di esempio errati","incorrectInformationOrSampleCode","thumb-down"],["Mancano le informazioni o gli esempi di cui ho bisogno","missingTheInformationSamplesINeed","thumb-down"],["Problema di traduzione","translationIssue","thumb-down"],["Altra","otherDown","thumb-down"]],["Ultimo aggiornamento 2025-09-04 UTC."],[[["\u003cp\u003eThis document outlines procedures for updating API versions, differentiating between backwards-compatible and backwards-incompatible changes.\u003c/p\u003e\n"],["\u003cp\u003eFor backwards-compatible changes, it's recommended to increment the minor version number in the \u003ccode\u003einfo.version\u003c/code\u003e field of the \u003ccode\u003eopenapi.yaml\u003c/code\u003e file and then deploy using the Google Cloud CLI.\u003c/p\u003e\n"],["\u003cp\u003eWhen introducing backwards-incompatible changes, it's recommended to increment the major version number and create separate OpenAPI configuration files for each version.\u003c/p\u003e\n"],["\u003cp\u003eTo deploy multiple major versions concurrently, each version should have its own configuration file (e.g., \u003ccode\u003eopenapi-v1.yaml\u003c/code\u003e, \u003ccode\u003eopenapi-v2.yaml\u003c/code\u003e) with distinct \u003ccode\u003ebasePath\u003c/code\u003e values and the \u003ccode\u003ex-google-endpoints\u003c/code\u003e section removed from all but one configuration.\u003c/p\u003e\n"],["\u003cp\u003eAfter the deployment of the API configuration files, a single backend must be deployed that services both versions of the API.\u003c/p\u003e\n"]]],[],null,["# Versioning an API\n\nOpenAPI \\| gRPC\n\n\u003cbr /\u003e\n\nThis page provides detailed configuration and deployment procedures for changing\nthe version number of your API. The procedure that you use depends on whether\nthe changes to your API are backwards compatible.\n\n- If your new API version has backwards-compatible changes, such as adding new fields or methods, see [Backwards-compatible changes](#backwards-compatible).\n- If your new API has changes to an existing method that breaks your customers' client code, see [Backwards-incompatible changes](#backwards-incompatible).\n\nFor additional information and best practices, see\n[API lifecycle management](/endpoints/docs/openapi/lifecycle-management).\n\nBackwards-compatible changes\n----------------------------\n\nWhen you make changes to your API that are backwards compatible with\nexisting client code, as a best practice, increment the minor version number of\nyour API before you deploy the new version. Although Cloud Endpoints runs only\none minor version of an API at a time, the graphs and logs in\n**Endpoints** \\\u003e **Services** display the version number. By incrementing the\nminor version number before you deploy, the graphs and logs provide a labeled\nhistory of your deployments.\n\nTo increment the minor version number:\n\n1. In `openapi.yaml`, increment the minor version number of the\n `info.version` field. For example, if the current version is `1.1`, set\n `info.version` to `1.2`:\n\n info:\n description: \"A simple Cloud Endpoints API example.\"\n title: \"Endpoints Example\"\n version: \"1.2\"\n host: \"echo-api.endpoints.example-project-12345.cloud.goog\"\n\n2. Use the Google Cloud CLI to deploy the API configuration:\n\n gcloud endpoints services deploy openapi.yaml\n\n3. Deploy the API backend by using the configuration ID returned from the\n previous step. For details, see\n [Deploying the API backend](/endpoints/docs/openapi/deploy-api-backend).\n\nBackwards-incompatible changes\n------------------------------\n\nWhen you make changes to your API that breaks your customers' client\ncode, as a best practice, increment the major version number of your API.\nEndpoints can run more than one major version of an API\nconcurrently. By providing both versions of the API, your customers can pick\nwhich version they want to use and control when they migrate to the new version.\n\nTo run the existing and new versions of an API concurrently:\n\n1. Create separate OpenAPI configuration files for each version you need to\n serve. This procedure uses the file names `openapi-v1.yaml` and\n `openapi-v2.yaml` for example purposes.\n\n2. Copy the contents of `openapi-v1.yaml` to `openapi-v2.yaml`.\n\n3. In `openapi-v1.yaml` configure the following:\n\n - Set the `info.version` field to the existing version number.\n - Leave the `basePath` field unchanged.\n\n For example: \n\n info:\n description: \"A simple Cloud Endpoints API example.\"\n title: \"Endpoints Example\"\n version: \"1.1\"\n host: \"echo-api.endpoints.example-project-12345.cloud.goog\"\n basePath: \"/v1\"\n\n4. In `openapi-v2.yaml` configure the following:\n\n - Make backwards-incompatible changes.\n - Set the `info.version` field to the new version number.\n - Set the `basePath` field to include the new major version number.\n - Remove the `x-google-endpoints` section. This section is needed if you want to specify DNS IP address or `allowCors` flag. When deploying two versions of the API with two yaml config files, only one of them can have `x-google-endpoints`, but its config will apply to both versions.\n\n For example: \n\n info:\n description: \"A simple Google Cloud Endpoints API example.\"\n title: \"Endpoints Example\"\n version: \"2.0\"\n host: \"echo-api.endpoints.example-project-12345.cloud.goog\"\n basePath: \"/v2\"\n\n5. Use the Google Cloud CLI to deploy both API configuration files:\n\n gcloud endpoints services deploy openapi-v1.yaml openapi-v2.yaml\n\n | **Note:** Cloud Endpoints internally converts your multiple OpenAPI configuration files into a single configuration, which is identified by one configuration ID.\n6. Deploy a single backend that serves both versions of the API by using the\n configuration ID returned from the previous step. For details, see\n [Deploying the API backend](/endpoints/docs/openapi/deploy-api-backend).\n\nWhat's next\n-----------\n\n- [API lifecycle management](/endpoints/docs/openapi/lifecycle-management)\n- [Planning your Google Cloud projects](/endpoints/docs/openapi/planning-cloud-projects)"]]
