API Management 정책 살펴보기

  • 3분

Azure API Management에서 정책을 사용하면 게시자가 구성을 통해 API의 동작을 변경할 수 있습니다. 정책은 API의 요청이나 응답에 따라 순차적으로 실행되는 명령문의 컬렉션입니다.

정책은 API 소비자와 관리되는 API 간에 있는 게이트웨이 내에서 적용됩니다. 게이트웨이는 모든 요청을 수신하고 보통 변경하지 않은 상태로 기본 API에 전달합니다. 그러나 정책은 인바운드 요청과 아웃바운드 응답 모두에 변경 내용을 적용할 수 있습니다. 정책이 다르게 지정하지 않는 한 정책 식은 어떤 API Management 정책에서든 특성 값 또는 텍스트 값으로 사용될 수 있습니다.

정책 구성 이해

정책 정의는 일련의 인바운드 및 아웃바운드 명령문을 설명하는 단순한 XML 문서입니다. 정의 창에서 XML을 직접 편집할 수 있습니다.

구성은 inbound, backend, outbound 및 on-error로 구분됩니다. 지정된 일련의 정책 문이 요청 및 응답을 위해 실행됩니다.

<policies>
  <inbound>
    <!-- statements to be applied to the request go here -->
  </inbound>
  <backend>
    <!-- statements to be applied before the request is forwarded to 
         the backend service go here -->
  </backend>
  <outbound>
    <!-- statements to be applied to the response go here -->
  </outbound>
  <on-error>
    <!-- statements to be applied if there is an error condition go here -->
  </on-error>
</policies>

요청을 처리하는 동안 오류가 발생하는 경우 inbound, backend 또는 outbound 섹션에 남아 있는 모든 단계를 건너뛰고 on-error 섹션의 문을 바로 실행합니다. on-error 섹션에 정책 문을 배치하면 context.LastError 속성을 사용하여 오류를 검토할 수 있으며 set-body 정책을 사용하여 오류 응답을 검사하고 사용자 지정할 수 있습니다. 그리고 오류가 발생하면 수행할 작업을 구성할 수 있습니다.

정책 식

정책에서 달리 지정하지 않는 한 정책 식은 모든 API Management 정책에서 특성 값 또는 텍스트 값으로 사용할 수 있습니다. 정책 식은 다음 중 하나입니다.

  • @(expression)으로 묶은 단일 C# 문 또는
  • 값을 반환하는 @{expression}으로 묶은 다중 문 C# 코드 블록

각 식은 암시적으로 제공된 context 변수와 .NET Framework 형식의 허용된 하위 집합에 액세스할 수 있습니다.

정책 식은 특수 코드를 작성하거나 백 엔드 서비스를 수정할 필요 없이 트래픽을 제어하고 API 동작을 수정할 수 있는 정교한 방법을 제공합니다.

다음 예제에서는 정책 식 및 set 헤더 정책을 사용하여 사용자 데이터를 들어오는 요청에 추가합니다. 추가된 헤더에는 요청의 구독 키와 연결된 사용자 ID와 요청을 처리하는 게이트웨이가 호스트되는 지역이 포함됩니다.

<policies>
    <inbound>
        <base />
        <set-header name="x-request-context-data" exists-action="override">
            <value>@(context.User.Id)</value>
            <value>@(context.Deployment.Region)</value>
      </set-header>
    </inbound>
</policies>

서로 다른 범위에서 지정된 정책 적용

글로벌 수준의 정책 및 API에 대해 구성된 정책이 있는 경우 특정 API가 사용될 때마다 두 정책이 모두 적용됩니다. API Management는 기본 요소를 통해 결합된 정책 명령문의 결정적인 순서를 허용합니다.

<policies>
    <inbound>
        <cross-domain />
        <base />
        <find-and-replace from="xyz" to="abc" />
    </inbound>
</policies>

이전 예제 정책 정의에서는 cross-domain 문이 먼저 실행됩니다. find-and-replace 정책은 더 넓은 범위의 정책 다음에 실행됩니다.

응답 콘텐츠 필터링

다음 예제에 정의된 정책은 요청과 연결된 제품에 따라 응답 페이로드에서 데이터 요소를 필터링하는 방법을 보여 줍니다.

이 코드 조각은 응답 콘텐츠가 JSON 형식이고 minutely, hourly, daily, flags라는 루트 수준 속성을 포함한다고 가정합니다.

<policies>
  <inbound>
    <base />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <choose>
      <when condition="@(context.Response.StatusCode == 200 && context.Product.Name.Equals("Starter"))">
        <!-- NOTE that we are not using preserveContent=true when deserializing response body stream into a JSON object since we don't intend to access it again. See details on /azure/api-management/api-management-transformation-policies#SetBody -->
        <set-body>
          @{
            var response = context.Response.Body.As<JObject>();
            foreach (var key in new [] {"minutely", "hourly", "daily", "flags"}) {
            response.Property (key).Remove ();
           }
          return response.ToString();
          }
    </set-body>
      </when>
    </choose>    
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>