이 페이지에서는 API의 버전 관리 방법과 여러 버전으로 배포하는 방법에 대해 설명합니다.
API 버전 관리 권장사항
API 버전을 관리할 때 다음과 같은 권장사항을 고려하세요.
- 증분 방식이지만 이전 버전과 호환되는 변경사항을 적용하려면 API 버전을 일정하게 유지하고 기존 API 위에 배포합니다.
- API에 브레이킹 체인지를 적용하려면 API 버전을 높입니다.
- 더 안전하게 보호하려면 App Engine 애플리케이션 버전도 높인 다음 이 새로운 App Engine 애플리케이션 버전에 새 API 버전을 배포합니다. 이렇게 하면 App Engine 특유의 유연성을 활용하여 App Engine의 여러 버전 간에 빠르게 전환할 수 있으며, 예상치 못한 문제가 발생할 경우 정상적인 기존 버전에서 서비스를 제공할 수 있습니다.
다음 표에서는 여러 App Engine 앱 버전에 따른 백엔드 API 버전을 단계식으로 보여줍니다.
| 애플리케이션 버전 | 백엔드 API 버전 |
|---|---|
| 1 |
|
| 2 |
|
| 3 |
|
표에서 볼 수 있듯이 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 버전에 액세스할 수 있습니다.
제공 버전은 Google Cloud 콘솔에서 명시적으로 변경될 때까지 그대로 유지됩니다.
비제공 애플리케이션 버전에 배포된 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을 사용합니다.
자세한 내용은 App Engine 문서를 참조하세요.
비제공 서비스(이전 명칭은 모듈)에 배포된 API 버전에 액세스
기본 App Engine 서비스에 배포되지 않은 API 버전에 액세스해야 하는 경우 다음과 같이 점 구문을 사용하는 서비스별 URL을 사용합니다.
https://SERVICE-NAME-dot-YOUR_PROJECT_ID.appspot.com/_ah/api/...
자세한 내용은 App Engine 문서를 참조하세요.