콘텐츠 유효성 검사

적용 대상: 모든 API Management 계층

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

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

형식	내용 유형
JSON	예제: application/json application/hal+json
XML	예: application/xml
SOAP	허용되는 값: SOAP 1.2 API의 경우 application/soap+xml SOAP 1.1 API의 경우 text/xml

참고 항목

유효성 검사 정책에서 사용할 수 있는 API 스키마의 최대 크기는 4MB입니다. 스키마가 이 제한을 초과하는 경우 유효성 검사 정책은 런타임에 오류를 반환합니다. 이 제한을 늘리려면 고객 지원팀에 문의하세요.

유효성이 검사된 콘텐츠

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

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

팁

스키마에서 사용할 수 있는 정규식 패턴 제약 조건의 예는 OWASP 유효성 검사 Regex 리포지토리를 참조하세요.

참고 항목

정책 문에 제공된 순서대로 정책의 요소 및 자식 요소를 설정합니다. 이 정책을 구성하는 데 도움이 되도록 포털은 양식 기반의 안내형 편집기를 제공합니다. API Management 정책을 설정하거나 편집하는 방법에 대해 자세히 알아봅니다.

정책 문

<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" />
</validate-content>

특성

특성	설명	필수 항목	기본값
unspecified-content-type-action	API 스키마에 지정되지 않은 콘텐츠 형식을 사용하여 요청 또는 응답에 대해 수행할 작업입니다. 정책 식이 허용됩니다.	예	해당 없음
max-size	요청 또는 응답 본문의 최대 길이(바이트)로 Content-Length 헤더가 확인합니다. 요청 본문 또는 응답 본문이 압축된 경우 이 값은 압축을 푼 길이입니다. 허용되는 최댓값: 102,400바이트(100KB). (이 제한을 늘려야 하는 경우 고객 지원팀에 문의하세요.) 정책 식이 허용됩니다.	예	해당 없음
size-exceeded-action	요청이나 응답의 본문 크기가 max-size에서 지정한 크기를 초과했을 때 수행할 작업입니다. 정책 식이 허용됩니다.	예	해당 없음
errors-variable-name	유효성 검사 오류를 로그할 context.Variables의 변수 이름입니다. 정책 식은 허용되지 않습니다.	아니요	해당 없음

Elements

이름	설명	필수
content-type-map	이 요소를 추가하여 들어오는 요청 또는 응답의 콘텐츠 형식을 유효성 검사를 트리거하는 데 사용되는 다른 콘텐츠 형식에 매핑합니다.	아니요
콘텐츠	이러한 요소 중 하나 이상을 추가하여 요청 또는 응답의 콘텐츠 형식 또는 매핑된 콘텐츠 형식의 유효성을 검사하고 지정된 작업을 수행합니다.	아니요

content-type-map 특성

attribute	설명	필수 항목	기본값
any-content-type-value	들어오는 콘텐츠 형식에 관계없이 요청 또는 응답 본문의 유효성 검사에 사용되는 콘텐츠 형식입니다. 정책 식은 허용되지 않습니다.	아니요	해당 없음
missing-content-type-value	들어오는 콘텐츠 형식이 없거나 비어 있는 경우 요청 또는 응답 본문의 유효성 검사에 사용되는 콘텐츠 형식입니다. 정책 식은 허용되지 않습니다.	아니요	해당 없음

content-type-map-elements

이름	설명	필수
type	이러한 요소 중 하나 이상을 추가하여 들어오는 콘텐츠 형식을 요청 또는 응답 본문의 유효성 검사에 사용되는 콘텐츠 형식에 매핑합니다. from을 사용하여 알려진 들어오는 콘텐츠 형식을 지정하거나 when을 정책 식과 함께 사용하여 조건과 일치하는 들어오는 콘텐츠 형식을 지정합니다. 지정된 경우 any-content-type-value 및 missing-content-type-value의 매핑을 재정의합니다.	아니요

콘텐츠 특성

attribute	설명	필수 항목	기본값
type	본문 유효성 검사를 실행할 콘텐츠 형식으로, 콘텐츠 형식 헤더 또는 지정된 경우 content-type-mapping에 매핑된 값에 대해 확인됩니다. 비어 있는 경우 API 스키마에 지정된 모든 콘텐츠 형식에 적용됩니다. SOAP 요청 및 응답(“soap”으로 설정된 validate-as 속성)을 확인하려면 SOAP 1.2 API의 경우 type을 application/soap+xml, SOAP 1.1 API의 경우 text/xml로 설정합니다.	아니요	해당 없음
validate-as	일치하는 type이 있는 요청 또는 응답 본문의 유효성 검사에 사용할 유효성 검사 엔진입니다. 지원되는 값: “json”, “xml”, “soap”. “soap”를 지정하면 요청 또는 응답의 XML이 SOAP 봉투에서 추출되고 XML 스키마에 대해 유효성이 검사됩니다.	예	해당 없음
schema-id	콘텐츠 유효성 검사를 위해 API Management 인스턴스에 추가된 기존 스키마의 이름입니다. 지정하지 않으면 API 정의의 기본 스키마가 사용됩니다.	아니요	해당 없음
schema-ref	schema-id에 지정된 JSON 스키마의 경우 JSON 문서의 유효한 로컬 참조 경로에 대한 선택적 참조입니다. 예: #/components/schemas/address 이 특성은 API Management가 유효한 JSON 스키마로 처리하는 JSON 개체를 반환해야 합니다. XML 스키마의 경우 schema-ref는 지원되지 않으며 최상위 스키마 요소를 XML 요청 또는 응답 페이로드의 루트로 사용할 수 있습니다. 유효성 검사는 XML 요청 또는 응답 페이로드 루트에서 시작하는 모든 요소가 제공된 XML 스키마를 준수하는지 확인합니다.	아니요	해당 없음
allow-additional-properties	부울입니다. JSON 스키마의 경우 스키마에 구성된 additionalProperties 값의 런타임 재정의를 구현할지 여부를 지정합니다. - true: JSON 스키마의 additionalProperties 필드가 추가 속성을 허용하지 않도록 구성된 경우에도 요청 또는 응답 본문에 추가 속성을 허용합니다. - false: JSON 스키마의 additionalProperties 필드가 추가 속성을 허용하도록 구성된 경우에도 요청 또는 응답 본문에 추가 속성을 허용하지 않습니다. 특성을 지정하지 않으면 정책은 스키마의 additionalProperties 필드 구성에 따라 추가 속성의 유효성을 검사합니다.	아니요	해당 없음

actions

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

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

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

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

작업	설명
ignore	유효성 검사 건너뛰기.
예방	요청 또는 응답 처리를 차단하고, 자세한 유효성 검사 오류를 로그하고, 오류를 반환합니다. 첫 번째 오류 집합이 검색되면 처리가 중단됩니다.
검색(detect)	요청 또는 응답 처리를 중단하지 않고 유효성 검사 오류를 로그합니다.

사용

• 정책 섹션: 인바운드, 아웃바운드, 오류 시
• 정책 범위: 전역, 작업 영역, 제품, 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>에 스키마 리소스를 추가하고 스키마가 스키마 페이지의 목록에 나타납니다. 스키마를 선택하여 속성을 보거나 스키마 편집기에서 편집합니다.

참고 항목

스키마는 API Management 인스턴스에 추가된 다른 스키마를 상호 참조할 수 있습니다. 예를 들어 다음과 유사한 요소를 사용하여 API Management에 추가된 XML 스키마를 포함합니다.

<xs:include schemaLocation="/schemas/myschema" />

팁

WSDL 및 XSD 스키마 참조를 확인하고 생성된 스키마를 API Management로 일괄 가져오기 위한 오픈 소스 도구는 GitHub에서 사용할 수 있습니다.

예제

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(아웃바운드 섹션에서 정책 적용 시)가 포함됩니다.

이름	Type	유효성 검사 규칙	세부 정보	공용 응답	작업
validate-content
	RequestBody	SizeLimit	요청의 본문은 {size} 바이트 길이이며 구성된 제한 {maxSize} 바이트를 초과합니다.	요청의 본문은 {size} 바이트 길이이며 {maxSize} 바이트 제한을 초과합니다.	검색/방지
	ResponseBody	SizeLimit	응답의 본문은 {size} 바이트 길이이며 구성된 제한 {maxSize} 바이트를 초과합니다.	내부 오류로 인해 요청을 처리할 수 없습니다. API 소유자에게 문의하세요.	검색/방지
{messageContentType}	RequestBody	Unspecified	지정되지 않은 콘텐츠 형식 {messageContentType}은 허용되지 않습니다.	지정되지 않은 콘텐츠 형식 {messageContentType}은 허용되지 않습니다.	검색/방지
{messageContentType}	ResponseBody	Unspecified	지정되지 않은 콘텐츠 형식 {messageContentType}은 허용되지 않습니다.	내부 오류로 인해 요청을 처리할 수 없습니다. API 소유자에게 문의하세요.	검색/방지
	ApiSchema		API의 스키마가 없거나 확인되지 못했습니다.	내부 오류로 인해 요청을 처리할 수 없습니다. API 소유자에게 문의하세요.	검색/방지
	ApiSchema		API의 스키마에서 정의를 지정하지 않습니다.	내부 오류로 인해 요청을 처리할 수 없습니다. API 소유자에게 문의하세요.	검색/방지
{messageContentType}	RequestBody / ResponseBody	MissingDefinition	API의 스키마에 콘텐츠 형식 {messageContentType}과 연결된 정의 {definitionName}이 없습니다.	내부 오류로 인해 요청을 처리할 수 없습니다. API 소유자에게 문의하세요.	검색/방지
{messageContentType}	RequestBody	IncorrectMessage	요청 본문이 콘텐츠 형식 {messageContentType}과 연결된 정의 {definitionName}을 따르지 않습니다. {valError.Message} Line: {valError.LineNumber}, Position: {valError.LinePosition}	요청 본문이 콘텐츠 형식 {messageContentType}과 연결된 정의 {definitionName}을 따르지 않습니다. {valError.Message} Line: {valError.LineNumber}, Position: {valError.LinePosition}	검색/방지
{messageContentType}	ResponseBody	IncorrectMessage	응답 본문이 콘텐츠 형식 {messageContentType}과 연결된 정의 {definitionName}을 따르지 않습니다. {valError.Message} Line: {valError.LineNumber}, Position: {valError.LinePosition}	내부 오류로 인해 요청을 처리할 수 없습니다. API 소유자에게 문의하세요.	검색/방지
	RequestBody	ValidationException	콘텐츠 형식 {messageContentType}에 대한 요청 본문의 유효성을 검사할 수 없습니다. {exception details}	내부 오류로 인해 요청을 처리할 수 없습니다. API 소유자에게 문의하세요.	검색/방지
	ResponseBody	ValidationException	콘텐츠 형식 {messageContentType}에 대한 응답 본문의 유효성을 검사할 수 없습니다. {exception details}	내부 오류로 인해 요청을 처리할 수 없습니다. API 소유자에게 문의하세요.	검색/방지
validate-parameters / validate-headers
{paramName} / {headerName}	QueryParameter/PathParameter/RequestHeader	Unspecified	지정되지 않은 {path parameter / query parameter / header} {paramName}은 허용되지 않습니다.	지정되지 않은 {path parameter / query parameter / header} {paramName}은 허용되지 않습니다.	검색/방지
{headerName}	ResponseHeader	Unspecified	지정되지 않은 헤더 {headerName}은 허용되지 않습니다.	내부 오류로 인해 요청을 처리할 수 없습니다. API 소유자에게 문의하세요.	검색/방지
	ApiSchema		API의 스키마가 없거나 확인할 수 없습니다.	내부 오류로 인해 요청을 처리할 수 없습니다. API 소유자에게 문의하세요.	검색/방지
	ApiSchema		API 스키마가 정의를 지정하지 않습니다.	내부 오류로 인해 요청을 처리할 수 없습니다. API 소유자에게 문의하세요.	검색/방지
{paramName}	QueryParameter / PathParameter / RequestHeader / ResponseHeader	MissingDefinition	API의 스키마에 {definitionName} 정의가 포함되어 있지 않습니다. 이는 {query parameter / path parameter / header} {paramName}과 연결되어 있습니다.	내부 오류로 인해 요청을 처리할 수 없습니다. API 소유자에게 문의하세요.	검색/방지
{paramName}	QueryParameter/PathParameter/RequestHeader	IncorrectMessage	요청은 {query parameter / path parameter / header}{paramName}에 여러 값을 포함할 수 없습니다.	요청은 {query parameter / path parameter / header}{paramName}에 여러 값을 포함할 수 없습니다.	검색/방지
{headerName}	ResponseHeader	IncorrectMessage	응답은 {headerName} 헤더에 여러 값을 포함할 수 없습니다.	내부 오류로 인해 요청을 처리할 수 없습니다. API 소유자에게 문의하세요.	검색/방지
{paramName}	QueryParameter/PathParameter/RequestHeader	IncorrectMessage	{query parameter / path parameter / header} {paramName}의 값이 정의를 따르지 않습니다. {valError.Message} Line: {valError.LineNumber}, Position: {valError.LinePosition}	{query parameter / path parameter / header} {paramName}의 값이 정의를 따르지 않습니다. {valError.Message} Line: {valError.LineNumber}, Position: {valError.LinePosition}	검색/방지
{headerName}	ResponseHeader	IncorrectMessage	{headerName} 헤더의 값이 정의를 따르지 않습니다. {valError.Message} Line: {valError.LineNumber}, Position: {valError.LinePosition}	내부 오류로 인해 요청을 처리할 수 없습니다. API 소유자에게 문의하세요.	검색/방지
{paramName}	QueryParameter/PathParameter/RequestHeader	IncorrectMessage	정의에 따라 {query parameter / path parameter / header} {paramName}의 값을 구문 분석할 수 없습니다. {ex.Message}	정의에 따라 {query parameter / path parameter / header} {paramName}의 값을 구문 분석할 수 없습니다. {ex.Message}	검색/방지
{headerName}	ResponseHeader	IncorrectMessage	정의에 따라 {headerName} 헤더의 값을 구문 분석할 수 없습니다.	내부 오류로 인해 요청을 처리할 수 없습니다. API 소유자에게 문의하세요.	검색/방지
{paramName}	QueryParameter/PathParameter/RequestHeader	ValidationError	{Query parameter / Path parameter / Header} {paramName}의 유효성을 검사할 수 없습니다. {exception details}	내부 오류로 인해 요청을 처리할 수 없습니다. API 소유자에게 문의하세요.	검색/방지
{headerName}	ResponseHeader	ValidationError	{headerName} 헤더의 유효성을 검사할 수 없습니다. {exception details}	내부 오류로 인해 요청을 처리할 수 없습니다. API 소유자에게 문의하세요.	검색/방지
validate-status-code
{status-code}	StatusCode	Unspecified	응답 상태 코드 {status-code}는 허용되지 않습니다.	내부 오류로 인해 요청을 처리할 수 없습니다. API 소유자에게 문의하세요.	검색/방지

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

이유	Message
Bad request	컨텍스트 변수에 대한 {Details}, 클라이언트에 대한 {Public response}
응답이 허용되지 않습니다	컨텍스트 변수에 대한 {Details}, 클라이언트에 대한 {Public response}

관련 정책

• 콘텐츠 유효성 검사

관련 콘텐츠

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

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