매개 변수 유효성 검사

아티클
07/23/2024

적용 대상: 모든 API Management 계층

validate-parameters 정책은 API 스키마에 대한 요청의 헤더, 쿼리 또는 경로 매개 변수의 유효성을 검사합니다.

Important

2021-01-01-preview보다 이전 버전의 관리 API를 사용하여 API를 가져온 경우 validate-parameters 정책이 작동하지 않을 수 있습니다. API를 다시 가져올 때 관리 API 버전 2021-01-01-preview 또는 그 이상이 필요합니다.

참고 항목

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

참고 항목

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

정책 문

<validate-parameters specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect" errors-variable-name="variable name"> 
    <headers specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </headers>
    <query specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </query>
    <path specified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </path>
</validate-parameters>

특성

특성	설명	필수 항목	기본값
specified-parameter-action	API 스키마에 지정된 요청 매개 변수에 수행할 작업입니다. `headers`, `query`, 또는 `path` 요소에서 제공되는 경우, 그 값은 `specified-parameter-action`의 값을 재정의하며 그 위치는 `validate-parameters` 요소 안입니다. 정책 식이 허용됩니다.	예	해당 없음
unspecified-parameter-action	API 스키마에 지정되지 않은 요청 매개 변수에 수행할 작업입니다. `headers`이나 `query` 요소에서 제공되는 경우 그 값은 `unspecified-parameter-action`의 값을 재정의하며 그 위치는 `validate-parameters` 요소 안입니다. 정책 식이 허용됩니다.	예	해당 없음
errors-variable-name	유효성 검사 오류를 로그할 `context.Variables`의 변수 이름입니다. 정책 식은 허용되지 않습니다.	아니요	해당 없음

Elements

이름	설명	필수
헤더	요청에서 명명된 특정 매개 변수에 대한 기본 유효성 검사 작업을 재정의하려면 이 요소와 하나 이상의 `parameter` 하위 요소를 추가합니다. 매개 변수가 API 스키마에 지정된 경우 이 값은 상위 수준 `specified-parameter-action` 구성을 재정의합니다. 매개 변수가 API 스키마에 지정되지 않은 경우 이 값은 상위 수준 `unspecified-parameter-action` 구성을 재정의합니다.	아니요
query	요청에서 명명된 특정 쿼리 매개 변수에 대한 기본 유효성 검사 작업을 재정의하려면 이 요소와 하나 이상의 `parameter` 하위 요소를 추가합니다. 매개 변수가 API 스키마에 지정된 경우 이 값은 상위 수준 `specified-parameter-action` 구성을 재정의합니다. 매개 변수가 API 스키마에 지정되지 않은 경우 이 값은 상위 수준 `unspecified-parameter-action` 구성을 재정의합니다.	아니요
경로	이 요소와 하나 이상의 `parameter` 하위 요소를 추가하여 요청의 특정 URL 경로 매개 변수에 대한 기본 유효성 검사 작업을 재정의합니다. 매개 변수가 API 스키마에 지정된 경우 이 값은 상위 수준 `specified-parameter-action` 구성을 재정의합니다. 매개 변수가 API 스키마에 지정되지 않은 경우 이 값은 상위 수준 `unspecified-parameter-action` 구성을 재정의합니다.	아니요

actions

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

API 스키마에 표시되는 요소에 대한 작업을 지정할 수 있으며, 정책에 따라서는 API 스키마에 표시되지 않는 요소에 대해서도 작업을 지정할 수 있습니다.
정책의 자식 요소에 지정된 작업은 부모에 지정된 동작을 재정의합니다.

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

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

사용

정책 섹션: inbound
정책 범위: 전역, 작업 영역, 제품, API, 작업
게이트웨이: 클래식, v2, 사용량, 자체 호스팅, 작업 영역

사용법 참고 사항

이 정책은 정책 섹션에서 한 번만 사용할 수 있습니다.

로그

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

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

성능 의미

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

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

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

예시

이 예제에서 모든 쿼리 및 경로 매개 변수의 유효성은 방지 모드와 검색 모드의 헤더에서 확인됩니다. 유효성 검사는 다양한 헤더 매개 변수에 의해 재정의됩니다.

<validate-parameters specified-parameter-action="prevent" unspecified-parameter-action="prevent" errors-variable-name="requestParametersValidation"> 
    <headers specified-parameter-action="detect" unspecified-parameter-action="detect">
        <parameter name="Authorization" action="prevent" />
        <parameter name="User-Agent" action="ignore" />
        <parameter name="Host" action="ignore" />
        <parameter name="Referrer" action="ignore" />
    </headers>   
</validate-parameters>

유효성 검사 오류

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}

콘텐츠 유효성 검사

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

다음을 통해 공유

매개 변수 유효성 검사

정책 문

특성

Elements

actions

사용

사용법 참고 사항

로그

성능 의미

예시

유효성 검사 오류

피드백

추가 리소스

다음을 통해 공유

매개 변수 유효성 검사

정책 문

특성

Elements

actions

사용

사용법 참고 사항

로그

성능 의미

예시

유효성 검사 오류

관련 정책

관련 콘텐츠

피드백

추가 리소스