Azure API Management의 버전

아티클
06/01/2023

적용 대상: 모든 API Management 계층

버전을 사용하면 관련 API 그룹을 개발자에게 제공할 수 있습니다. 버전을 사용하여 API의 호환성이 손상되는 변경을 안전하게 처리할 수 있습니다. 클라이언트는 준비가 되면 새 API 버전을 사용하도록 선택할 수 있지만 기존 클라이언트는 계속 이전 버전을 사용합니다. 버전은 버전 식별자(선택한 문자열 값)를 통해 구분되며 버전 관리 체계를 통해 클라이언트는 사용하려는 API 버전을 식별할 수 있습니다.

대부분의 경우 각 API 버전은 자체 독립 API로 간주될 수 있습니다. 서로 다른 두 API 버전에는 서로 다른 작업 집합과 다른 정책이 있을 수 있습니다.

버전을 사용하여 다음을 수행할 수 있습니다.

동시에 여러 버전의 API를 게시합니다.
경로, 쿼리 문자열 또는 헤더를 사용하여 버전을 구분합니다.
숫자, 날짜 또는 이름이 될 수 있는 버전을 식별할 문자열 값을 사용합니다.
개발자 포털에서 함께 그룹화된 API 버전을 표시합니다.
기존(버전이 지정되지 않은) API를 가져와 기존 클라이언트를 중단하지 않고 새 버전을 만듭니다.

안내에 따라 버전을 시작합니다.

버전 관리 체계

API 개발자마다 버전 관리에 대한 요구 사항이 다릅니다. Azure API Management는 버전 관리에 대한 단일 방법을 규정하지 않고 대신 여러 옵션을 제공합니다.

경로 기반 버전 관리

경로 버전 관리 체계를 사용하는 경우 버전 식별자는 모든 API 요청에 대한 URL 경로에 포함되어야 합니다.

예를 들어, https://apis.contoso.com/products/v1 및 https://apis.contoso.com/products/v2는 동일한 products API를 참조하지만 각각 버전 v1 및 v2를 참조할 수 있습니다.

경로 기반 버전 관리를 사용할 때 API 요청 URL의 형식은 https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}입니다.

헤더 기반 버전 관리

헤더 버전 관리 체계를 사용하는 경우 버전 식별자는 모든 API 요청에 대한 HTTP 요청 헤더에 포함되어야 합니다. HTTP 요청 헤더의 이름을 지정할 수 있습니다.

예를 들어 Api-Version이라는 사용자 지정 헤더를 만들고 클라이언트는 이 헤더 값에 v1 또는 v2를 지정할 수 있습니다.

쿼리 문자열 기반 버전 관리

쿼리 문자열 버전 관리 체계를 사용하는 경우 버전 식별자는 모든 API 요청에 대한 쿼리 문자열 매개 변수에 포함되어야 합니다. 쿼리 문자열 매개 변수의 이름을 지정할 수 있습니다.

쿼리 문자열 기반 버전 관리를 사용할 때 API 요청 URL의 형식은 https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}입니다.

예를 들어, https://apis.contoso.com/products?api-version=v1 및 https://apis.contoso.com/products?api-version=v2는 동일한 products API를 참조하지만 각각 버전 v1 및 v2를 참조할 수 있습니다.

참고 항목

OpenAPI 사양의 servers 속성에는 쿼리 매개 변수가 허용되지 않습니다. API 버전에서 OpenAPI 사양을 내보내면 쿼리 문자열이 서버 URL에 표시되지 않습니다.

원본 버전

버전이 지정되지 않은 API에 버전을 추가하면 Original 버전이 자동으로 만들어지고 지정된 버전 식별자 없이 기본 URL에 응답합니다. Original 버전은 기존 호출자가 버전을 추가하는 과정에서 손상되지 않도록 합니다. 시작 시 버전이 사용하도록 설정된 새 API를 만들면 Original 버전이 만들어지지 않습니다.

버전 표시 방법

Azure API Management는 단일 논리적 API의 버전 집합을 나타내는 버전 집합이라는 리소스를 유지 관리합니다. 버전 집합에는 버전이 지정된 API의 표시 이름과 요청을 지정된 버전으로 보내는 데 사용되는 버전 관리 체계가 포함됩니다.

API의 각 버전은 고유한 API 리소스로 유지 관리되며, 이 리소스는 버전 집합과 연결됩니다. 버전 집합에는 다른 작업 또는 정책이 있는 API가 포함될 수 있습니다. 집합의 버전 간에 중요한 변경을 수행할 수 있습니다.

Azure Portal은 버전 집합을 만듭니다. Azure Portal에서 설정한 버전의 이름과 설명을 수정할 수 있습니다.

최종 버전이 삭제되면 버전 집합이 자동으로 삭제됩니다.

Azure CLI, Azure PowerShell, Resource Manager 템플릿 또는 Azure Resource Manager API를 사용하여 버전 집합을 직접 보고 관리할 수 있습니다.

참고 항목

버전 관리 집합의 모든 버전 관리는 API에 버전 관리를 처음 추가할 때 사용된 버전 관리 체계를 기반으로 동일한 버전 관리 체계를 갖습니다.

버전이 없는 API를 버전이 있는 API로 마이그레이션

Azure Portal을 사용하여 기존 API에서 버전 관리를 사용하도록 설정하면 API Management 리소스가 다음과 같이 변경됩니다.

새 버전 집합이 만들어집니다.
기존 버전이 유지되고 Original API 버전으로 구성됩니다. API는 버전 집합에 연결되지만 버전 식별자를 지정할 필요는 없습니다.
새 버전은 새 API로 만들어지고 버전 집합에 연결됩니다. 이 새 API는 버전 관리 체계와 식별자를 사용하여 액세스해야 합니다.

버전 및 수정 버전

버전 및 수정 버전은 별개의 기능입니다. 각 버전에는 버전이 없는 API와 마찬가지로 여러 개의 수정 버전이 있을 수 있습니다. 버전을 사용하지 않고 수정 버전을 사용하거나 다른 방법을 사용할 수 있습니다. 일반적으로 버전은 API 버전을 주요 변경 내용과 구분하는 데 사용되고, 수정 버전은 API에 대한 사소한 변경 내용에 사용할 수 있습니다.

수정 버전에 호환성이 손상되는 변경이 포함되어 있거나, 정식으로 수정 버전을 베타/테스트 버전으로 전환하려는 경우 수정 버전에서 버전을 만들 수 있습니다. Azure Portal을 사용하여 수정 버전 탭의 수정 버전 상황에 맞는 메뉴에서 '수정 버전에서 버전 만들기'를 클릭합니다.

개발자 포털

개발자 포털에는 API의 각 버전이 별도로 나열됩니다.

버전이 지정된 API 목록을 표시하는 API Management 개발자 포털

API 세부 정보에는 해당 API의 모든 버전 목록도 표시됩니다. 버전 식별자 없이 Original 버전이 표시됩니다.

API의 세부 정보 및 해당 API에 대한 버전 목록을 표시하는 API Management 개발자 포털

팁

API 버전은 개발자 포털에 표시되기 전에 제품에 추가해야 합니다.

다음을 통해 공유