다음을 통해 공유


매개 변수 유효성 검사

적용 대상: 모든 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) 요청 또는 응답 처리를 중단하지 않고 유효성 검사 오류를 로그합니다.

사용

사용법 참고 사항

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

로그

정책 실행 중의 유효성 검사 오류에 대한 세부 정보는 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}

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