Политика проверки 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