다음을 통해 공유

Azure API Management의 정책

적용 대상: 모든 API Management 계층

Azure API Management에서 API 게시자는 정책을 사용하여 구성을 통해 API 동작을 변경할 수 있습니다. 이 문서에서는 정책을 사용하는 방법을 설명합니다.

정책은 API의 요청 또는 응답에 따라 순차적으로 실행되는 명령문의 컬렉션입니다. API Management는 인증, 속도 제한, 캐싱 및 요청 또는 응답 변환과 같은 일반적인 API 시나리오를 처리하도록 구성할 수 있는 75개 이상의 정책을 제공합니다. 전체 목록은 API Management 정책 참조를 참조하세요.

인기 있는 정책은 다음과 같습니다.

  • XML에서 JSON으로의 형식 변환입니다.
  • 개발자의 수신 전화 수를 제한하기 위한 호출 속도 제한입니다.
  • 특정 IP 주소에서 들어오는 요청 필터링

정책은 API 소비자와 관리되는 API 간에 있는 게이트웨이 내에서 적용됩니다. 게이트웨이는 요청을 수신하고 변경되지 않고 기본 API로 전달하지만 정책은 인바운드 요청과 아웃바운드 응답 모두에 변경 내용을 적용할 수 있습니다.

정책 구성 이해

정책 정의는 요청 및 응답에 적용할 명령문의 시퀀스를 설명하는 간단한 XML 문서입니다. 정책 정의를 구성하는 데 도움이 되도록 포털에서 제공하는 옵션은 다음과 같습니다.

  • XML을 코딩하지 않고 인기 있는 정책 구성을 간소화하는 단계별 양식 기반 편집기
  • XML 코드 조각을 삽입하거나 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's an error condition go here -->
  </on-error>
</policies>

정책 XML 예제는 API Management 정책 부분 리포지토리를 참조하세요.

오류 처리

요청 처리 중 오류가 발생하는 경우:

  • inbound, backend 또는 outbound 섹션의 나머지 단계는 건너뜁니다.
  • 실행은 on-error 섹션의 문으로 이동합니다.

on-error 섹션에 정책 문을 배치하여 다음을 수행할 수 있습니다.

  • 속성을 사용하여 오류를 검토합니다 context.LastError .
  • 정책을 사용하여 오류 응답을 검사하고 사용자 지정합니다 set-body .
  • 오류가 발생하면 어떻게 되는지 구성합니다.

자세한 내용은 API Management 정책에서 오류 처리를 참조하세요.

정책 식

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

  • 단일 C# 문이 @(expression)로 묶여 있음
  • 값을 반환하는 다중 문으로 구성된 C# 코드 블록@{expression}입니다.

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

정책 식은 특수 코드를 작성하거나 백 엔드 서비스를 수정할 필요 없이 트래픽을 제어하고 API 동작을 수정할 수 있는 정교한 방법을 제공합니다. 일부 정책은 제어 흐름 및 변수 설정 등의 정책 식을 기준으로 합니다.

범위

API Management를 사용하면 가장 넓은 범위에서 가장 좁은 범위까지 다음과 같은 범위에서 정책을 정의할 수 있습니다.

  • 전역(모든 API)
  • 작업 영역(선택한 작업 영역과 연결된 모든 API)
  • 제품(선택한 제품과 연결된 API)
  • API(API의 모든 작업)
  • 작업(API의 단일 작업)

정책을 구성하는 경우 먼저 정책이 적용되는 범위를 선택해야 합니다.

5가지 정책 범위를 보여 주는 다이어그램.

알아야 할 사항

  • 다른 API 소비자에 대한 세분화된 제어의 경우 둘 이상의 범위에서 정책 정의를 구성할 수 있습니다.

  • 모든 정책이 각 범위 및 정책 섹션에서 지원되는 것은 아닙니다.

  • 둘 이상의 범위에서 정책 정의를 구성할 때 요소를 배치하여 각 정책 섹션에서 정책 상속 및 정책 평가 순서를 제어합니다 base .

  • API 요청에 적용된 정책은 요청에 사용되는 구독 키의 존재 또는 부재, 구독 키의 API 또는 제품 범위, API 또는 제품에 구독이 필요한지 여부 등 요청 컨텍스트의 영향을 받습니다.

    참고 항목

    API 범위 구독, 모든 API 구독 또는 기본 제공 전체 액세스 구독을 사용하는 경우 제품 범위에서 구성된 정책은 해당 구독의 요청에 적용되지 않습니다.

자세한 내용은 다음을 참조하세요.

GraphQL 해결 프로그램 정책

API Management에서 GraphQL 리졸버는 GraphQL 스키마의 특정 작업 유형 및 필드에 대한 정책을 사용하여 구성됩니다.

  • 현재 API Management는 HTTP API, Azure Cosmos DB 또는 Azure SQL 데이터 원본을 지정하는 GraphQL 확인자를 지원합니다. 예를 들어 HTTP 데이터 원본에 대한 요청(및 필요에 따라 응답)을 지정하는 요소를 사용하여 단일 http-data-source 정책을 구성할 수 있습니다.
  • API, 제품 또는 모든 API와 같은 다른 범위의 정책 정의에는 확인자 정책을 포함할 수 없습니다. 또한 정책은 다른 범위에서 구성된 정책을 상속하지 않습니다.
  • 게이트웨이는 정책 실행 파이프라인에서 구성된 inbound 정책 및 backend 정책이 실행된 후에 '리졸버 범위 정책'을 평가합니다.

자세한 내용은 GraphQL 확인자 구성을 참조하세요.

Copilot 지원 받기

Copilot에서 AI 지원을 받아 API Management 정책 정의를 만들고 편집할 수 있습니다. Copilot를 사용하여 XML 구문을 알 필요 없이 특정 요구 사항과 일치하는 정책을 만들고 업데이트할 수 있습니다. 기존 정책에 대한 설명을 가져올 수도 있습니다. 또한 Copilot는 다른 API 관리 솔루션에서 구성했을 수 있는 정책을 번역하는 데 도움이 될 수 있습니다.

프롬프트 예:

Generate a policy that adds an Authorization header to the request with a Bearer token.

부조종사에는 AI가 지원되므로 놀라움과 실수가 가능합니다. 자세한 내용은 Copilot 일반 사용 FAQ를 참조하세요.

예제

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

전역 수준의 정책 및 API에 대해 구성된 정책이 있는 경우 특정 API를 사용할 때마다 두 정책을 모두 적용할 수 있습니다. API Management는 base 요소를 통해 결합된 정책 명령문의 결정적인 순서를 허용합니다.

API 범위의 정책 정의 예제는 다음과 같습니다.

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

앞의 예제 정책 정의에서 다음을 수행합니다.

  • 해당 문이 cross-domain 먼저 실행된다.
  • 정책은find-and-replace 더 넓은 범위의 모든 정책 후에 실행됩니다.

참고 항목

API 범위에서 base 요소를 제거하면 API 범위에서 구성된 정책만 적용됩니다. 제품 및 광범위한 범위에서 구성된 정책은 적용되지 않습니다.

정책 식을 사용하여 요청 수정

다음 예제에서는 정책 식 및 set-header 정책을 사용하여 들어오는 요청에 사용자 데이터를 추가합니다. 추가된 헤더에는 요청의 구독 키와 연결된 사용자 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>

관련 콘텐츠

정책 작업에 대한 자세한 내용은 다음을 참조하세요.