콘텐츠 유효성 검사

적용 대상: 모든 API Management 계층

validate-content 정책은 하나 이상의 지원되는 스키마에 대해 요청 또는 응답 본문의 크기 또는 콘텐츠의 유효성을 검사합니다.

다음 표에서는 정책이 지원하는 스키마 형식과 요청 또는 응답 콘텐츠 형식을 보여 줍니다. 콘텐츠 형식 값은 대/소문자를 구분하지 않습니다.

유효성이 검사된 콘텐츠

정책은 스키마에 대한 요청 또는 응답에서 다음 콘텐츠의 유효성을 검사합니다.

• 모든 필수 속성이 있습니다.
• 스키마에 additionalProperties 필드가 설정된 경우 추가 속성이 있거나 없습니다. allow-additional-properties 특성으로 재정의될 수 있습니다.
• 모든 속성의 형식입니다. 예를 들어 스키마가 속성을 정수로 지정하는 경우 요청(또는 응답)에는 문자열과 같은 다른 형식이 아닌 정수가 포함되어야 합니다.
• 스키마에 지정된 경우 속성의 형식(예: regex(pattern 키워드가 지정된 경우), 정수의 경우 minimum 등).

정책 문

<validate-content unspecified-content-type-action="ignore | prevent | detect" max-size="size in bytes" size-exceeded-action="ignore | prevent | detect" errors-variable-name="variable name">
    <content-type-map any-content-type-value="content type string" missing-content-type-value="content type string">
        <type from | when="content type string" to="content type string" />
    </content-type-map>
    <content type="content type string" validate-as="json | xml | soap" schema-id="schema id" schema-ref="#/local/reference/path" action="ignore | prevent | detect" allow-additional-properties="true | false" case-insensitive-property-names="true | false"/>
</validate-content>

특성

Elements

content-type-map 특성

content-type-map-elements

콘텐츠 특성

actions

콘텐츠 유효성 검사 정책에는 API 요청의 엔터티나 API 스키마에 대한 응답의 유효성을 검사할 때 API Management가 수행하는 작업을 지정하는 하나 이상의 특성이 포함되어 있습니다.

• API 스키마에 표시되는 요소에 대한 작업을 지정할 수 있으며, 정책에 따라서는 API 스키마에 표시되지 않는 요소에 대해서도 작업을 지정할 수 있습니다.

• 정책의 자식 요소에 지정된 작업은 부모에 지정된 동작을 재정의합니다.

사용 가능한 작업은 다음과 같습니다.

사용

• 정책 섹션: 인바운드, 아웃바운드, 오류 시
• 정책 범위: 전역, 작업 영역, 제품, API, 작업
• 게이트웨이: 클래식, v2, 사용량, 자체 호스팅, 작업 영역

로그

정책 실행 중의 유효성 검사 오류에 대한 세부 정보는 context.Variables의 변수에 로그되며 이 변수는 정책 루트 요소의 errors-variable-name 특성에 지정되어 있습니다. 작업 prevent에 구성된 경우 유효성 검사 오류가 발생하면 추가 요청 또는 응답 처리가 차단되고 context.LastError 속성에도 전파됩니다.

오류를 조사하려면 추적 정책을 사용하여 컨텍스트 변수에서 오류를 Application Insights로 로그합니다.

성능 의미

유효성 검사 정책을 추가하면 API 처리량에 영향을 줄 수 있습니다. 다음과 같은 일반적인 원칙이 적용됩니다.

• API 스키마 크기가 커질수록 처리량이 낮아집니다.
• 요청이나 응답에서 페이로드가 커질수록 처리량이 낮아집니다.
• API 스키마의 크기가 페이로드의 크기보다 성능에 더 큰 영향을 줍니다.
• 수 메가바이트 크기의 API 스키마에 대해 유효성 검사를 수행하면 일부 조건에서 요청 또는 응답 시간 초과가 발생할 수 있습니다. 효과는 서비스의 사용량 및 개발자 계층에서 더 두드러지게 나타납니다.

API 처리량에 대한 유효성 검사 정책의 영향을 평가하기 위해 예상되는 프로덕션 워크로드에서 부하 테스트를 수행하기를 권합니다.

콘텐츠 유효성 검사를 위한 스키마

기본적으로 요청 또는 응답 콘텐츠의 유효성 검사는 API 정의의 JSON 또는 XML 스키마를 사용합니다. 이러한 스키마는 OpenAPI 또는 WSDL 사양에서 API Management로 API를 가져올 때 수동으로 지정하거나 자동으로 생성할 수 있습니다.

validate-content 정책을 사용하면 필요에 따라 API Management 인스턴스에 추가한 하나 이상의 JSON 또는 XML 스키마에 대해 유효성을 검사할 수 있으며 API 정의에 포함되지 않습니다. API Management에 추가하는 스키마는 여러 API에서 다시 사용할 수 있습니다.

Azure Portal을 사용하여 API Management 인스턴스에 스키마를 추가하려면 다음을 수행합니다.

1. 포털에서 API Management 인스턴스로 이동합니다.

2. 왼쪽 메뉴의 API 섹션에서 스키마>+ 추가를 선택합니다.

3. 커넥터 만들기 창에서 다음을 수행합니다.

   1. 스키마의 이름(ID)을 입력합니다.
   2. 스키마 유형에서 JSON 또는 XML을 선택합니다.
   3. 설명을 입력합니다.
   4. Create 메서드에서 다음 중 하나를 수행합니다.
      • 새로 만들기를 선택하고 스키마를 입력하거나 붙여넣습니다.
      • 파일에서 가져오기를 선택하거나 URL에서 가져오기를 선택하고 스키마 위치를 입력합니다.

        참고 항목

        URL에서 스키마를 가져오려면 브라우저에서 인터넷을 통해 스키마에 액세스할 수 있어야 합니다.

   5. 저장을 선택합니다.

   

API Management가 상대 URI /schemas/<schemaId>에 스키마 리소스를 추가하고 스키마가 스키마 페이지의 목록에 나타납니다. 스키마를 선택하여 속성을 보거나 스키마 편집기에서 편집합니다.

예제

JSON 스키마 유효성 검사

다음 예제에서 API Management는 빈 콘텐츠 형식 헤더가 있는 요청 또는 콘텐츠 형식 헤더 application/hal+json이 있는 요청을 콘텐츠 형식 application/json의 요청으로 해석합니다. 그런 다음, API Management는 API 정의의 application/json 콘텐츠 형식에 대해 정의된 스키마에 대해 검색 모드에서 유효성 검사를 수행합니다. 페이로드가 100KB보다 큰 메시지는 차단됩니다. 스키마의 additionalProperties 필드가 추가 속성을 허용하도록 구성된 경우에도 추가 속성을 포함하는 요청이 차단됩니다.

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map missing-content-type-value="application/json">
        <type from="application/hal+json" to="application/json" />
    </content-type-map>
    <content type="application/json" validate-as="json" action="detect" allow-additional-properties="false" />
</validate-content>

SOAP 스키마 유효성 검사

다음 예제에서 API Management는 들어오는 콘텐츠 형식에 관계없이 모든 요청을 콘텐츠 형식 application/soap+xml(SOAP 1.2 API에서 사용하는 콘텐츠 형식)을 사용하는 요청으로 해석합니다. 요청은 빈 콘텐츠 형식 헤더, text/xml의 콘텐츠 형식 헤더(SOAP 1.1 API에서 사용됨) 또는 다른 콘텐츠 형식 헤더와 함께 도착할 수 있습니다. 그런 다음, API Management는 SOAP 봉투에서 XML 페이로드를 추출하고 “myschema”라는 스키마에 대해 방지 모드에서 유효성 검사를 수행합니다. 페이로드가 100KB보다 큰 메시지는 차단됩니다.

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map any-content-type-value="application/soap+xml" />
    <content type="application/soap+xml" validate-as="soap" schema-id="myschema" action="prevent" /> 
</validate-content>

유효성 검사 오류

API Management는 다음 형식으로 콘텐츠 유효성 검사 오류를 생성합니다.

{
 "Name": string,
 "Type": string,
 "ValidationRule": string,
 "Details": string,
 "Action": string
}

다음 표에는 유효성 검사 정책의 발생 가능한 모든 오류가 나열되어 있습니다.

• 세부 정보: 오류를 조사하는 데 사용할 수 있습니다. 공개적으로 공유되지 않습니다.
• 퍼블릭 응답: 클라이언트에 반환되는 오류입니다. 구현 세부 정보를 누출하지 않습니다.

유효성 검사 정책에서 prevent 작업을 지정하고 오류를 생성하는 경우, API 관리의 응답에는 HTTP 상태 코드 400(인바운드 섹션에서 정책 적용 시) 및 502(아웃바운드 섹션에서 정책 적용 시)가 포함됩니다.

다음 표에서는 가능한 메시지 값과 함께 유효성 검사 오류의 가능한 모든 이유 값을 나열합니다.

관련 정책

• 콘텐츠 유효성 검사

관련 콘텐츠

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

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