이 페이지에서는 API의 버전 관리 방법과 여러 버전으로 배포하는 방법에 대해 설명합니다.
API 버전 관리 권장사항
API 버전을 관리할 때 다음과 같은 권장사항을 고려하세요.
증분 방식이지만 이전 버전과 호환되는 변경사항을 적용하려면 API 버전을 일정하게 유지하고 기존 API 위에 배포합니다.
API에 브레이킹 체인지를 적용하려면 API 버전을 높입니다.
더 안전하게 보호하려면 App Engine 애플리케이션 버전도 높인 다음 이 새로운 App Engine 애플리케이션 버전에 새 API 버전을 배포합니다. 이렇게 하면 App Engine 특유의 유연성을 활용하여 App Engine의 여러 버전 간에 빠르게 전환할 수 있으며, 예상치 못한 문제가 발생할 경우 정상적인 기존 버전에서 서비스를 제공할 수 있습니다.
다음 표에서는 여러 App Engine 앱 버전에 따른 백엔드 API 버전을 단계식으로 보여줍니다.
애플리케이션 버전
백엔드 API 버전
1
v1 --> v1 (2) --> v1 (n)
2
v1 (n)
v2 --> v2 (2) --> v2 (n)
3
v1 (n)
v2 (n)
v3 --> v3 (2) --> v3 (n)
표에서 볼 수 있듯이 API v1에 증분 방식이지만 이전 버전과 호환되는 업데이트가 배포되면 각 업데이트가 이전 버전을 덮어씁니다. 브레이킹 체인지가 적용될 경우 API 버전이 v2로 증가되어 새로운 App Engine 애플리케이션 버전에 배포됩니다. 따라서 필요한 경우 이전 애플리케이션 버전으로 다시 전환할 수 있습니다.
표에 따르면 애플리케이션 버전 2는 API의 최신 v1 버전과 새로운 v2 버전을 모두 지원합니다. 프로젝트에서 기존 v1 코드를 삭제하지 않으면 프로젝트를 배포할 때 API의 v2 및 vl(n)이 모두 애플리케이션 버전 2로 배포됩니다.
여러 애플리케이션 버전에 배포
백엔드 API를 배포할 때는 API용으로 만든 Google Cloud 프로젝트의 프로젝트 ID에 배포하고 배포할 대상 App Engine 버전도 지정해야 합니다.
App Engine 앱 버전은 /WEB-INF/appengine-web.xml 파일의 <version> 요소에 지정합니다. App Engine 앱 버전은 @Api 주석의 version 인수에 지정하는 백엔드 API 버전 번호와 다릅니다.
위 그림과 같이, 동일한 App Engine 버전에 여러 API 버전을 배포할 수 있습니다. 또한 애플리케이션 하나에 여러 App Engine 버전이 있을 수 있습니다.
제공 버전에 배포된 API 버전에 액세스
API를 배포하는 첫 번째 대상 App Engine 버전이 제공 버전입니다. 이 버전은 URL http://YOUR_PROJECT_ID.appspot.com에서 실행됩니다. 여기서 YOUR_PROJECT_ID는 Google Cloud 프로젝트 ID를 나타냅니다. 이 URL을 사용하여 해당 App Engine 애플리케이션 버전에 배포된 모든 API 버전에 액세스할 수 있습니다.
현재 제공 중인 App Engine 버전에 배포되지 않은 API 버전에 액세스해야 하는 경우 다음과 비슷한 버전별 URL을 사용합니다.
https://VERSION-dot-YOUR_PROJECT_ID.appspot.com
VERSION을 App Engine 버전으로, YOUR_PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다. 예를 들어 App Engine 제공 버전이 1이지만 버전 2에 배포된 API 버전에 액세스하려는 경우에는 URL https://2-dot-YOUR_PROJECT_ID.appspot.com을 사용합니다.
[[["이해하기 쉬움","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\u003eWhen introducing non-breaking changes to an API, keep the API version the same and deploy over the existing API.\u003c/p\u003e\n"],["\u003cp\u003eWhen a breaking change is made to an API, increment the API version and, for extra precaution, increment the App Engine application version as well.\u003c/p\u003e\n"],["\u003cp\u003eMultiple API versions can be deployed to the same App Engine version, and multiple App Engine versions can exist for an application.\u003c/p\u003e\n"],["\u003cp\u003eThe serving version of an API is accessed via \u003ccode\u003ehttp://YOUR_PROJECT_ID.appspot.com\u003c/code\u003e, while non-serving API versions use a version-specific URL like \u003ccode\u003ehttps://VERSION-dot-YOUR_PROJECT_ID.appspot.com\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eNon-default service deployments can be accessed using the following URL format \u003ccode\u003ehttps://SERVICE-NAME-dot-YOUR_PROJECT_ID.appspot.com/_ah/api/...\u003c/code\u003e.\u003c/p\u003e\n"]]],[],null,["# Handling API versioning\n\nThis page describes how to do versioning for your API and how to deploy to\nmultiple versions.\n\nRecommendations for managing API versions\n-----------------------------------------\n\nIn managing your API versions, consider these recommendations:\n\n- When you want to introduce an incremental, but non-breaking change, keep the API version constant and deploy over the existing API.\n- When you introduce a breaking change to your API, increment the API version.\n- For additional protection, increment the App Engine application version as well, and then deploy the new API version to that new App Engine application version. This lets you use the built-in flexibility of App Engine to quickly switch between App Engine versions and serve from the old working versions if you run into unexpected problems.\n\nThe following table is an illustration of cascading backend API versions to\ndifferent App Engine application versions.\n\nAs shown in the table, incremental, non-breaking updates to v1 of the API are\nrolled out, each overwriting the previous version. When breaking changes are\nintroduced, the API version is incremented to v2 and it is deployed to a new\nApp Engine application version. That allows you to switch back to the\nprevious applications version if needed.\n\nIn the table, notice that application version 2 supports both the latest v1 version\nand the new v2 version of your API. If you don't delete the existing v1 code\nfrom your project, when you deploy the project both `v2` and `vl` (n)\nof your API are deployed to version 2 of your application.\n\nDeploying to multiple application versions\n------------------------------------------\n\nWhen you deploy your backend API, you deploy it to the project ID of the\nGoogle Cloud project you created for your API, and you must also\nspecify the App Engine version you deploy to.\n\nYou specify the App Engine app version in the `\u003cversion\u003e` element of the\n[`/WEB-INF/appengine-web.xml`](/appengine/docs/standard/java/config/appref)\nfile. The App Engine app version isn't the same thing as the backend API\nversion number, which you specify in the `version` attribute of the `@Api`\nannotation.\n\nAs shown in the preceding figure, you can deploy multiple API versions to the\nsame App Engine version. And, you can have many App Engine\nversions for an application.\n\n### Accessing API versions deployed to a serving version\n\nThe first\n[App Engine version](/appengine/docs/python/an-overview-of-app-engine#versions_and_instances)\nthat you deploy your API to is the serving version. This version runs at the URL\n`http://`\u003cvar translate=\"no\"\u003eYOUR_PROJECT_ID\u003c/var\u003e`.appspot.com` where\n\u003cvar translate=\"no\"\u003eYOUR_PROJECT_ID\u003c/var\u003e represents your Google Cloud\nproject ID. You can access all of the API versions deployed to that\nApp Engine application version by using that URL.\n\nThe serving version remains the same until you explicitly change it, in the\n[Google Cloud console](https://console.cloud.google.com/appengine/versions).\n\n### Accessing API versions deployed to a non-serving application version\n\nIf you need to access API versions that are *not* deployed to the currently\nserving App Engine version, you use a *version-specific* URL, similar to\nthe following: \n\n```\nhttps://VERSION-dot-YOUR_PROJECT_ID.appspot.com\n```\n\nReplace \u003cvar translate=\"no\"\u003eVERSION\u003c/var\u003e with your App Engine version,\nand \u003cvar translate=\"no\"\u003eYOUR_PROJECT_ID\u003c/var\u003e with your Google Cloud project\nID. For example, suppose your App Engine serving version\nis 1, but you want to access an API version deployed to version 2. You would\nuse this URL: `https://2-dot-`\u003cvar translate=\"no\"\u003eYOUR_PROJECT_ID\u003c/var\u003e`.appspot.com`.\n| **Important:** For backend APIs, only host names formed using `-dot-` in place of literal periods work for versioned apps.\n\nFor more details, see the\n[App Engine documentation](/appengine/docs/standard/python/how-requests-are-routed).\n\n### Accessing API versions deployed to non-serving services (previously modules)\n\nIf you need to access API versions that are *not* deployed to the default\nApp Engine service, you can use a *service-specific* URL using the dot\nsyntax as follows: \n\n```\nhttps://SERVICE-NAME-dot-YOUR_PROJECT_ID.appspot.com/_ah/api/...\n```\n\nFor more details, see the\n[App Engine documentation](/appengine/docs/standard/python/how-requests-are-routed)."]]
