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

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

О политике OASValidation

Политика OASValidation (проверка спецификации OpenAPI) позволяет проверять входящие запросы или ответы на соответствие спецификации 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 . Если Content-Type не установлен на 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 , которая хранится в каталоге /apiproxy/resources/oas в пакете API-прокси:

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

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

<Параметры>

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

Значение по умолчанию н/д
Необходимый? Необязательный
Тип Сложный тип
Родительский элемент <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 .

Значение по умолчанию ЛОЖЬ
Необходимый? Необязательный
Тип Логический
Родительский элемент <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 , чтобы выполнение политики завершилось с ошибкой.

Значение по умолчанию истинный
Необходимый? Логический
Тип Сложный тип
Родительский элемент <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 , чтобы выполнение политики завершилось с ошибкой.

Значение по умолчанию истинный
Необходимый? Логический
Тип Сложный тип
Родительский элемент <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 , чтобы выполнение политики завершилось с ошибкой.

Значение по умолчанию истинный
Необходимый? Логический
Тип Сложный тип
Родительский элемент <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 для автоматической оценки сообщения request, когда политика прикреплена к потоку запроса, и сообщения response, когда политика прикреплена к потоку ответа.

Значение по умолчанию запрос
Необходимый? Необязательный
Тип Нить
Родительский элемент <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 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, которые кратко описаны в следующей таблице по категориям. Также перечислены функции, которые не поддерживаются.

Категория Поддерживается Не поддерживается
Форматы типов данных логический
дата
дата-время
двойной
электронная почта
плавать
int32/int64
ipv4/ipv6
мд5
sha1/sha256/sha512
нить
ури
uri-template
uuid
 бинарный
байт
пароль
Объект-дискриминатор картирование
propertyName		 Н/Д
Объект типа носителя схема кодирование
пример
примеры
Объект операций параметры
requestBody
ответы
безопасность (частичная поддержка)		 обратные вызовы
устаревший
серверы
Объект параметров allowEmptyValue
в ( query , header , path )
необходимый
ответы
схема
style ( deepObject , form , formmatrix , label , pipeDelimited , simple , spaceDelimited )

Примечание: deepObject поддерживает только строковые параметры; массивы и вложенные объекты не поддерживаются.		 allowReserved
устаревший
пример
примеры
содержание
Объект Paths удалить
получать
голова
параметры
параметры
пластырь
почта
помещать
след
переменные		 серверы
Объект тела запроса приложение/json
application/hal+json
application/x-www-form-urlencoded ( encoding объекта не поддерживается)
содержание
необходимый		 приложение/xml
multipart/form-data
текст/простой
текст/xml
Объект ответа приложение/json
application/hal+json
application/x-www-form-urlencoded ( encoding объекта не поддерживается)
содержание
заголовки		 приложение/xml
ссылки
текст/простой
текст/xml
Объект ответов по умолчанию
Код состояния HTTP		 Н/Д
Объект схемы $ref
additionalProperties (только вариант с логическим флагом)
allOf (игнорируется, если additionalProperties имеет значение false )
любой из
перечисление
эксклюзивныйМаксимум/эксклюзивныйМинимум
формат
предметы
максимум/минимум
maxItems/minItems
максДлина/минДлина
maxProperties/minProperties
кратное
нет
допускающий значение null
один из
шаблон
характеристики
необходимый
заголовок
тип
уникальные предметы		 устаревший
пример
только для чтения
writeOnly
XML
объект схемы безопасности в ( header , query ) (игнорируется, если type — http )
имя
тип ( apiKey , http )		 bearerFormat
потоки
openIdConnectUrl
схема
Объект сервера url
переменные		 Множественные определения серверов

Связанные темы