다음을 통해 공유

API Management의 백 엔드

적용 대상: 모든 API Management 계층

API Management의 백 엔드(또는 API 백 엔드)는 프런트 엔드 API와 해당 작업을 구현하는 HTTP 서비스입니다.

특정 API를 가져올 경우 API Management는 자동으로 API 백 엔드를 구성합니다. 예를 들어 API Management는 다음을 가져올 때 백 엔드 웹 서비스를 구성합니다.

API Management는 다음과 같은 다른 Azure 리소스를 API 백 엔드로 사용하는 것도 지원합니다.

백 엔드 이점

API Management는 API의 백 엔드 서비스를 관리할 수 있도록 백 엔드 엔터티를 지원합니다. 백 엔드 엔터티는 백 엔드 서비스에 대한 정보를 캡슐화하고 API와 향상된 거버넌스에서 재사용을 승격합니다.

다음 중 하나 이상에 백 엔드를 사용합니다.

  • 백 엔드 서비스에 대한 요청의 자격 증명 권한 부여
  • 헤더나 쿼리 매개 변수 인증에 명명된 값이 구성된 경우 API Management 기능을 활용하여 Azure Key Vault에서 비밀을 유지합니다.
  • 너무 많은 요청으로부터 백 엔드를 보호하기 위한 회로 차단기 규칙 정의
  • 요청을 여러 백 엔드로 라우팅 또는 부하 분산

Azure Portal에서 또는 Azure API 또는 도구를 사용하여 백 엔드 엔터티를 구성 및 관리합니다.

백 엔드 만들기

Azure Portal에서 또는 Azure API 또는 도구를 사용하여 백 엔드를 만들 수 있습니다.

포털에서 백 엔드를 만들려면 다음을 수행합니다.

  1. 포털에 로그인하고 API Management 인스턴스로 이동합니다.
  2. 왼쪽 메뉴에서 API>백 엔드> 만들기를 선택합니다.
  3. 백 엔드 페이지에서 다음을 수행합니다.
    1. 백 엔드의 이름과 설명(선택 사항)을 입력 합니다.
    2. 예를 들어 함수 앱 또는 논리 앱, 사용자 지정 서비스의 사용자 지정 URL 또는 Service Fabric 클러스터와 같은 Azure 리소스에 대한 Azure 리소스와 같은 백 엔드 호스팅 유형을 선택합니다.
    3. 런타임 URL에서 API 요청이 전달되는 백 엔드 서비스의 URL을 입력합니다.
    4. 고급에서 필요에 따라 백 엔드에 대한 인증서 체인 또는 인증서 이름 유효성 검사를 사용하지 않도록 설정합니다.
    5. 백 엔드 풀에 이 백 엔드 서비스 추가에서 필요에 따라 백 엔드에 대한 부하 분산 풀을 선택하거나 만듭니다.
    6. 회로 차단기 규칙에서 필요에 따라 백 엔드에 대한 회로 차단기를 구성합니다.
    7. 권한 부여 자격 증명에서 필요에 따라 백 엔드에 대한 액세스 권한을 부여하도록 자격 증명을 구성합니다. 옵션에는 요청 헤더, 쿼리 매개 변수, 클라이언트 인증서 또는 API Management 인스턴스에 구성된 시스템 할당 또는 사용자 할당 관리 ID 가 포함됩니다.
    8. 선택하고생성합니다.

백 엔드를 만든 후 언제든지 백 엔드 설정을 업데이트할 수 있습니다. 예를 들어 회로 차단기 규칙을 추가하거나, 런타임 URL을 변경하거나, 권한 부여 자격 증명을 추가합니다.

권한 부여 자격 증명에 대한 관리 ID 구성

API Management 인스턴스에 구성된 시스템 할당 또는 사용자 할당 관리 ID 를 사용하여 백 엔드 서비스에 대한 액세스 권한을 부여할 수 있습니다. 권한 부여 자격 증명에 대한 관리 ID를 구성하려면 다음을 수행합니다.

  1. 백 엔드 구성의 권한 부여 자격 증명 섹션에서 관리 ID 탭을 선택하고 사용을 선택합니다.

  2. 클라이언트 ID에서 시스템 할당 ID 또는 인스턴스에 구성된 사용자 할당 ID를 선택합니다.

  3. 리소스 ID에 대상 Azure 서비스 또는 백 엔드를 나타내는 Microsoft Entra 애플리케이션의 애플리케이션 ID를 입력합니다. 예: https://cognitiveservices.azure.com Azure OpenAI 서비스의 경우

    자세한 예제는 인증 관리 ID 정책 참조를 참조하세요.

  4. 선택하고생성합니다.

참고 항목

또한 관리 ID에 적절한 권한 또는 RBAC 역할을 할당하여 백 엔드 서비스에 액세스합니다. 예를 들어 백 엔드가 Azure OpenAI 서비스인 경우 관리 ID에 역할을 할당할 Cognitive Services User 수 있습니다.

set-backend-service 정책을 사용하여 백 엔드 참조

백 엔드를 만든 후 API에서 백 엔드 식별자(이름)를 참조할 수 있습니다. set-backend-service 정책을 사용하여 들어오는 API 요청을 백 엔드로 보냅니다. API에 대한 백 엔드 웹 서비스를 이미 구성한 경우 set-backend-service 정책을 사용하여 대신 백 엔드 엔터티로 요청을 리디렉션할 수 있습니다. 예시:

<policies>
    <inbound>
        <base />
        <set-backend-service backend-id="myBackend" />
    </inbound>
    [...]
<policies/>

참고 항목

또는 base-url를 사용할 수 있습니다. 일반적으로 형식은 .입니다 https://backend.com/api. 잘못된 구성을 방지하려면 끝에 슬래시를 추가하지 마십시오. 일반적으로 백 엔드의 base-url HTTP(S) 엔드포인트 값이 일치하여 프런트 엔드와 백 엔드 간에 원활한 통합을 사용하도록 설정해야 합니다. API Management 인스턴스는 백 엔드 서비스 이름을 에 추가합니다 base-url.

set-backend-service 정책과 함께 조건부 논리를 사용하여 위치, 호출된 게이트웨이 또는 기타 식에 따라 유효 백 엔드를 변경할 수 있습니다.

예를 들어 호출된 게이트웨이를 기준으로 트래픽을 다른 백 엔드로 라우팅하는 정책은 다음과 같습니다.

<policies>
    <inbound>
        <base />
        <choose>
            <when condition="@(context.Deployment.Gateway.Id == "factory-gateway")">
                <set-backend-service backend-id="backend-on-prem" />
            </when>
            <when condition="@(context.Deployment.Gateway.IsManaged == false)">
                <set-backend-service backend-id="self-hosted-backend" />
            </when>
            <otherwise />
        </choose>
    </inbound>
    [...]
<policies/>

회로 차단기

API Management는 백 엔드 리소스에 회로 차단기 속성을 노출하여 백 엔드 서비스가 너무 많은 요청에 의해 과부하되지 않도록 보호합니다.

  • 회로 차단기 속성은 정의된 시간 간격 동안의 오류 조건 수 또는 백분율, 오류를 나타내는 상태 코드 범위와 같이 회로 차단기를 발생시키는 규칙을 정의합니다.
  • 회로 차단기가 발생되면 API Management는 정의된 시간 동안 백 엔드 서비스에 대한 요청 전송을 중지하고 클라이언트에 503 서비스를 사용할 수 없음 응답을 반환합니다.
  • 구성된 발생 기간이 지나면 회로가 다시 설정되고 트래픽이 백 엔드로 다시 시작됩니다.

백 엔드 회로 차단기는 백 엔드가 오버로드 상황에서 복구할 수 있도록 하는 회로 차단기 패턴의 구현입니다. API Management 게이트웨이 및 백 엔드 서비스를 보호하기 위해 구현할 수 있는 일반적인 속도 제한 및 동시성 제한 정책을 보강합니다.

참고 항목

  • 현재 백 엔드 회로 차단기는 API Management의 소비 계층에서 지원되지 않습니다.
  • API Management 아키텍처의 분산 특성으로 인해 회로 차단기 발생 규칙은 근사값입니다. 게이트웨이의 다른 인스턴스는 동기화되지 않으며 동일한 인스턴스의 정보에 따라 회로 차단기 규칙을 적용합니다.
  • 현재 백 엔드 회로 차단기에 대해 하나의 규칙만 구성할 수 있습니다.

예시

Azure Portal, API Management REST API 또는 Bicep 또는 ARM 템플릿을 사용하여 백 엔드에서 회로 차단기를 구성합니다. 다음 예제에서는 한 시간내 서버 오류를 나타내는 세 개 이상의 상태 코드가 있는 경우 API Management 인스턴스 myAPIM 트립의 5xx에 있는 회로 차단기가 발생합니다.

이 예제의 회로 차단기는 1시간 후에 다시 설정됩니다. 응답에 Retry-After 헤더가 있는 경우 회로 차단기는 값을 수락하고 백 엔드에 요청을 다시 보내기 전에 지정된 시간 동안 기다립니다.

  1. Azure Portal에서 API Management 인스턴스로 이동합니다.
  2. 왼쪽 메뉴에서 API>백엔드>를 선택하고 백엔드를 선택하십시오.
  3. 백 엔드 페이지에서 설정>회로 차단기 설정>새로 추가를 선택합니다.
  4. 새 회로 차단기 만들기 페이지에서 규칙을 구성합니다.
    • 규칙 이름: myBackend와 같은 규칙의 이름을 입력합니다.
    • 실패 횟수: 3을 입력합니다.
    • 실패 간격: 기본값인 1시간을 그대로 둡니다.
    • 오류 상태 코드 범위: 500 - 599를 선택합니다.
    • 여정 기간: 기본값인 1시간을 그대로 둡니다.
    • HTTP 응답에서 'Retry-After' 헤더를 선택합니다. True(수락)를 선택합니다.

부하 분산 풀

API Management는 API에 대한 여러 백 엔드를 구현하고 해당 백 엔드에서 요청을 부하 분산하려는 경우 백 엔드풀을 지원합니다. 풀은 부하 분산을 위해 단일 엔터티로 처리되는 백 엔드의 컬렉션입니다.

다음과 같은 시나리오에 백 엔드 풀을 사용합니다.

  • 부하를 여러 백 엔드로 분산합니다. 이 백 엔드에는 개별 백 엔드 회로 차단기가 있을 수 있습니다.
  • 업그레이드를 위해 한 백 엔드 집합에서 다른 백 엔드 집합으로 부하를 이동합니다(파란색-녹색 배포).

참고 항목

  • 풀에 최대 30개의 백 엔드를 포함할 수 있습니다.
  • API Management 아키텍처의 분산 특성으로 인해 백 엔드 부하 분산은 근사값입니다. 게이트웨이의 다른 인스턴스는 동기화되지 않으며 동일한 인스턴스의 정보에 따라 부하를 분산합니다.

부하 분산 옵션

API Management는 백 엔드 풀에 대해 다음과 같은 부하 분산 옵션을 지원합니다.

부하 분산 옵션 설명
라운드 로빈 요청은 기본적으로 풀의 백 엔드에 균등하게 분산됩니다.
가중치 적용 가중치는 풀의 백 엔드에 할당되고 요청은 각 백 엔드의 상대적 가중치에 따라 분산됩니다. 청록색 배포와 같은 시나리오에 유용합니다.
우선 순위 기반 백 엔드는 우선 순위 그룹으로 구성됩니다. 요청은 우선 순위가 높은 그룹으로 먼저 전송됩니다. 그룹 내에서 요청은 균등하게 또는 할당된 가중치에 따라 분산됩니다.

참고 항목

우선 순위가 낮은 그룹의 백 엔드는 회로 차단기 규칙이 트립되기 때문에 우선 순위가 높은 그룹의 모든 백 엔드를 사용할 수 없는 경우에만 사용됩니다.

세션 인식

위의 부하 분산 옵션을 사용하면 필요에 따라 세션 인식(세션 선호도)을 사용하도록 설정하여 세션 중 특정 사용자의 모든 요청이 풀의 동일한 백 엔드로 전달되도록 합니다. API Management는 세션 상태를 유지하기 위해 세션 ID 쿠키를 설정합니다. 이 옵션은 예를 들어 AI 채팅 도우미 또는 다른 대화형 에이전트와 같은 백 엔드가 있는 시나리오에서 동일한 세션에서 동일한 엔드포인트로 요청을 라우팅하는 데 유용합니다.

참고 항목

부하 분산 풀의 세션 인식은 AI Gateway 초기업데이트 그룹에 먼저 릴리스됩니다.

세션 인식을 위한 쿠키 관리

세션 인식을 사용하는 경우 클라이언트는 쿠키를 적절하게 처리해야 합니다. 클라이언트는 세션 상태를 유지하기 위해 헤더 값 Set-Cookie 을 저장하고 후속 요청과 함께 보내야 합니다.

API Management 정책을 사용하여 세션 인식에 대한 쿠키를 설정할 수 있습니다. 예를 들어 Assistants API의 경우( Azure AI Foundry 모델에서 Azure OpenAI의 기능) 클라이언트는 세션 ID를 유지하고, 본문에서 스레드 ID를 추출하고, 쌍을 유지하고, 각 호출에 대해 올바른 쿠키를 보내야 합니다. 또한 클라이언트는 쿠키를 보낼 시기 또는 쿠키 헤더를 보내지 않을 시기를 알아야 합니다. 다음 예제 정책을 정의하여 이러한 요구 사항을 적절하게 처리할 수 있습니다.

<policies>
  <inbound>
    <base />
    <set-backend-service backend-id="APIMBackend" />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <set-variable name="gwSetCookie" value="@{
      var payload = context.Response.Body.As<JObject>();
      var threadId = payload["id"];
      var gwSetCookieHeaderValue = context.Request.Headers.GetValueOrDefault("SetCookie", string.Empty);
      if(!string.IsNullOrEmpty(gwSetCookieHeaderValue))
      {
        gwSetCookieHeaderValue = gwSetCookieHeaderValue + $";Path=/threads/{threadId};";
      }
      return gwSetCookieHeaderValue;
    }" />
    <set-header name="Set-Cookie" exists-action="override">
      <value>Cookie=gwSetCookieHeaderValue</value>
    </set-header>
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>

예시

포털, API Management REST API 또는 Bicep 또는 ARM 템플릿을 사용하여 백 엔드 풀을 구성합니다. 다음 예제에서는 API Management 인스턴스 myAPIM의 백 엔드 myBackendPool이 백 엔드 풀로 구성됩니다. 풀의 예제 백 엔드 이름은 backend-1 및 backend-2입니다. 두 백 엔드 모두 우선 순위가 가장 높은 그룹에 있습니다. 그룹 내에서 백 엔드-1 은 백 엔드-2보다 가중치가 더 큽니다.

  1. Azure Portal에서 API Management 인스턴스로 이동합니다.
  2. 왼쪽 메뉴에서 API>백엔드>를 선택하고 백엔드를 선택하십시오.
  3. 백 엔드 페이지에서 부하 분산 장치 탭을 선택합니다.
  4. + 새 풀 만들기를 선택합니다.
  5. 부하 분산된 새 풀 만들기 페이지에서 다음을 수행합니다.
    • 이름: myBackendPool과 같은 풀의 이름을 입력합니다.
    • 설명: 필요에 따라 설명을 입력합니다.
    • 풀에 백 엔드 추가: 풀에 추가할 하나 이상의 백 엔드를 선택합니다.
    • 백 엔드 가중치 및 우선 순위: 풀에 있는 각 백 엔드의 가중치 및 우선 순위를 구성하려면 가중치 및 우선 순위 사용자 지정 을 선택합니다. 예를 들어 백 엔드-1 과 백 엔드-2라는 두 개의 백 엔드를 추가한 경우 백 엔드-1 의 가중치를 3으로 설정하고 백 엔드-2 의 가중치를 1로 설정하고 두 백 엔드의 우선 순위를 1로 설정합니다.
    • 선택하고생성합니다.

제한 사항

관련 콘텐츠