Правила OASValidation

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

Правила OASValidation

Правило OASValidation (проверка спецификации OpenAPI) позволяет проверить входящий запрос или ответ на соответствие спецификации OpenAPI 3.0 (JSON или YAML). Подробнее о том, какой контент проверяется…

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

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

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

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

Компоненты Запросить проверку
Basepath Проверяет базовый путь, определенный прокси-сервером API, и игнорирует базовый путь, указанный в спецификации OpenAPI.
Путь Проверяет, соответствует ли путь запроса (без базового пути) одному из шаблонов пути, определенных в спецификации OpenAPI.
Глагол Проверяет, определен ли глагол для пути в спецификации OpenAPI.
Тело запроса
  • Проверяет, есть ли в запросе тело письма, если это необходимо.
  • При необходимости проверяет тело сообщения на соответствие схеме тела запроса операции в спецификации OpenAPI. Настроить этот параметр можно с помощью <ValidateMessageBody>.

Примечание. Правила проверяют тело запроса на соответствие спецификации OpenAPI, только если для параметра Content-Type задано значение application/json. Если тип контента не задан как application/json, проверка тела запроса будет пройдена автоматически (без фактической проверки контента).

Параметры
  • Проверяет, есть ли в запросе необходимые параметры, в том числе параметры пути, заголовка, запроса и файла cookie.
  • Проверяет, соответствуют ли значения параметров значениям, определенным в спецификации OpenAPI.
  • При необходимости проверяет, есть ли в запросе параметры, не определенные в спецификации OpenAPI. Настроить этот параметр можно с помощью <AllowUnspecifiedParameters>.

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

Компоненты Проверка ответов
Путь Проверяет, соответствует ли путь запроса (без базового пути) одному из шаблонов пути, определенных в спецификации OpenAPI.
Глагол Проверяет, определен ли глагол для пути в спецификации OpenAPI.
Тело ответного сообщения
  • Проверяет наличие тела сообщения в ответе, если это необходимо.
  • Проверяет, присутствуют ли заголовки ответов из спецификации OpenAPI в сообщении ответа и соответствует ли значение заголовков ответов схеме.
  • При необходимости проверяет тело сообщения на соответствие схеме тела ответа операции в спецификации OpenAPI. Настроить этот параметр можно с помощью <ValidateMessageBody>.

Примеры

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

Как проверить сообщение с запросом

В примере ниже правила myoaspolicy проверяют тело запроса на соответствие схеме тела запроса операции, определенной в спецификации OpenAPI my-spec.json. 

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

Если текст сообщения не соответствует спецификации OpenAPI, возвращается ошибка policies.oasvalidation.Failed.

Проверка параметров

В примере ниже показано, как настроить правило, чтобы оно не выполнялось, если в запросе указан параметр заголовка, запроса или файла cookie, не определенный в спецификации 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>

Правило по умолчанию

В следующем примере показаны настройки по умолчанию, которые задаются при добавлении правила проверки OAS в поток в интерфейсе Apigee:

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

continueOnError ЛОЖЬ Необязательный Установите значение «false», чтобы возвращать ошибку при сбое политики. Это ожидаемое поведение для большинства политик. Установите значение «true», чтобы выполнение потока продолжалось даже после сбоя политики.
enabled истинный Необязательный Установите значение «true», чтобы применить политику. Установите значение «false», чтобы «отключить» политику. Политика не будет применяться, даже если она остается присоединенной к потоку.
async ЛОЖЬ Устаревший Этот атрибут устарел.

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

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

<DisplayName>

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

Элемент <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
  • В разделе Resources редактора прокси-сервера API в представлении навигатора.

Подробнее о том, как управлять ресурсами…

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

Значение по умолчанию Нет
Обязательно? Обязательно
Тип Строка
Родительский элемент <OASValidation>
Дочерние элементы Нет

Синтаксис

Элемент <OASResource> имеет следующий синтаксис:

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

Пример

В приведенном ниже примере используется спецификация my-spec.yaml, которая хранится в пакете прокси-сервера API в каталоге /apiproxy/resources/oas:

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

Вы можете указать, следует ли продолжать выполнение потока после ошибки проверки, задав для атрибута continueOnError элемента <OASValidation> значение 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>

Настраивает поведение правила, если в запросе есть параметры заголовка, запроса или файла cookie, которые не определены в спецификации 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>

Пример

В примере ниже показано, как настроить правило, чтобы оно не выполнялось, если в запросе указан параметр заголовка, запроса или файла cookie, не определенный в спецификации 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>

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

Чтобы разрешить указывать в запросе параметры файлов cookie, не определенные в спецификации 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> задана переменная, тип которой не message.

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

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

Название ошибки Причина
ResourceDoesNotExist Спецификация OpenAPI, на которую ссылается элемент <OASResource>, не существует.
ResourceCompileFailed Спецификация OpenAPI, включенная в развертывание, содержит ошибки, из-за которых ее нельзя скомпилировать. Обычно это означает, что спецификация не соответствует требованиям OpenAPI Specification 3.0.
BadResourceURL Не удалось обработать спецификацию OpenAPI, указанную в элементе <OASResource>. Это может произойти, если файл не является файлом 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
 binary
byte
password
Объект дискриминатора mapping
propertyName 		Н/Д
Объект типа медиаконтента схема; encoding
example
examples
Объект операций parameters
requestBody
responses
security (частичная поддержка) 		обратные вызовы
устаревшие
серверы
Объект параметров 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 		Н/Д
Объект схемы $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 		Несколько определений сервера

Статьи по теме