本页面介绍 Cloud Endpoints API 版本控制功能，并提供有关 Endpoints API 版本控制和预演的最佳做法。本页面提供的信息适用于采用 OpenAPI 规范的 API。
如果 API 使用适用于 App Engine 标准环境的 Cloud Endpoints Frameworks，请参阅处理 API 版本控制：Java 或处理 API 版本控制：Python。
接下来，您将 OpenAPI 配置和 API 后端部署到生产环境。此 API 仍然通过 my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo 提供，但现在调用者可以向新方法发出请求。由于您没有更改旧方法的接口，因此您的客户无需更改和重新部署其客户端；客户端可以像以前一样向旧方法发送请求。
[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-09-04。"],[[["\u003cp\u003eThis page provides guidance on versioning and staging APIs within Cloud Endpoints, specifically for those using the OpenAPI specification.\u003c/p\u003e\n"],["\u003cp\u003eIt's recommended to set the version number in the \u003ccode\u003einfo.version\u003c/code\u003e field (e.g., \u003ccode\u003e1.0\u003c/code\u003e) and include the major version in the \u003ccode\u003ebasePath\u003c/code\u003e (e.g., \u003ccode\u003e/v1\u003c/code\u003e) within the OpenAPI configuration file before deploying.\u003c/p\u003e\n"],["\u003cp\u003eFor backwards-compatible changes, like adding a new method, the minor version number should be incremented (e.g., 1.2, 1.3) and redeployed, while backwards-incompatible changes require incrementing the major version number (e.g., 2.0, 3.0) and deploying a new configuration file with an updated \u003ccode\u003ebasePath\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eAll major API versions should be implemented in a single backend to simplify routing, configuration, deployment, and to reduce costs, while still allowing customers to choose and migrate between versions.\u003c/p\u003e\n"],["\u003cp\u003eStaging updates in a separate Google Cloud project, with a clear naming convention (e.g., \u003ccode\u003e-staging\u003c/code\u003e suffix), is highly recommended for testing before deploying to production, ensuring isolation from potential issues.\u003c/p\u003e\n"]]],[],null,["# API lifecycle management\n\nOpenAPI \\| gRPC\n\n\u003cbr /\u003e\n\nThis page describes the Cloud Endpoints API versioning features and\nprovides best practices for versioning and staging your Endpoints\nAPI. The information on this page is applicable for APIs using the\n[OpenAPI specification](https://github.com/OAI/OpenAPI-Specification).\nFor APIs using Cloud Endpoints Frameworks for App Engine standard environment,\nsee\n[Handling API versioning: Java](/endpoints/docs/frameworks/java/handling-api-versioning)\nor\n[Handling API versioning: Python](/endpoints/docs/frameworks/python/handling-api-versioning).\n\nWe recommend that you follow the same basic principles that Google uses for API\nversioning and service staging:\n\n- Include the following in your OpenAPI configuration file before you deploy\n the initial version:\n\n - Set the version number in the `info.version` field. We recommend that you use a version string which includes a major version and a minor version, for example, `1.0`.\n - Set the `basePath` field to include the major version number. We recommend that you use a base path formatted as the letter `v` followed by major version number, for example, `/v1`.\n- When you need to make a backwards-compatible change, such as adding a new\n method, increment the minor version number (1.2, 1.3, etc.) in the\n `info.version` field and redeploy. See\n [Versioning an API](/endpoints/docs/openapi/versioning-an-api)\n for details.\n\n- When you need to make a change to an existing method that breaks client\n code, make a copy of your OpenAPI configuration file, and make the following\n changes:\n\n - Increment the major version number (2.0, 3.0, etc.) in the `info.version` field.\n - Increment the major version number (/v2, /v3, etc.) in the `basePath` field.\n\n Deploy both versions of your OpenAPI configuration files and redeploy the\n backend, which now has both versions of the method. See\n [Versioning an API](/endpoints/docs/openapi/versioning-an-api)\n for details.\n- Implement all major API versions in a single backend. This recommendation:\n\n - Simplifies routing because requests to a specific version are based on the path, as in the previous example.\n - Simplifies configuration and deployment. You use the same Google Cloud project and backend for all major versions of the API, and you deploy all versions of your API at the same time.\n - Keeps your costs down by avoiding running superfluous backends.\n- Stage your API in a separate Google Cloud project before you deploy to\n your production Google Cloud project. See\n [Staging services](#staging-services)\n for details.\n\nThe use of major and minor version numbers in Endpoints\ncorresponds to the definitions in\n[Semantic versioning](http://semver.org/). Although Endpoints\ndoesn't require that you increment the patch version number in your\nOpenAPI configuration file and deploy the configuration when you deploy a bug\nfix in your backend code, you can choose to do so if you like.\n\nCloud Endpoints API versioning features\n---------------------------------------\n\nThe\n[Extensible Service Proxy (ESP)](/endpoints/docs/openapi/about-cloud-endpoints)\nhas the ability to manage multiple major versions of your API concurrently in a\nsingle Google Cloud project and backend as long as the APIs don't have\noverlapping paths. For example: \n\n http://echo-api.endpoints.my-project.cloud.goog/v1/echo\n http://echo-api.endpoints.my-project.cloud.goog/v2/echo\n\nThis lets your customers pick which version they want to use and control\nwhen they migrate to the new version. The ESP tags each\nrequest with the version number before routing the request to the applicable\nmethod in the backend. Because each request is tagged with a version number:\n\n- The graphs and logs in **Endpoints** \\\u003e **Services** display requests from\n each major API version and the aggregate total across all versions. You can\n filter your view to a specific version. This gives you a clear idea of how\n much traffic each version is getting. The logs can even tell you which\n clients are using which version.\n\n- When you redeploy your API with a minor version number update, subsequent\n activity is labeled with the new version number in the graphs and\n logs. This provides you with a labeled history of your deployments.\n\n- When you remove a version of an API, the graphs and logs continue to display\n data in the time range that the API was active.\n\nAPI lifecycle example\n---------------------\n\nThis section describes a typical evolution of a service.\n\n**Version 1**\n\nYou initially deploy version 1 of My Awesome Echo API service. The API is served\nfrom `my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo`. In the graphs and\nlogs in **Endpoints** \\\u003e **Services** , you see all traffic at `1.0`.\n\n**Version 1.1**\n\nYour customers request a new feature, so you add a new method. In your OpenAPI\nconfiguration file, you add the new method and increment the `info.version` field\nto `1.1`. You increment the minor version number because this change doesn't\nbreak client code. You deploy and test your change in a staging environment to\nensure it works.\n\nNext, you deploy the OpenAPI configuration and the API backend to the production\nenvironment. The API is still served from\n`my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo`, but now callers can make\nrequests to the new method. Because you didn't change the interface to the old\nmethods, your customers don't need to change and\nredeploy their clients; clients can continue to send requests to the old method\nthe same as before.\n\nIn **Endpoints** \\\u003e **Services** , the traffic served is now at version `1.1`. If\nyou select an earlier time range to display, it displays the previous version in\nthe graphs and logs, which provides a labeled history of your deployments.\n\n**Version 2.0**\n\nOver time, you realize that you need to make a backwards-incompatible change to\nan existing method. Because it's important that you don't break your customers'\nclient code, you decide to maintain two versions of the API. You leave the old\nmethod as it is, and implement the new version of the method. You create another\nOpenAPI configuration file for version 2.0, and configure the new version to be\nserved from `my-api.endpoints.my‐awesomeproject.cloud.goog/v2/echo`. Your\noriginal OpenAPI configuration file still points to the old version of the\nmethod, while the new OpenAPI configuration file points to the new version of\nthe method.\n\nYou deploy both version 1 and version 2 OpenAPI configuration files at the same\ntime, and redeploy the backend, which now contains both versions of the method.\n(See\n[Versioning an API](/endpoints/docs/openapi/versioning-an-api)\nfor details.)\n\nAfter you deploy, **Endpoints** \\\u003e **Services** shows that you are serving two\nversions of your API, and you can see how much traffic each version\nis getting. Your v1 clients can continue to call `/v1`, but they can also call\n`/v2` to use the new version of the method. How you handle versioning in your\nbackend code depends on the API framework you are using. For an example using\nservlets, see\n[Endpoints \\& Java with multiple versions sample](https://github.com/GoogleCloudPlatform/java-docs-samples/tree/master/endpoints/multiple-versions).\n\n**Disabling version 1**\n\nIn time, as your clients migrate and you see that all traffic to v1 has stopped,\nyou can stop serving it. To remove version 1 of your API, deploy only the\nversion 2 OpenAPI configuration file and redeploy the backend. You can now safely\nremove the code that implemented version 1 from your backend.\n**Endpoints** \\\u003e **Services** retains the historical data from version 1.x.\n\nStaging services\n----------------\n\nAs a best practice, we recommend that you stage updates to your\nEndpoints service so that you can test your service before it\nreaches your customers. We also recommend that you create a separate\nGoogle Cloud project for staging your service, so that it is isolated from\nproduction. For example, Google quotas are generally shared by resources within\na project. Thus, if you put the staging\nservice in the same project as the production service, an errant for loop, for\nexample, could cause an outage in your production service.\n\nWe recommend that you devise a Google Cloud project name that clearly\nindicates it is for staging. A common naming strategy is to use the same name as\nyour production Google Cloud project name, but with `-staging` at the end.\nYou might also want to put `-prod` on production projects to make it clear that\nthe project holds production services.\n\nService names on Google Cloud must be unique. Because you specify the name\nof the service in the OpenAPI configuration file, you need to either maintain\nseparate API configuration files for the staging and production projects, or use\none set of API configuration files and devise a process where you change the\nservice name to match the name of the project that you are deploying to.\n\nWhat's next\n-----------\n\n- [Endpoints \\& Java with multiple versions sample](https://github.com/GoogleCloudPlatform/java-docs-samples/tree/master/endpoints/multiple-versions)\n- [Planning your Google Cloud projects](/endpoints/docs/openapi/planning-cloud-projects)\n- [Versioning an API](/endpoints/docs/openapi/versioning-an-api)"]]
