Restez organisé à l'aide des collections
Enregistrez et classez les contenus selon vos préférences.
OpenAPI | gRPC
Cette page fournit des procédures de configuration et de déploiement détaillées permettant de modifier le numéro de version de votre API. La procédure que vous utilisez varie selon que les modifications apportées à votre API sont compatibles avec les versions antérieures.
Si la nouvelle version de votre API comporte des modifications rétrocompatibles, telles que l'ajout de champs ou méthodes, consultez la section Modifications rétrocompatibles.
Si votre nouvelle API est passée à une méthode existante qui rompt le code client de votre client, consultez la section Modifications incompatibles.
Lorsque vous apportez à votre API des modifications rétrocompatibles avec le code client existant, selon les bonnes pratiques, incrémentez le numéro de version mineure de votre API avant de déployer la nouvelle version. Bien que Cloud Endpoints n'exécute qu'une seule version mineure d'une API à la fois, les graphiques et les journaux sous Endpoints > Services affichent le numéro de version. En incrémentant le numéro de version mineure avant le déploiement, les graphiques et les journaux fournissent un historique étiqueté de vos déploiements.
Pour incrémenter le numéro de version mineure :
Dans openapi.yaml, incrémentez le numéro de version mineure dans le champ info.version. Par exemple, si la version actuelle est 1.1, définissez info.version sur 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"
Utilisez la Google Cloud CLI pour déployer la configuration de l'API:
gcloud endpoints services deploy openapi.yaml
Déployez le backend de l'API en utilisant l'ID de configuration renvoyé à l'étape précédente. Pour plus d'informations, consultez la section Déployer le backend de l'API.
Modifications non rétrocompatibles
Lorsque vous effectuez des modifications à votre API induisant une rupture du code client de votre client, selon les bonnes pratiques, vous devez incrémenter le numéro de version majeure de votre API.
Cloud Endpoints peut exécuter plusieurs versions majeures d'une API simultanément. En fournissant les deux versions de l'API, vos clients peuvent choisir la version qu'ils souhaitent utiliser et restent libres de définir une migration vers la nouvelle version.
Pour exécuter simultanément les versions existantes et les nouvelles versions d'une API :
Créez des fichiers de configuration OpenAPI distincts pour chaque version à diffuser. Cette procédure utilise les noms de fichiers openapi-v1.yaml et openapi-v2.yaml à des fins d'exemple.
Copiez le contenu de openapi-v1.yaml dans openapi-v2.yaml.
Dans openapi-v1.yaml, configurez les éléments suivants :
Définissez le champ info.version sur le numéro de la version existante.
Laissez le champ basePath inchangé.
Exemple :
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"
Dans openapi-v2.yaml, configurez les éléments suivants :
Apportez les modifications incompatibles avec les versions antérieures.
Définissez le champ info.version sur le numéro de la nouvelle version.
Définissez le champ basePath pour inclure le nouveau numéro de version majeure.
Supprimez la section x-google-endpoints. Cette section est nécessaire si vous souhaitez spécifier l'adresse IP DNS ou l'option allowCors. Lorsque vous déployez deux versions de l'API avec deux fichiers de configuration yaml, une seule d'entre elles peut être présente dans le fichier x-google-endpoints, mais sa configuration s'applique aux deux versions.
Exemple :
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"
Utilisez la Google Cloud CLI pour déployer les deux fichiers de configuration de l'API:
Déployez un seul backend qui diffuse les deux versions de l'API à l'aide de l'ID de configuration renvoyé à l'étape précédente. Pour plus d'informations, consultez la section Déployer le backend de l'API.
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/09/08 (UTC).
[[["Facile à comprendre","easyToUnderstand","thumb-up"],["J'ai pu résoudre mon problème","solvedMyProblem","thumb-up"],["Autre","otherUp","thumb-up"]],[["Difficile à comprendre","hardToUnderstand","thumb-down"],["Informations ou exemple de code incorrects","incorrectInformationOrSampleCode","thumb-down"],["Il n'y a pas l'information/les exemples dont j'ai besoin","missingTheInformationSamplesINeed","thumb-down"],["Problème de traduction","translationIssue","thumb-down"],["Autre","otherDown","thumb-down"]],["Dernière mise à jour le 2025/09/08 (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)"]]
