Azure API Management에서의 버전

적용 대상: 모든 API Management 계층

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

대부분의 경우 각 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 버전을 가리킬 수 있습니다.

원래 버전

버전이 아닌 API Original 에 버전을 추가하는 경우 버전 식별자가 지정되지 않은 상태에서 버전이 자동으로 만들어지고 기본 URL에 응답합니다. 버전은 Original 기존 호출자가 버전을 추가하는 프로세스의 영향을 받지 않도록 합니다. 새 API를 생성할 때 처음부터 버전이 활성화되어 있으면 Original 버전이 생성되지 않습니다.

버전을 나타내는 방법

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

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

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

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

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

버전이 아닌 API를 버전이 지정된 API로 마이그레이션

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

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

버전 및 수정

버전 및 수정 버전은 고유한 기능입니다. 버전이 아닌 API와 마찬가지로 각 버전에 여러 수정 버전이 있을 수 있습니다. 버전을 사용하지 않고 수정 버전을 사용하거나 다른 방법으로 수정 버전을 사용할 수 있습니다. 일반적으로 버전은 호환성이 손상되는 변경 내용이 있는 API 버전을 구분하는 데 사용되며 수정 버전을 API의 사소한 변경 및 호환성이 손상되지 않는 변경에 사용할 수 있습니다.

수정 버전에 호환성이 손상되는 변경 내용이 있거나 수정 버전을 베타/테스트 버전으로 공식적으로 전환하려는 경우 수정 버전에서 버전을 만들 수 있습니다. Azure 포털의 수정 탭에서 수정 상황에 맞는 메뉴(...)의 이 수정에서 버전 만들기를 선택합니다.

개발자 포털

개발자 포털은 API의 각 버전을 별도로 나열합니다.

API에 대한 세부 정보에서 API의 모든 버전 목록을 볼 수도 있습니다. Original 버전은 버전 식별자 없이 표시됩니다.