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 프록시 번들에 리소스로 추가합니다.

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

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

다음 표에는 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 해당 없음 필수

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

오류 코드

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

런타임 오류

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

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

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

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

배포 오류

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

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

오류 변수

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

변수 설명 예
fault.category 장애 카테고리입니다. 정책이 요청을 거부하면 항상 Step을 유지합니다. fault.category = "Step"
fault.name 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다. fault.name Matches "ResourceDoesNotExist"
fault.reason 오류의 원인입니다. 오류의 원인을 설명하는, 사람이 읽을 수 있는 문자열입니다. OASValidation OAS-1 with resource "oas://my-spec1.yaml": failed with reason: "[ERROR - POST operation not allowed on path '/persons/13'.: []]"
fault.subcategory 오류의 하위 카테고리입니다. 정책이 요청을 거부하면 항상 OASValidationFailure을 유지합니다. fault.subcategory = "OASValidationFailure"
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
 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가 오류를 반환합니다.

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

관련 주제