Política OASValidation

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

ícono de política

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.

Esta es una política estándar y se puede implementar en cualquier tipo de entorno. No todos los usuarios necesitan conocer los tipos de políticas y el entorno. Para obtener información sobre los tipos de políticas y la disponibilidad con cada tipo de entorno, consulta Tipos de políticas.

¿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 Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle. También consulta:
enabled true Opcional Configúralo como true para aplicar la política. Configúralo como false para desactivar la política. La política no se aplicará, incluso si permanece conectada a un flujo.
async   falso Obsoleta 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 None

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 None

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 None

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 None

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 None

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 None

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 de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee 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 400 El cuerpo del mensaje de solicitud no se puede validar en la especificación de OpenAPI proporcionada.
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.NonMessageVariable 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.

Variable Descripción Ejemplo
fault.category La categoría de la falla. Cuando la política rechaza una solicitud, siempre se aplicará Step. fault.category = "Step"
fault.name 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"
fault.reason El motivo de la falla. Es una string legible que explica el motivo de la falla. OASValidation OAS-1 with resource "oas://my-spec1.yaml": failed with reason: "[ERROR - POST operation not allowed on path '/persons/13'.: []]"
fault.subcategory La subcategoría de la falla. Cuando la política rechace una solicitud, siempre se conservará OASValidationFailure. fault.subcategory = "OASValidationFailure"
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