Azure API Management의 정책

적용 대상: 모든 API Management 계층

Azure API Management에서 API 게시자는 정책을 사용하여 구성을 통해 API 동작을 변경할 수 있습니다. 정책은 API의 요청 또는 응답에 따라 순차적으로 실행되는 명령문의 컬렉션입니다. API Management는 인증, 속도 제한, 캐싱, 요청 또는 응답의 변환과 같은 일반적인 API 시나리오를 처리하도록 구성할 수 있는 50개 이상의 정책을 기본으로 제공합니다. 전체 목록은 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 is 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 정책에서 특성 값 또는 텍스트 값으로 사용할 수 있습니다. 정책 식은 다음 중 하나입니다.

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

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

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

범위

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

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

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

알아야 할 사항

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

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

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

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

  참고 항목

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

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

• 정책 설정 또는 편집
• API Management의 구독.

GraphQL 해결 프로그램 정책

API Management에서 GraphQL 확인자는 GraphQL 스키마의 특정 작업 유형 및 필드로 범위가 지정된 정책을 사용하여 구성됩니다.

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

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

Azure용 Microsoft Copilot를 사용하여 정책 만들기 지원 받기(미리 보기)

Azure용 Microsoft Copilot(미리 보기)은 Azure API Management에 대한 정책 작성 기능을 제공합니다. API Management의 정책 편집기 컨텍스트에서 Azure용 Copilot을 사용하여 구문을 모르는 상태에서 특정 요구 사항과 일치하는 정책을 만들 수도 있고, 사용자에게 정책이 설명되도록 미리 구성했을 수도 있습니다.

Azure용 Copilot에 정책 정의를 생성하라는 메시지를 표시한 다음, 결과를 정책 편집기에 복사하고 필요한 조정을 수행할 수 있습니다. 다양한 옵션에 대한 인사이트를 얻거나, 제공된 정책을 수정하거나, 이미 가지고 있는 정책을 명확히 하기 위해 질문을 합니다. 자세한 정보

Important

Azure용 Microsoft Copilot(미리 보기)은 등록이 필요하며 현재 승인된 엔터프라이즈 고객 및 파트너만 사용할 수 있습니다. 자세한 내용은 Azure용 Microsoft Copilot에 대한 제한된 액세스(미리 보기)를 참조하세요.

예제

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

전역 수준의 정책 및 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> 

관련 콘텐츠

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

• 자습서: API 변환 및 보호
• 정책 문 및 해당 설정에 대한 전체 목록에 대한 정책 참조
• 정책 식
• 정책 설정 또는 편집
• 정책 구성 재사용
• 정책 코드 조각 리포지토리
• Azure용 Microsoft Copilot을 사용하는 작성자 정책