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 사양의 경로에 동사가 정의되었는지 확인합니다. |
요청 메시지 본문 |
참고: 이 정책은 Content-Type이 |
매개변수 |
|
다음 표에는 OASValidation 정책을 통해 검증된 응답 메시지 콘텐츠가 구성요소별로 요약되어 있습니다.
구성요소 | 응답 확인 |
---|---|
경로 | 요청 경로(기본 경로 생략)가 OpenAPI 사양에 정의된 경로 패턴 중 하나와 일치하는지 확인합니다. |
동사 | OpenAPI 사양의 경로에 동사가 정의되었는지 확인합니다. |
응답 메시지 본문 |
|
샘플
다음 예시에서는 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 | 필수 |
정책의 내부 이름입니다. 원하는 경우 |
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로 설정하여 유효성 검증 오류 후에 흐름 실행을 계속할지 여부를 제어할 수 있습니다.
기본값 | 거짓 |
필수 여부 | 선택사항 |
유형 | 불리언 |
상위 요소 |
<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>
<Header>
(<AllowUnspecifiedParameters>
의 하위 요소)
OpenAPI 사양에서 정의되지 않은 요청에 헤더 매개변수가 있는 경우 정책의 동작을 구성합니다.
OpenAPI 사양에서 정의되지 않은 요청에 헤더 매개변수를 지정할 수 있게 하려면 이 매개변수를 true로 설정합니다. 그렇지 않으면 이 매개변수를 false로 설정하여 정책 실행이 실패하도록 합니다.
기본값 | 참 |
필수 여부 | 부울 |
유형 | 복합 유형 |
상위 요소 |
<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로 설정하여 정책 실행이 실패하도록 합니다.
기본값 | 참 |
필수 여부 | 부울 |
유형 | 복합 유형 |
상위 요소 |
<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로 설정하여 정책 실행이 실패하도록 합니다.
기본값 | 참 |
필수 여부 | 부울 |
유형 | 복합 유형 |
상위 요소 |
<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 |
정책의 |
|
steps.oasvalidation.NotMessageVariable |
500 |
|
build |
배포 오류
이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.
오류 이름 | 원인 | |
---|---|---|
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 float int32/int64 ipv4/ipv6 md5 sha1/sha256/sha512 string uri uri-template uuid |
binary byte password |
구분자 객체 | mapping propertyName |
해당 사항 없음 |
미디어 유형 객체 | schema | encoding example examples |
작업 객체 | parameters requestBody responses security(부분 지원) |
callbacks deprecated servers |
매개변수 객체 | allowEmptyValue in( query , header , path )required responses schema style( deepObject , form , formmatrix , label , pipeDelimited , simple , spaceDelimited )참고: deepObject 는 문자열 매개변수만 지원합니다. 배열 및 중첩된 객체는 지원되지 않습니다. |
allowReserved deprecated example examples content |
경로 객체 | delete get head options parameters patch post put trace variables |
실행 |
요청 본문 객체 | application/json application/hal+json application/x-www-form-urlencoded( encoding 객체는 지원되지 않음)content required |
application/xml multipart/form-data text/plain text/xml |
응답 객체 | application/json application/hal+json application/x-www-form-urlencoded( encoding 객체는 지원되지 않음)content headers |
application/xml links text/plain text/xml |
응답 객체 | default HTTP Status Code |
해당 사항 없음 |
스키마 객체 | $ref additionalProperties(부울 플래그 변수만) allOf ( additionalProperties 가 false 인 경우 무시)anyOf enum exclusiveMaximum/exclusiveMinimum format items maximum/minimum maxItems/minItems maxLength/minLength maxProperties/minProperties multipleOf not nullable oneOf pattern properties required title type uniqueItems |
deprecated example readOnly writeOnly xml |
보안 스키마 객체 | in(header , query )(type 이 http 인 경우 무시)name type( apiKey , http )
|
bearerFormat flows openIdConnectUrl scheme |
서버 객체 | url variables |
여러 서버 정의 |