OASValidation 정책

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보

OASValidation 정책 정보

OASValidation(OpenAPI 사양 유효성 검사) 정책을 사용하면 OpenAPI 3.0 사양(JSON 또는 YAML)에 대한 수신 요청 또는 응답 메시지를 확인할 수 있습니다. 어떤 콘텐츠가 검증되나요?를 참조하세요.

OASValidation 정책은 정책이 연결된 단계가 실행될 때 유효성 검사에 사용할 OpenAPI 사양의 이름을 지정합니다. OpenAPI 사양은 API 프록시 번들 내의 다음 표준 위치(apiproxy/resources/oas)에 리소스로 저장됩니다. OpenAPI 사양에는 .json, .yml, .yaml 확장 프로그램이 있어야 합니다.

리소스 관리에 설명된 대로 UI 또는 API를 사용하여 OpenAPI 사양을 API 프록시 번들에 리소스로 추가합니다.

어떤 콘텐츠가 검증되나요?

다음 표에는 OASValidation 정책에 따라 유효성 검사가 완료된 요청 메시지 콘텐츠가 구성요소별로 요약되어 있습니다.

구성요소 요청 유효성 검사
기본 경로 API 프록시에 의해 정의된 기본 경로를 검증합니다. OpenAPI 사양에 지정된 기본 경로를 무시합니다.
경로 요청 경로(기본 경로 생략)가 OpenAPI 사양에 정의된 경로 패턴 중 하나와 일치하는지 확인합니다.
동사 OpenAPI 사양의 경로에 동사가 정의되었는지 확인합니다.
요청 메시지 본문
  • 필요한 경우 요청에 메시지 본문이 존재하는지 확인합니다.
  • 필요한 경우 OpenAPI 사양에서 작업의 요청 본문 스키마에 대한 메시지 본문을 검증합니다. <ValidateMessageBody>를 사용하여 이 옵션을 구성합니다.

참고: 이 정책은 Content-Type이 application/json으로 설정된 경우에만 OpenAPI 사양에 대해 요청 메시지 본문을 검증합니다. 콘텐츠 유형이 application/json으로 설정되지 않은 경우 요청 메시지 본문 유효성 검사는 실제로 콘텐츠를 검증하지 않고 자동으로 전달합니다.

매개변수
  • 경로, 헤더, 쿼리, 쿠키 매개변수를 포함하여 필수 매개변수가 요청에 있는지 검증합니다.
  • 매개변수 값이 OpenAPI 사양에 정의된 값과 일치하는지 검증합니다.
  • 필요한 경우 OpenAPI 사양에 정의되지 않은 요청에 매개변수가 있는지 검증합니다. <AllowUnspecifiedParameters>를 사용하여 이 옵션을 구성합니다.

다음 표에는 OASValidation 정책에 따라 확인된 응답 메시지 콘텐츠가 구성요소별로 요약되어 있습니다.

구성요소 응답 확인
경로 요청 경로(기본 경로 생략)가 OpenAPI 사양에 정의된 경로 패턴 중 하나와 일치하는지 확인합니다.
동사 OpenAPI 사양의 경로에 동사가 정의되었는지 확인합니다.
응답 메시지 본문
  • 필요한 경우 응답에 메시지 본문이 있는지 확인합니다.
  • OpenAPI 사양의 응답 헤더가 응답 메시지에 있으며 응답 헤더의 값이 스키마와 일치하는지 확인합니다.
  • 필요한 경우 OpenAPI 사양에 있는 작업의 응답 본문 스키마에 대한 메시지 본문의 유효성을 검사합니다. <ValidateMessageBody>를 사용하여 이 옵션을 구성합니다.

샘플

다음 예시에서는 OASValidation 정책을 사용하여 OpenAPI 3.0 사양에 대한 메시지를 검증할 수 있는 몇 가지 방법을 보여줍니다.

요청 메시지 유효성 검사

다음 예시에서 myoaspolicy 정책은 my-spec.json OpenAPI 사양에 정의된 작업의 요청 메시지 본문 스키마를 기준으로 요청 메시지 본문의 유효성을 검사합니다. 

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.json</OASResource>
   <Options>
      <ValidateMessageBody>true</ValidateMessageBody>
   </Options>
   <Source>request</Source>
</OASValidation>

메일 본문이 OpenAPI 사양을 준수하지 않는 경우 policies.oasvalidation.Failed 오류가 반환됩니다.

매개변수 유효성 검사

다음 예시에서는 OpenAPI 사양에서 정의되지 않은 요청에 헤더, 쿼리, 쿠키 매개변수가 지정된 경우 정책이 실패하도록 구성합니다.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<OASValidation> 요소

OpenAPI 사양 유효성 검사 정책을 정의합니다.

기본값 아래의 기본 정책 탭을 참조하세요.
필수 여부 필수
유형 복합 객체
상위 요소 해당 사항 없음
하위 요소 <DisplayName>
<OASResource>
<Source>
<Options>
<Source>

문법

<OASValidation> 요소는 다음 구문을 사용합니다.

<OASValidation
  continueOnError="[true|false]"
  enabled="[true|false]"
  name="policy_name"
>
    <!-- All OASValidation child elements are optional except OASResource -->
    <DisplayName>policy_display_name</DisplayName>
    <OASResource>validation_JSON_or_YAML</OASResource>
    <Options>
        <ValidateMessageBody>[true|false]</ValidateMessageBody>
        <AllowUnspecifiedParameters>
            <Header>[true|false]</Header>
            <Query>[true|false]</Query>
            <Cookie>[true|false]</Cookie>
        </AllowUnspecifiedParameters>
    </Options>
    <Source>message_to_validate</Source>
</OASValidation>

기본 정책

다음 예시에서는 Apigee UI의 흐름에 OAS 유효성 검사 정책을 추가할 때의 기본 설정을 보여줍니다.

<OASValidation continueOnError="false" enabled="true" name="OpenAPI-Spec-Validation-1">
    <DisplayName>OpenAPI Spec Validation-1</DisplayName>
    <Properties/>
    <Source>request</Source>
    <OASResource>oas://OpenAPI-Spec-Validation-1.yaml</OASResource>
</OASValidation>

이 요소에는 다음과 같이 모든 정책에 공통된 속성이 있습니다.

속성 기본 필수 여부 설명
name N/A 필수

정책의 내부 이름입니다. name 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다.

원하는 경우 <DisplayName> 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.
continueOnError false 선택사항 정책이 실패할 때 오류를 반환하려면 'false'로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패한 후에도 흐름 실행이 계속되게 하려면 'true'로 설정합니다.
enabled true 선택 정책을 시행하려면 'true'로 설정합니다. 정책을 '사용 중지'하려면 'false'로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.
async   false 지원 중단됨 이 속성은 지원이 중단되었습니다.

하위 요소 참조

이 섹션에서는 <OASValidation>의 하위 요소를 설명합니다.

<DisplayName>

name 속성 외에 이 요소를 사용하여 관리 UI 프록시 편집기에서 자연스러운 다른 이름으로 정책의 라벨을 지정합니다.

<DisplayName> 요소는 모든 정책에 공통으로 적용됩니다.

기본값 해당 사항 없음
필수 여부 선택사항입니다. <DisplayName>을 생략하면 정책의 name 속성 값이 사용됩니다.
유형 문자열
상위 요소 <PolicyElement>
하위 요소 없음

<DisplayName> 요소는 다음 구문을 사용합니다.

문법

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

예

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 요소에 속성 또는 하위 요소가 없습니다.

<OASResource>

유효성을 검사할 OpenAPI 사양을 지정합니다. 이 파일을 다음에서 저장할 수 있습니다.

  • API 프록시 번들의 /apiproxy/resources/oas 아래 API 프록시 범위
  • API 프록시 편집기의 탐색기 보기 Resources 섹션

자세한 내용은 리소스 관리를 참조하세요.

{oas.resource.url}과 같은 메시지 템플릿을 사용하여 OpenAPI 사양을 지정할 수 있습니다. 이 경우 흐름 변수 oas.resource.url의 값(중괄호)이 런타임 시에 페이로드 문자열로 대체됩니다. 자세한 내용은 메시지 템플릿을 참조하세요.

기본값 없음
필수 여부 필수
유형 문자열
상위 요소 <OASValidation>
하위 요소 없음

문법

<OASResource> 요소는 다음 구문을 사용합니다.

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   ...
</OASValidation>

예

다음 예시에서는 API 프록시 번들의 /apiproxy/resources/oas에 저장된 my-spec.yaml 사양을 참조합니다.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
</OASValidation>

<OASResource> 요소에 속성 또는 하위 요소가 없습니다.

<Options>

정책의 옵션을 구성합니다.

기본값 해당 사항 없음
필수 여부 선택사항
유형 복합 유형
상위 요소 <OASValidation>
하위 요소 <ValidateMessageBody>
<AllowUnspecifiedParameters>

문법

<Options> 요소는 다음 구문을 사용합니다.

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <ValidateMessageBody>[true|false]</ValidateMessageBody>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
         <Query>[true|false]</Query>
         <Cookie>[true|false]</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

예

다음 예시에서는 정책 옵션을 구성합니다. 각 옵션에 대한 자세한 내용은 아래를 참조하세요.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <ValidateMessageBody>false</ValidateMessageBody>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<ValidateMessageBody>

정책이 OpenAPI 사양의 작업 요청 본문 스키마에 대해 메시지 본문의 유효성을 검사해야 하는지 여부를 지정합니다. 메시지 본문 콘텐츠의 유효성을 검사하려면 true로 설정합니다. 메시지 본문이 존재하는지만 확인하려면 false로 설정합니다.

<OASValidation> 요소의 continueOnError 속성을 true로 설정하여 유효성 검사 오류 후 흐름 실행이 계속되는지 여부를 제어할 수 있습니다.

기본값 false
필수 여부 선택사항
유형 불리언
상위 요소 <Options>
하위 요소 없음

문법

<ValidateMessageBody> 요소는 다음 구문을 사용합니다.

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
         <ValidateMessageBody>[true|false]</ValidateMessageBody>
   </Options>
   ...
</OASValidation>

예

다음 예시에서는 메시지 본문 콘텐츠의 유효성 검사를 사용 설정합니다.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <ValidateMessageBody>true</ValidateMessageBody>
   </Options>
</OASValidation>

<AllowUnspecifiedParameters>

OpenAPI 사양에 정의되지 않은 요청에 헤더, 쿼리, 쿠키 매개변수가 있는 경우 정책의 동작을 구성합니다.

기본값 해당 사항 없음
필수 여부 선택사항
유형 복합 유형
상위 요소 <Options>
하위 요소 <Header>
<Query>
<Cookie>

문법

<AllowUnspecifiedParameters> 요소는 다음 구문을 사용합니다.

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
         <Query>[true|false]</Query>
         <Cookie>[true|false]</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

예

다음 예시에서는 OpenAPI 사양에서 정의되지 않은 요청에 헤더, 쿼리, 쿠키 매개변수가 지정된 경우 정책이 실패하도록 구성합니다.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

OpenAPI 사양에 정의되지 않은 헤더 매개변수가 요청에 있는 경우 정책의 동작을 구성합니다.

OpenAPI 사양에서 정의되지 않은 요청에 헤더 매개변수를 지정할 수 있게 하려면 이 매개변수를 true로 설정합니다. 그렇지 않으면 이 매개변수를 false로 설정하여 정책 실행이 실패하도록 합니다.

기본값 true
필수 여부 부울
유형 복합 유형
상위 요소 <AllowUnspecifiedParameters>
하위 요소 없음

문법

<Header> 요소는 다음 구문을 사용합니다.

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

예

다음 예시에서는 OpenAPI 사양에 정의되지 않은 요청에 헤더 매개변수가 지정된 경우 정책이 실패하도록 구성합니다.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Query>(<AllowUnspecifiedParameters>의 하위 요소)

OpenAPI 사양에 정의되지 않은 쿼리 매개변수가 요청에 있는 경우 정책의 동작을 구성합니다.

OpenAPI 사양에서 정의되지 않은 요청에 쿼리 매개변수를 지정할 수 있도록 하려면 이 매개변수를 true로 설정합니다. 그렇지 않으면 이 매개변수를 false로 설정하여 정책 실행이 실패하도록 합니다.

기본값 true
필수 여부 부울
유형 복합 유형
상위 요소 <AllowUnspecifiedParameters>
하위 요소 없음

문법

<Query> 요소는 다음 구문을 사용합니다.

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

예

다음 예에서는 OpenAPI 사양에 정의되지 않은 요청에 쿼리 매개변수가 지정된 경우 정책이 실패하도록 구성합니다.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>false</Query>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

OpenAPI 사양에 정의되지 않은 쿠키 매개변수가 요청에 있는 경우 정책의 동작을 구성합니다.

OpenAPI 사양에서 정의되지 않은 요청에 쿠키 매개변수를 지정할 수 있도록 하려면 이 매개변수를 true로 설정합니다. 그렇지 않으면 이 매개변수를 false로 설정하여 정책 실행이 실패하도록 합니다.

기본값 true
필수 여부 부울
유형 복합 유형
상위 요소 <AllowUnspecifiedParameters>
하위 요소 없음

문법

<Cookie> 요소는 다음 구문을 사용합니다.

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

예

다음 예에서는 OpenAPI 사양에 정의되지 않은 요청에 쿼리 매개변수가 지정된 경우 정책이 실패하도록 구성합니다.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Source>

JSON 페이로드 공격에 대해 평가할 JSON 메시지입니다. 일반적으로 클라이언트 앱에서 인바운드 요청을 평가해야 하므로 일반적으로 request로 설정됩니다. 응답 메시지를 평가하려면 response으로 설정합니다. 정책이 요청 흐름에 연결될 때 요청 메시지를 자동으로 평가하고 정책이 응답 흐름에 첨부될 때 응답 메시지를 자동으로 평가하려면 message로 설정합니다.

기본값 요청
필수 여부 선택사항
유형 문자열
상위 요소 <Source>
하위 요소 없음

문법

<Source> 요소는 다음 구문을 사용합니다.

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Source>[message|request|response]</Source>
   ...
</OASValidation>

예

다음 예시에서는 정책이 요청 흐름에 연결되면 요청 메시지를 자동으로 평가하고 정책이 응답 흐름에 연결되면 응답 메시지를 자동으로 평가합니다.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Source>message</Source>
</OASValidation>

<Source> 요소에 속성 또는 하위 요소가 없습니다.

스키마

각 정책 유형은 XML 스키마(.xsd)로 정의됩니다. 참고로 GitHub에서 정책 스키마를 사용할 수 있습니다.

오류 코드

이 섹션에서는 반환되는 오류 코드, 오류 메시지, 정책이 오류를 트리거할 때 Edge에서 설정하는 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.

런타임 오류

이러한 오류는 정책이 실행될 때 발생할 수 있습니다.

오류 코드 HTTP 상태 원인
steps.oasvalidation.Failed 500 제공된 OpenAPI 사양에 따라 요청 메시지 본문을 확인할 수 없습니다.
steps.oasvalidation.SourceMessageNotAvailable 500

정책의 <Source> 요소에 지정된 변수가 범위를 벗어나거나 확인할 수 없습니다.
steps.oasvalidation.NotMessageVariable 500

<Source> 요소는 메시지 유형이 아닌 변수로 설정됩니다.

배포 오류

이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.

오류 이름 원인
ResourceDoesNotExist <OASResource> 요소에서 참조된 OpenAPI 사양이 없습니다.
ResourceCompileFailed 배포에 포함된 OpenAPI 사양에는 컴파일할 수 없는 오류가 포함되어 있습니다. 이는 일반적으로 사양이 올바른 형식의 OpenAPI 사양 3.0이 아님을 나타냅니다.
BadResourceURL <OASResource> 요소에 참조된 OpenAPI 사양을 처리할 수 없습니다. 이 문제는 파일이 JSON 또는 YAML 파일이 아니거나 파일 URL이 올바르게 지정되지 않은 경우에 발생할 수 있습니다.

오류 변수

이러한 변수는 이 정책이 런타임 시 오류를 트리거할 때 설정됩니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.

변수 각 항목의 의미는 다음과 같습니다. 예
fault.name="fault_name" fault_name은 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다. fault.name Matches "ResourceDoesNotExist"
oasvalidation.policy_name.failed policy_name은 오류를 발생시킨 정책의 사용자 지정 이름입니다. oasvalidation.myoaspolicy.failed = true

지원되는 OpenAPI 사양 기능

OASValidation 정책은 다음 표에 요약된 OpenAPI 사양 기능을 카테고리별로 지원합니다. 지원되지 않는 기능도 나와 있습니다.

카테고리 지원됨 지원되지 않음
데이터 유형 형식 boolean
date
date-time
double
email
float
int32/int64
ipv4/ipv6
md5
sha1/sha256/sha512
string
uri
uri-template
uuid
 바이너리
바이트
비밀번호
구분자 객체 매핑
propertyName 		해당 사항 없음
미디어 유형 객체 schema 인코딩
예시
예시
작업 객체 매개변수
requestBody
응답
보안 (부분 지원) 		콜백
지원 중단된
서버
매개변수 객체 (query, header, path)의
allowEmptyValue
필수
응답
스키마
스타일 (deepObject, form, formmatrix, label, pipeDelimited, simple, spaceDelimited)

참고: deepObject는 문자열 매개변수만 지원합니다. 배열과 중첩된 객체는 지원되지 않습니다. 		allowBooking
지원 중단됨
예
예시
콘텐츠
경로 객체 삭제
get
head
옵션
매개변수
패치
post
put
trace
변수 		서버
요청 본문 객체 application/json
application/hal+json
application/x-www-form-urlencoded (encoding 객체는 지원되지 않음)
content
필수 		application/xml
multipart/form-data
text/plain
text/xml
응답 객체 application/json
application/hal+json
application/x-www-form-urlencoded (encoding 객체는 지원되지 않음)
content
headers 		application/xml
링크
text/plain
text/xml
응답 객체 기본값
HTTP 상태 코드 		해당 사항 없음
스키마 객체 $ref
additionalProperties (불리언 플래그 변형만 해당)
allOf (additionalProperties가 false인 경우 무시됨)
anyOf
enum
only최대/제외최소
형식
항목
최대/최소
maxItems/minItems
maxLength/minLength
maxProperties/minProperties
multipleOf
not
nullable
oneOf
pattern
titleItems
필수 유형
필수 유형

 지원 중단됨
예
readOnly
writeOnly
xml
보안 스키마 객체 위치 (header, query) (type가 http이면 무시됨)
name
유형 (apiKey, http) 		bearerFormat
flows
openIdConnectUrl
스키마
서버 객체 url
변수 		여러 서버 정의

관련 주제