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

Вы просматриваете документацию 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, по компонентам.

Компоненты Запросить проверку
Базовый путь Проверяет базовый путь, определенный прокси-сервером 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 проверяет тело сообщения запроса на соответствие схеме тела сообщения запроса операции, определенной в спецификации 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 .

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

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

<Валидатемессажебоди>

Указывает, должна ли политика проверять тело сообщения на соответствие схеме тела запроса операции в спецификации 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 , так как вам обычно необходимо оценивать входящие запросы от клиентских приложений. Установите значение «ответ» , чтобы оценить ответные сообщения. Установите значение 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 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
ша1/ша256/ша512
нить
ури
uri-шаблон
uuid
 двоичный
байт
пароль
Объект дискриминатора картографирование
имя свойства		 Н/Д
Объект типа носителя схема кодирование
пример
примеры
Объект операций параметры
тело запроса
ответы
безопасность (частичная поддержка)		 обратные вызовы
устарел
серверы
Объект параметров Разрешить пустое значение
в ( query , header , path )
необходимый
ответы
схема
стиль ( deepObject , form , formmatrix , label , pipeDelimited , simple , spaceDelimited )

Примечание. deepObject поддерживает только строковые параметры; массивы и вложенные объекты не поддерживаются.		 РазрешитьЗарезервировано
устарел
пример
примеры
содержание
Объект путей удалить
получать
голова
параметры
параметры
пластырь
почта
помещать
след
переменные		 серверы
Объект тела запроса приложение/json
приложение/hal+json
application/x-www-form-urlencoded (объект encoding не поддерживается)
содержание
необходимый		 приложение/xml
multipart/данные формы
текстовый/обычный
текст/xml
Объект ответа приложение/json
приложение/hal+json
application/x-www-form-urlencoded (объект encoding не поддерживается)
содержание
заголовки		 приложение/xml
ссылки
текстовый/обычный
текст/xml
Объект ответов по умолчанию
Код состояния HTTP		 Н/Д
Объект схемы $ref
дополнительные свойства (только вариант с логическим флагом)
allOf (игнорируется, если additionalProperties имеют значение false )
AnyOf
перечисление
эксклюзивныйМаксимум/эксклюзивныйМинимум
формат
предметы
максимум/минимум
макситемс/минитемс
МаксДлина/МинДлина
макспропертиес/минпропертиес
MultipleOf
нет
обнуляемый
один из
шаблон
характеристики
необходимый
заголовок
тип
уникальные предметы		 устарел
пример
только чтение
writeOnly
xml
Объект схемы безопасности in ( header , query ) (игнорируется, если type http )
имя
введите ( apiKey , http )		 формат носителя
потоки
опенидконнектурл
схема
Серверный объект URL
переменные		 Несколько определений серверов

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