Política OASValidation

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

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.

Componentes Validación de la solicitud
Basepath Valida la basepath definida por el proxy de API, ignora la basepath especificada en la Especificación de OpenAPI.
Ruta Valida que la ruta de solicitud (menos la basepath) coincida con uno de los patrones de ruta definidos en la Especificación de OpenAPI.
Verbo Valida que el verbo se define para la ruta en la Especificación de OpenAPI.
Cuerpo del mensaje de solicitud
  • Valida la existencia del cuerpo del mensaje en la solicitud, si es necesario.
  • De forma opcional, valida el cuerpo del mensaje con el esquema del cuerpo de la solicitud de la operación en la Especificación de OpenAPI. Configura esta opción mediante <ValidateMessageBody>

Nota: La política valida el cuerpo de un mensaje de solicitud respecto de la especificación de OpenAPI solo si el tipo de contenido se configura en application/json. Si el tipo de contenido no se configura como application/json, la validación del cuerpo del mensaje de solicitud se completará correctamente de forma automática (sin validar el contenido en realidad).

Parámetros
  • Verifica que los parámetros obligatorios estén presentes en la solicitud, incluidos parámetros de cookie, ruta, encabezado y consulta.
  • Valida que los valores de parámetros coincidan con los definidos en la Especificación de OpenAPI.
  • De forma opcional, valida si existen parámetros en la solicitud que no están definidos en la Especificación de OpenAPI. Configura esta opción mediante <AllowUnspecifiedParameters>

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

Componentes Validación de respuesta
Ruta Valida que la ruta de solicitud (menos la basepath) coincida con uno de los patrones de ruta definidos en la Especificación de OpenAPI.
Verbo Valida que el verbo se define para la ruta en la Especificación de OpenAPI.
Cuerpo del mensaje de respuesta
  • Valida la existencia del cuerpo del mensaje en la respuesta, si es necesario.
  • Valida que los encabezados de respuesta en la especificación de OpenAPI estén presentes en el mensaje de respuesta y que el valor de los encabezados de respuesta coincida con el esquema.
  • De forma opcional, valida el cuerpo del mensaje con el esquema del cuerpo de respuesta de la operación en la Especificación de OpenAPI. Configura esta opción mediante <ValidateMessageBody>

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.

Valida mensajes de solicitud

En el siguiente ejemplo, la política myoaspolicy valida el cuerpo del mensaje de solicitud en el esquema de cuerpo de mensaje de solicitud de la operación definido en la Especificación de OpenAPI my-spec.json.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.json</OASResource>
   <Options>
      <ValidateMessageBody>true</ValidateMessageBody>
   </Options>
   <Source>request</Source>
</OASValidation>

Si el cuerpo del mensaje no cumple con la especificación de OpenAPI, se muestra un error policies.oasvalidation.Failed.

Valida parámetros

En el siguiente ejemplo, se configura la política para que falle si se especifican parámetros de encabezado, consulta o cookie en la solicitud que no se definen en la especificación de OpenAPI.

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

Valor predeterminado Consulta la pestaña Política predeterminada, a continuación
(obligatorio) Obligatorio
Tipo Objeto complejo
Elemento principal n/a
Elementos secundarios <DisplayName>
<OASResource>
<Source>
<Options>
<Source>

Sintaxis

El elemento <OASValidation> usa la siguiente sintaxis:

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

Política predeterminada

En el siguiente ejemplo, se muestra la configuración predeterminada cuando agregas una política de validación de OAS a tu flujo en la IU de 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>

Este elemento tiene los siguientes atributos que son comunes a todas las políticas:

Atributo Predeterminada (obligatorio) Descripción
name N/A Obligatorio

El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres.

De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.
continueOnError falso Opcional Si la estableces como "false", muestra un error cuando falla una política. Este es el comportamiento previsto para la mayoría de las políticas. Si su valor es "true", la ejecución del flujo continuará incluso después de que falle la política.
enabled true Opcional Si estableces la política como "true", la aplicarás. Si la estableces como "false", se desactivará la política. La política no se aplicará, incluso si permanece conectada a un flujo.
async   falso Funciones obsoletas Este atributo dejó de estar disponible.

Referencia del elemento secundario

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

<DisplayName>

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

El elemento <DisplayName> es común a todas las políticas.

Valor predeterminado N/A
¿Es obligatorio? Opcional. Si omites <DisplayName>, se usa el valor del atributo name de la política.
Tipo String
Elemento principal <PolicyElement>
Elementos secundarios Ninguna

El elemento <DisplayName> usa la siguiente sintaxis:

Sintaxis

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

Ejemplo

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

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

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

Valor predeterminado None
(obligatorio) Obligatorio
Tipo String
Elemento principal <OASValidation>
Elementos secundarios Ninguno

Sintaxis

El elemento <OASResource> usa la siguiente sintaxis:

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

Ejemplo

En el siguiente ejemplo, se hace referencia a la especificación my-spec.yaml que se almacena en /apiproxy/resources/oas en el paquete de proxy de API:

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

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo Tipo complejo
Elemento principal <OASValidation>
Elementos secundarios <ValidateMessageBody>
<AllowUnspecifiedParameters>

Sintaxis

El elemento <Options> usa la siguiente sintaxis:

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

Ejemplo

En el siguiente ejemplo, se configuran las opciones para la política. Cada una de las opciones se describe con más detalle a continuación.

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

Valor predeterminado falso
¿Es obligatorio? Opcional
Tipo Booleano
Elemento principal <Options>
Elementos secundarios Ninguno

Sintaxis

El elemento <ValidateMessageBody> usa la siguiente sintaxis:

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

Ejemplo

En el siguiente ejemplo, se habilita la validación del contenido del cuerpo del mensaje:

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

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo Tipo complejo
Elemento principal <Options>
Elementos secundarios <Header>
<Query>
<Cookie>

Sintaxis

El elemento <AllowUnspecifiedParameters> usa la siguiente sintaxis:

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

Ejemplo

En el siguiente ejemplo, se configura la política para que falle si se especifican parámetros de encabezado, consulta o cookie en la solicitud que no se definen en la especificación de OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

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.

Valor predeterminado true
(obligatorio) Booleano
Tipo Tipo complejo
Elemento principal <AllowUnspecifiedParameters>
Elementos secundarios Ninguno

Sintaxis

El elemento <Header> usa la siguiente sintaxis:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Ejemplo

En el siguiente ejemplo, se configura la política para que falle si se especifica un parámetro de encabezado en la solicitud que no se define en la Especificación de OpenAPI.

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

Valor predeterminado true
(obligatorio) Booleano
Tipo Tipo complejo
Elemento principal <AllowUnspecifiedParameters>
Elementos secundarios Ninguno

Sintaxis

El elemento <Query> usa la siguiente sintaxis:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Ejemplo

En el siguiente ejemplo, se configura la política para que falle si se especifica un parámetro de búsqueda en la solicitud que no está definido en la Especificación de OpenAPI.

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

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.

Valor predeterminado true
(obligatorio) Booleano
Tipo Tipo complejo
Elemento principal <AllowUnspecifiedParameters>
Elementos secundarios Ninguno

Sintaxis

El elemento <Cookie> usa la siguiente sintaxis:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Ejemplo

En el siguiente ejemplo, se configura la política para que falle si se especifica un parámetro de búsqueda en la solicitud que no está definido en la Especificación de OpenAPI.

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

Valor predeterminado solicitud
(obligatorio) Opcional
Tipo String
Elemento principal <Source>
Elementos secundarios Ninguno

Sintaxis

El elemento <Source> usa la siguiente sintaxis:

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

Ejemplo

En el siguiente ejemplo, se evalúa 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 se adjunta al flujo de respuesta:

<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

En esta sección, se describen los códigos y mensajes de error que se muestran y las variables de fallas que establece Edge cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo solucionar fallas.

Errores de entorno de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Código de falla Estado de HTTP Causa
steps.oasvalidation.Failed 500 El cuerpo del mensaje de solicitud no se puede validar en la especificación de OpenAPI proporcionada.
steps.oasvalidation.SourceMessageNotAvailable 500

La variable especificada en el elemento <Source> de la política está fuera del alcance o no se puede resolver.
steps.oasvalidation.NotMessageVariable 500

El elemento <Source> se establece en una variable que no es del tipo mensaje.

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

Nombre del error Causa
ResourceDoesNotExist La especificación de OpenAPI a la que se hace referencia en el elemento <OASResource> no existe.
ResourceCompileFailed La especificación de OpenAPI que se incluye en la implementación contiene errores que evitan que se compile. Por lo general, esto indica que la especificación no es una especificación 3.0 de OpenAPI con el formato correcto.
BadResourceURL No se puede procesar la especificación de OpenAPI a la que se hace referencia en el elemento <OASResource>. Esto puede ocurrir si el archivo no es un archivo JSON o YAML, o si la URL del archivo no se especificó de forma correcta.

Variables con fallas

Estas variables se configuran cuando esta política activa un error en el entorno de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Variables Donde Ejemplo
fault.name="fault_name" fault_name es el nombre de la falla, como se indica en la tabla de Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla. fault.name Matches "ResourceDoesNotExist"
oasvalidation.policy_name.failed policy_name es el nombre especificado por el usuario de la política que generó la falla. oasvalidation.myoaspolicy.failed = true

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.

Categoría Compatible No compatible
Formatos de tipos de datos boolean
date
date-time
double
email
float
int32/int64
ipv4/ipv6
md5
sha1/sha256/sha512
string
uri
uri-template
uuid
 binary
byte
password
Objeto discriminante mapping
propertyName 		N/A
Objeto de tipo de medio schema encoding
example
examples
Objeto de operaciones parameters
requestBody
responses
security (partial support) 		callbacks
deprecated
servers
Objeto de parámetros allowEmptyValue
in (query, header, path)
required
responses
schema
style (deepObject, form, formmatrix, label, pipeDelimited, simple, spaceDelimited)

Nota: deepObject solo admite parámetros de string. No se admiten arreglos ni objetos anidados.		 allowReserved
deprecated
example
examples
content
Objeto de rutas delete
get
head
options
parameters
patch
post
put
trace
variables 		servidores
Objeto de cuerpo de solicitud application/json
application/hal+json
application/x-www-form-urlencoded (objeto encoding no admitido)
content
required		 application/xml
multipart/form-data
text/plain
text/xml
Objeto de respuesta application/json
application/hal+json
application/x-www-form-urlencoded (objetoencoding no admitido)
content
headers 		application/xml
links
text/plain
text/xml
Objeto de respuestas predeterminado
Código de estado HTTP		 N/A
Objeto de esquema $ref
additionalProperties (solo variante de marca booleana)
allOf (se ignora si additionalProperties es 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
Objeto de esquema de seguridad in (header, query) (se ignora si type es http)
name
type (apiKey, http) 		bearerFormat
flows
openIdConnectUrl
scheme
Objeto del servidor url
variables 		Definiciones de varios servidores

Temas relacionados