Правила OASValidation

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

О правилах OASValidation

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

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

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

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

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

Компоненты Запросить проверку
Базовый путь Проверяет базовый путь, определенный прокси-сервером 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 Validation в поток в интерфейсе 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 в представлении Navigator редактора прокси-сервера 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
Объект Discriminator mapping
propertyName 		Н/Д
Объект типа медиа схема encoding
example
examples
Объект Operations 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
Объект Paths delete
get
head
options
parameters
patch
post
put
trace
variables 		серверы
Объект тела запроса application/json
application/hal+json
application/x-www-form-urlencoded (объект encoding не поддерживается)
content
обязательно 		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
Объект Responses 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 		Несколько определений серверов

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