OASValidation 정책

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

OASValidation 정책 정보

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

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

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

이 정책은 표준 정책이며 모든 환경 유형에 배포할 수 있습니다. 정책 유형과 각 환경 유형에서의 가용성에 대한 자세한 내용은 정책 유형을 참조하세요.

참고: API 프록시 수정 버전만 OpenAPI 사양을 저장할 수 있습니다. 리소스가 저장되는 위치를 참조하세요.

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

다음 표에는 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>

This element has the following attributes that are common to all policies:

Attribute	Default	Required?	Description
name	N/A	Required	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError	false	Optional	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow
enabled	true	Optional	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async	false	Deprecated	This attribute is deprecated.

하위 요소 참조

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

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value	N/A
Required?	Optional. If you omit <DisplayName>, the value of the policy's name attribute is used.
Type	String
Parent Element	<PolicyElement>
Child Elements	None

The <DisplayName> element uses the following syntax:

Syntax

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Example

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

The <DisplayName> element has no attributes or child elements.

<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> 요소에 속성 또는 하위 요소가 없습니다.

참고: OASValidation 정책이 전역 수준에서 설정된 보안 요구사항으로 <OASResource>를 지정하면 보안 요구사항이 시행되지 않습니다. 시행을 보장하려면 이 정책의 <OASResource> 요소에 전달된 OpenAPI 사양의 작업 수준에서 모든 보안 요구사항을 설정해야 합니다. 자세한 내용은 Apigee에서 알려진 문제를 참조하세요.

<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로 설정하여 유효성 검증 오류 후에 흐름 실행을 계속할지 여부를 제어할 수 있습니다.

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

기본값	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>

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

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>

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

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에서 정책 스키마를 사용할 수 있습니다.

오류 코드

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
steps.oasvalidation.Failed	400	The Request message body cannot be validated against the provided OpenAPI Specification.
steps.oasvalidation.Failed	500	The Response message body cannot be validated against the provided OpenAPI Specification.
steps.oasvalidation.SourceMessageNotAvailable	500	Variable specified in the <Source> element of the policy is either out of scope or cannot be resolved.
steps.oasvalidation.NonMessageVariable	500	<Source> element is set to a variable that is not of type message.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause
ResourceDoesNotExist	OpenAPI Specification referenced in the <OASResource> element does not exist.
ResourceCompileFailed	OpenAPI Specification that is included in the deployment contains errors that prevent it from being compiled. This generally indicates that the specification is not a well-formed OpenAPI Specification 3.0.
BadResourceURL	OpenAPI Specification referenced in the <OASResource> element cannot be processed. This can occur if the file is not a JSON or YAML file or the file URL is not specified correctly.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variable	Description	Example
fault.category	The category of the fault. When the policy rejects a request, this will always hold Step.	fault.category = "Step"
fault.name	The name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "ResourceDoesNotExist"
fault.reason	The reason for the fault. It is a human-readable string explaining the reason for the fault.	OASValidation OAS-1 with resource "oas://my-spec1.yaml": failed with reason: "[ERROR - POST operation not allowed on path '/persons/13'.: []]"
fault.subcategory	The subcategory of the fault. When the policy rejects a request, this will always hold OASValidationFailure.	fault.subcategory = "OASValidationFailure"
OASValidation.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	OASValidation.myoaspolicy.failed = true

지원되는 OpenAPI 사양 기능

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

참고: OASValidation 정책은 지원되지 않는 기능을 사용하는 OpenAPI 사양을 거부합니다. 이 경우 정책이 지원되지 않는 기능의 유효성 검사를 통과하지 못하며 API 프록시 배포가 실패합니다.

카테고리	지원됨	지원되지 않음
데이터 유형 형식	boolean date date-time double email 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	여러 서버 정의

스키마에서 패턴 사용

OpenAPI 사양 표준에서는 사양에서 매개변수 또는 필드의 데이터 유형을 설명하기 위해 schema를 규정할 수 있습니다. 문자열 유형의 매개변수 또는 필드의 경우 스키마는 문자열의 유효한 형식을 정의하는 정규 표현식(정규식)인 pattern을 정의할 수도 있습니다.

예를 들어 다음 OpenAPI 사양 프래그먼트를 살펴보겠습니다.

paths:
  /products/{product-id}:
    get:
      operationId: getProduct
      summary: Get product by id
      description: returns information regarding a product, by id
      parameters:
        - name: product-id
          in: path
          description: id of the product
          required: true
          schema:
            type: string
            pattern: '^\w{3}-\d{4}$'

이 사양을 사용하려면 getProduct 작업의 경우 product-id 매개변수가 3단어 문자, 대시, 소수점 이하 4자리를 규정하는 특정 정규식을 준수해야 합니다.

OpenAPI 사양은 문자열 값 유효성 검사의 패턴의 동작을 공식적으로 정의하기 위해 JSON 스키마 유효성 검사 표준 및 제한된 정규 표현식 구문 집합과 관련하여 스키마 작성자에게 권장사항을 위한 JSON 스키마 코어 표준을 다릅니다. 이 후자의 표준에서는 OpenAPI 사양 문서 내부의 패턴에서 다른 기능들 중에서도 탐색(전방 탐색 및 후방 탐색), 역참조, 8진수 문자 표현식을 사용하지 않을 것을 권장합니다.

기본적으로 Apigee는 OASValidation 정책에서 참조하는 OpenAPI 사양 문서의 유효성을 검사하고 사양 문서의 형식이 올바르지 않은 경우 오류를 보고합니다. 또한 Apigee는 사양 문서의 정규식 패턴 유효성을 검사하고 발견된 문제를 보고합니다.

권장 하위 집합 이외의 정규식 기능을 사용하는 경우 Apigee는 정규식의 유효성을 검사하지 않으며 OpenAPI 사양 문서의 추가 유효성 검사를 정지합니다. 문서 또는 권장 하위 집합 외부의 기능을 사용하는 정규식에서 오류가 있거나 Apigee 런타임에서 정규식 기능을 지원하지 않는 경우 정책이 실행될 때 런타임 시에만 오류가 감지됩니다.

다음 표에는 몇 가지 예시가 나와 있습니다.

패턴	동작
^\w{3}-\d{4}$	패턴이 유효합니다. 권장 하위 집합 내의 정규식 기능만 사용합니다. Apigee는 프록시의 저장 또는 가져오기를 허용하고, 런타임 시 OASValidation 정책이 의도한 대로 작동하여, 패턴에 대해 매개변수를 검증합니다.
^([a-z]\w{3}-\d{4}$	패턴이 잘못되었습니다. 닫는 괄호가 누락되었습니다. 이 패턴은 권장 하위 집합 이외의 정규식 기능을 사용하지 않습니다. Apigee는 API 프록시를 가져오거나 저장할 때 이 오류를 보고합니다.
^(?![a-z]\w{3}-\d{4}$	패턴이 잘못되었습니다. 앞의 예시와 같이 닫는 괄호가 누락되었습니다. 하지만 정규식이 권장되는 정규식 기능 하위 집합 범위를 벗어나는 부정 전방 탐색을 사용하므로 Apigee는 API 프록시를 저장하거나 가져올 때 이 오류를 보고하지 않습니다. 이 오류는 정책이 실행될 때 런타임 시에만 감지됩니다.
^(?![a-z])\w{3}-\d{4}$	유효한 패턴이지만, 권장되는 정규식 기능의 하위 집합을 벗어나는 부정 전방 탐색을 사용합니다. Apigee는 OpenAPI 사양 문서의 유효성 검사를 정지합니다. Apigee 런타임은 실제로 부정 전방 탐색을 지원하므로 런타임 시 이 패턴을 사용하여 사양을 참조하는 OASValidation 정책을 실행하면 Apigee가 이 정규식을 올바르게 적용하여 매개변수 값을 검증합니다.
^(a)?b(?(1)c|d)$	패턴이 유효하지만, 권장되는 정규식 기능의 하위 집합을 벗어나는 캡처 그룹 조건부를 사용합니다. Apigee는 OpenAPI 사양 문서의 유효성 검사를 정지합니다. Apigee 런타임은 이 정규식 기능을 지원하지 않으므로 런타임 시 이 패턴을 사용하여 사양을 참조하는 OASValidation 정책을 실행하면 Apigee가 오류를 반환합니다.

런타임 실패를 방지하려면 정규식에서 권장되는 기능의 하위 집합만 사용하는 것이 좋습니다.

관련 주제

• JSON 위협 보호 정책
• SOAPMessageValidation 정책