이 페이지에서는 Cloud Endpoints API 버전 관리 기능을 설명하고 Endpoints API 버전 관리 및 스테이징의 권장사항을 제공합니다. 이 페이지의 정보는 OpenAPI 사양을 사용하는 API에 적용됩니다.
App Engine 표준 환경용 Cloud Endpoints 프레임워크를 사용하는 API는 API 버전 관리 처리: 자바 또는 API 버전 관리 처리: Python을 참조하세요.
API 버전 관리 및 서비스 스테이징을 위해 Google에서 사용되는 동일한 기본 원칙을 따르는 것이 좋습니다.
최초 버전을 배포하기 전에 OpenAPI 구성 파일에 다음을 포함합니다.
info.version 필드에서 버전 번호를 설정합니다.
주 버전과 부 버전이 포함된 버전 문자열(예: 1.0)을 사용하는 것이 좋습니다.
주 버전 번호를 포함하도록 basePath 필드를 설정합니다.
v 문자 뒤에 주 버전 번호가 있는 기본 경로 형식(예: /v1)을 사용하는 것이 좋습니다.
새 메서드 추가와 같이 이전 버전과 호환되는 변경을 수행해야 하는 경우에는 info.version 필드에서 부 버전 번호(예: 1.2, 1.3)를 증가시키고 다시 배포합니다. 자세한 내용은 API 버전 관리를 참조하세요.
기존 메서드에 대한 변경사항이 클라이언트 코드에 문제를 일으키는 경우에는 OpenAPI 구성 파일을 복사하고 다음과 같이 변경합니다.
info.version 필드에서 주 버전 번호(예: 2.0, 3.0)를 증가시킵니다.
basePath 필드에서 주 버전 번호(예: /v2, /v3)를 증가시킵니다.
OpenAPI 구성 파일의 두 버전을 배포하고 백엔드를 다시 배포합니다. 이제 메서드의 두 버전이 모두 포함됩니다. 자세한 내용은 API 버전 관리를 참조하세요.
단일 백엔드에서 모든 주 API 버전을 구현합니다. 권장사항은 다음과 같습니다.
특정 버전에 대한 요청은 경로를 토대로 하므로 위 예와 같이 라우팅을 간소화합니다.
구성 및 배포를 간소화합니다. API의 모든 주 버전에 동일한 Google Cloud 프로젝트와 백엔드를 사용하고 모든 API 버전을 동시에 배포합니다.
너무 많은 백엔드 실행을 방지하여 비용을 줄입니다.
프로덕션 Google Cloud 프로젝트에 배포하기 전에 개별 Google Cloud 프로젝트에서 API를 스테이징합니다. 자세한 내용은 서비스 스테이징을 참조하세요.
Endpoints에서 사용되는 주 버전 번호 및 부 버전 번호는 체계적인 버전 관리에 있는 정의를 따릅니다. Endpoints는 백엔드 코드의 버그 수정을 배포할 때 OpenAPI 구성 파일의 패치 버전 번호를 높이고 구성을 배포하도록 규정하지 않지만, 필요하다면 그렇게 할 수 있습니다.
Cloud Endpoints API 버전 관리 기능
Extensible Service Proxy(ESP)에는 API의 경로가 겹치지 않는 한 단일 Google Cloud 프로젝트와 백엔드에 속한 API의 여러 주 버전을 동시에 관리하는 기능이 있습니다. 예를 들면 다음과 같습니다.
따라서 고객은 사용할 버전을 자유롭게 선택하고 새 버전으로 이전하는 시점을 제어할 수 있습니다. ESP는 백엔드의 해당 메소드로 요청을 라우팅하기 전에 각 요청에 버전 번호를 태그로 지정합니다. 각 요청에 버전 번호가 태그로 지정되었으므로, 다음이 수행됩니다.
Endpoints > 서비스의 그래프와 로그에 주 API 버전 각각에서 들어오는 요청 및 모든 버전을 집계한 합이 표시됩니다. 보기를 특정 버전으로 필터링할 수 있습니다. 그러면 각 버전이 사용 중인 트래픽 양을 명확하게 확인할 수 있습니다. 로그에서 어떤 클라이언트가 어떤 버전을 사용하는지도 확인할 수 있습니다.
부 버전 번호를 업데이트하여 API를 다시 배포하면 그래프 및 로그에서 이후 작업에 새 버전 번호로 라벨이 지정됩니다. 이를 통해 라벨로 표시된 배포 기록을 확인할 수 있습니다.
API 버전을 삭제하면 해당 API가 사용된 시간 범위의 데이터가 그래프 및 로그에 계속 표시됩니다.
API 수명 주기 예
이 섹션에서는 서비스의 일반적인 발전 과정을 설명합니다.
버전 1
My Awesome Echo API 서비스의 버전 1을 최초로 배포합니다. API는 my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo에서 제공됩니다. Endpoints > 서비스의 그래프 및 로그에서 모든 트래픽이 1.0으로 확인됩니다.
버전 1.1
고객이 새로운 기능을 요청하여 새 메서드를 추가합니다. OpenAPI 구성 파일에서 새 메서드를 추가하고 info.version 필드를 1.1로 증가시킵니다. 이 변경사항은 클라이언트 코드에 문제를 일으키지 않으므로 부 버전 번호를 증가시킵니다. 스테이징 환경에서 변경 사항을 배포하고 테스트하여 작동하는지 확인합니다.
그런 다음 OpenAPI 구성과 API 백엔드를 프로덕션 환경에 배포합니다. API가 여전히 my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo에서 제공되지만 호출자는 이제 새 메서드에 요청을 수행할 수 있습니다. 이전 메서드에 대한 인터페이스를 변경하지 않았으므로 고객은 클라이언트를 변경하여 재배포할 필요가 없습니다. 클라이언트는 이전과 동일하게 이전 메서드로 요청을 계속 보낼 수 있습니다.
Endpoints > 서비스에서 제공되는 트래픽이 이제 1.1 버전으로 표시됩니다. 이전 시간 범위를 선택하여 표시하면 그래프 및 로그에 이전 버전이 표시되므로 라벨이 지정된 배포 기록을 확인할 수 있습니다.
버전 2.0
시간이 경과하면 이전 버전과 호환되지 않는 방식으로 기존 메서드를 변경해야 한다는 것을 알게 됩니다. 고객의 클라이언트 코드가 손상되지 않는 것이 중요하므로 API를 두 가지 버전으로 유지보수하기로 결정합니다. 이전 메서드는 그대로 놔두고 새 버전의 메서드를 구현합니다. 버전 2.0에 또 다른 OpenAPI 구성 파일을 만들고 새 버전이 my-api.endpoints.my‐awesomeproject.cloud.goog/v2/echo에서 제공되도록 구성합니다. 원래 OpenAPI 구성 파일은 여전히 이전 버전의 메서드에 연결되지만 새로운 OpenAPI 구성 파일은 새 버전의 메서드에 연결됩니다.
버전 1 및 버전 2의 OpenAPI 구성 파일을 동시에 배포하고, 백엔드를 다시 배포하여 두 버전의 메소드가 포함되도록 합니다.
자세한 내용은 API 버전 관리를 참조하세요.
배포 후에는 Endpoints > 서비스에 두 가지 버전의 API가 제공되고 있는 것으로 표시되고, 각 버전이 사용하는 트래픽 양을 확인할 수 있습니다. v1 클라이언트는 /v1을 계속 호출할 수 있지만 /v2를 호출하여 새 버전의 메서드를 사용할 수도 있습니다. 백엔드 코드에서 버전 관리를 처리하는 방법은 사용 중인 API 프레임워크에 따라 다릅니다. 서블릿을 사용하는 예시는 여러 버전이 포함된 Endpoints 및 자바 샘플을 참조하세요.
버전 1 중지
시간이 지나서 클라이언트가 이전되고 v1에 대한 모든 트래픽이 중지된 것으로 확인되면, v1 제공을 중지할 수 있습니다. 버전 1의 API를 삭제하려면 버전 2 OpenAPI 구성 파일만 배포하고 백엔드를 다시 배포합니다. 이제 백엔드에서 버전 1을 구현했던 코드를 안전하게 삭제할 수 있습니다.
Endpoints > 서비스에는 버전 1.x의 기록 데이터가 보존됩니다.
서비스 스테이징
고객에게 서비스를 배포하기 전에 테스트할 수 있도록 Endpoints 서비스에 대한 업데이트를 스테이징하는 것이 좋습니다. 또한 프로덕션과의 격리를 위해 서비스 스테이징용 Google Cloud 프로젝트를 별도로 만드는 것이 좋습니다. 예를 들어 Google 할당량은 일반적으로 프로젝트 내의 리소스를 통해 공유됩니다. 따라서 스테이징 서비스를 프로덕션 서비스와 동일한 프로젝트에 넣으면 잘못된 루프 등으로 인해 프로덕션 서비스가 중단될 수 있습니다.
Google Cloud 프로젝트 이름을 스테이징용임을 명확하게 나타내는 이름으로 지정하는 것이 좋습니다. 일반적인 명명법은 프로덕션 Google Cloud 프로젝트 이름을 그대로 사용하면서 뒤에 -staging을 붙이는 방법입니다.
또한 프로젝트에 프로덕션 서비스가 포함되었음을 명시하기 위해 프로덕션 프로젝트에 -prod를 붙일 수도 있습니다.
Google Cloud의 서비스 이름은 고유해야 합니다. OpenAPI 구성 파일에서 서비스 이름을 지정하므로 스테이징 및 프로덕션 프로젝트에 별도의 API 구성 파일을 유지보수하거나, API 구성 파일 집합 한 개를 사용하고 배포 중인 프로젝트의 이름과 일치하도록 서비스 이름을 변경하는 프로세스를 고안해야 합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2024-12-21(UTC)"],[[["\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)"]]
