Política OASValidation

Estás viendo la documentación de Apigee Edge.
Ve a la documentación de Apigee X. info

Información sobre la política OASValidation

La política OASValidation (Validación de especificaciones de OpenAPI) te permite validar un mensaje de solicitud o respuesta entrante con una especificación de OpenAPI 3.0 (JSON o YAML). Consulta ¿Qué contenido se valida?

La política OASValidation especifica el nombre de la especificación de OpenAPI que se usará para la validación cuando se ejecute el paso en el que se adjunta la política. La Especificación de OpenAPI se almacena como un recurso en la siguiente ubicación estándar dentro del paquete del proxy de API: apiproxy/resources/oas. La Especificación de OpenAPI debe tener una extensión .json, .yml, .yaml.

Agrega una especificación de OpenAPI como un recurso a un paquete de proxy de API mediante la IU o la API, como se describe en Administra recursos.

¿Qué contenido se valida?

En la siguiente tabla, se resume el contenido de los mensajes de solicitud que valida la política OASValidation por componente.

En la siguiente tabla, se resume el contenido de los mensajes de respuesta que valida la política OASValidation por componente.

Ejemplos

En los siguientes ejemplos, se muestran algunas de las formas en las que puedes usar la política OASValidation para validar mensajes con una Especificación de 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>

Elemento <OASValidation>

Define la política de validación de la especificación de 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>

This element has the following attributes that are common to all policies:

Referencia del elemento secundario

En esta sección, se describen los elementos secundarios de <OASValidation>.

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

The <DisplayName> element uses the following syntax:

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

The <DisplayName> element has no attributes or child elements.

<OASResource>

Especifica la especificación de OpenAPI que se va a validar. Puedes almacenar este archivo:

• En el alcance del proxy de API en /apiproxy/resources/oas, en el paquete del proxy de API
• En la sección Resources de la vista del navegador del editor de proxy de API.

Para obtener más información, consulta Administra recursos.

Puedes precisar la especificación de OpenAPI con una plantilla de mensajes, como {oas.resource.url}. En este caso, el valor de la variable de flujo oas.resource.url (entre llaves) se evaluará y se sustituirá en la string de carga útil en el entorno de ejecución. Para obtener más información, consulta Plantillas de mensajes.

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

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

El elemento <OASResource> no tiene atributos ni elementos secundarios.

<Options>

Configura las opciones para la política.

<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>

Especifica si la política debe validar el cuerpo del mensaje en el esquema de cuerpo de la solicitud de la operación en la Especificación de OpenAPI. Configúralo como true para validar el contenido del cuerpo del mensaje. Se configura en false para validar solo que el cuerpo del mensaje exista.

Puedes controlar si la ejecución del flujo continúa siguiendo un error de validación si configuras el atributo continueOnError del elemento <OASValidation> en verdadero.

<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>

Configura el comportamiento de la política si hay parámetros de encabezado, consulta o cookie presentes en la solicitud que no se definen en la Especificación de 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> (elemento secundario de <AllowUnspecifiedParameters>)

Configura el comportamiento de la política si hay parámetros de encabezado presentes en la solicitud que no se definen en la Especificación de OpenAPI.

Para permitir que se especifiquen parámetros de encabezado en la solicitud que no se definen en la Especificación de OpenAPI, configura este parámetro en verdadero. De lo contrario, establece este parámetro en falso para que falle la ejecución de la política.

<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> (elemento secundario de <AllowUnspecifiedParameters>)

Configura el comportamiento de la política si hay parámetros de búsqueda presentes en la solicitud que no se definen en la Especificación de OpenAPI.

Para permitir que los parámetros de búsqueda se especifiquen en la solicitud que no están definidos en la Especificación de OpenAPI, configura este parámetro en verdadero. De lo contrario, establece este parámetro en falso para que falle la ejecución de la política.

<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> (elemento secundario de <AllowUnspecifiedParameters>)

Configura el comportamiento de la política si hay parámetros de cookie presentes en la solicitud que no se definen en la Especificación de OpenAPI.

Para permitir que los parámetros de cookies se especifiquen en la solicitud que no se definen en la Especificación de OpenAPI, configura este parámetro en verdadero. De lo contrario, establece este parámetro en falso para que falle la ejecución de la política.

<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>

Mensaje JSON que se evaluará en relación con los ataques de carga útil JSON. Normalmente, este se configura como request, ya que, por lo general, deberás evaluar las solicitudes entrantes de las apps de cliente. Configúralo como respuesta para evaluar los mensajes de respuesta. Configúralo como mensaje para evaluar automáticamente el mensaje de solicitud cuando la política se adjunta al flujo de solicitudes y el mensaje de respuesta cuando la política está adjunta al flujo de respuesta.

<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>

El elemento <Source> no tiene atributos ni elementos secundarios.

Esquemas

Un esquema XML (.xsd) define cada tipo de política. Como referencia, los esquemas de políticas están disponibles en GitHub.

Códigos de error

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Características de las especificaciones de OpenAPI admitidas

La política OASValidation admite las funciones de especificación de OpenAPI que se resumen en la siguiente tabla, por categoría. También se enumeran las características que no se admiten.

Temas relacionados

• Política de protección contra amenazas de JSON
• Política SOAPMessageValidation