Политика проверки OAS

Вы просматриваете документацию Apigee Edge .
Перейти к документации Apigee X. info

О политике валидации OAS

Политика OASValidation (проверка спецификации OpenAPI) позволяет проверять входящие запросы и ответы на соответствие спецификации OpenAPI 3.0 (JSON или YAML). См. раздел «Какое содержимое проверяется?»

Политика OASValidation определяет имя спецификации OpenAPI, используемой для проверки при выполнении шага, к которому она прикреплена. Спецификация OpenAPI хранится как ресурс в следующем стандартном расположении в пакете прокси-сервера API: apiproxy/resources/oas . Спецификация OpenAPI должна иметь расширение .json , .yml , .yaml .

Добавьте спецификацию OpenAPI в качестве ресурса в пакет прокси API с помощью пользовательского интерфейса или API, как описано в разделе Управление ресурсами .

Какой контент проверяется?

В следующей таблице обобщено содержимое сообщения-запроса , проверяемое политикой OASValidation, по компонентам.

В следующей таблице обобщено содержимое ответного сообщения , проверяемое политикой OASValidation, по компонентам.

Образцы

В следующих примерах показаны некоторые способы использования политики OASValidation для проверки сообщений на соответствие спецификации OpenAPI 3.0.

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

<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.

<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>

<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>

Этот элемент имеет следующие атрибуты, общие для всех политик:

Ссылка на дочерний элемент

В этом разделе описываются дочерние элементы <OASValidation> .

<DisplayName>

Используйте в дополнение к атрибуту name , чтобы обозначить политику в редакторе прокси-сервера пользовательского интерфейса управления другим, более естественно звучащим именем.

Элемент <DisplayName> является общим для всех политик.

Элемент <DisplayName> использует следующий синтаксис:

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

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

Элемент <DisplayName> не имеет атрибутов или дочерних элементов.

<OASResource>

Указывает спецификацию OpenAPI для проверки. Вы можете сохранить этот файл:

• В области действия API-прокси в папке /apiproxy/resources/oas в пакете API-прокси
• В разделе Resources окна «Навигатор» редактора прокси API.

Более подробную информацию см. в разделе Управление ресурсами .

Вы можете указать спецификацию OpenAPI, используя шаблон сообщения, например, {oas.resource.url} . В этом случае значение переменной потока oas.resource.url (в фигурных скобках) будет вычислено и подставлено в строку полезной нагрузки во время выполнения. Подробнее см. в разделе Шаблоны сообщений .

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

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

Элемент <OASResource> не имеет атрибутов или дочерних элементов.

<Параметры>

Настраивает параметры политики.

<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 , чтобы проверить только наличие тела сообщения.

Вы можете контролировать, будет ли продолжено выполнение потока после ошибки проверки, установив атрибут continueOnError для элемента <OASValidation> в значение true .

<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>

Настраивает поведение политики, если в запросе присутствуют параметры заголовка, запроса или cookie, которые не определены в спецификации OpenAPI.

<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>

<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 , чтобы вызвать сбой выполнения политики.

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

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

<Query> (дочерний элемент <AllowUnspecifiedParameters> )

Настраивает поведение политики, если в запросе присутствуют параметры запроса, не определенные в спецификации OpenAPI.

Чтобы разрешить указывать в запросе параметры, не определенные в спецификации OpenAPI, установите для этого параметра значение true . В противном случае установите для этого параметра значение false , чтобы вызвать сбой выполнения политики.

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

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

<Cookie> (дочерний элемент <AllowUnspecifiedParameters> )

Настраивает поведение политики, если в запросе присутствуют параметры cookie, не определенные в спецификации OpenAPI.

Чтобы разрешить указывать в запросе параметры cookie, не определенные в спецификации OpenAPI, установите для этого параметра значение true . В противном случае установите для этого параметра значение false , чтобы вызвать сбой выполнения политики.

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

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

<Source>

JSON-сообщение, которое необходимо оценить на предмет атак с использованием полезной нагрузки JSON. Чаще всего для этого параметра устанавливается значение request , поскольку обычно требуется оценивать входящие запросы от клиентских приложений. Установите значение response для оценки ответных сообщений. Установите значение message для автоматической оценки сообщения-запроса, когда политика прикреплена к потоку запросов, и сообщения-ответа, когда политика прикреплена к потоку ответов.

<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, когда эта политика вызывает ошибку. Эту информацию важно знать, если вы разрабатываете правила обработки ошибок. Дополнительные сведения см. в разделах Что нужно знать об ошибках политики и Обработка ошибок .

Ошибки выполнения

Эти ошибки могут возникнуть при выполнении политики.

Ошибки развертывания

Эти ошибки могут возникнуть при развертывании прокси-сервера, содержащего эту политику.

Переменные неисправности

Эти переменные устанавливаются, когда эта политика вызывает ошибку во время выполнения. Дополнительные сведения см. в разделе Что нужно знать об ошибках политики .

Поддерживаемые функции спецификаций OpenAPI

Политика OASValidation поддерживает функции спецификации OpenAPI, которые перечислены в следующей таблице по категориям. Также перечислены функции, которые не поддерживаются.

Похожие темы

• Политика защиты от угроз JSON
• Политика проверки сообщений SOAP