Política OASValidation

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

Consulta la documentación de Apigee Edge.

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.

Nota: Solo puedes almacenar la Especificación de OpenAPI con la revisión del proxy de API. Consulta Dónde se almacenan los 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	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: Las reglas de fallas se activan SOLAMENTE en un estado de error (sobre el continueOnError) Controla fallas dentro del flujo actual
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.

Nota: Si la política OASValidation especifica un <OASResource> con requisitos de seguridad establecidos a nivel global, no se aplican los requisitos de seguridad. Para garantizar la aplicación, todos los requisitos de seguridad se deben establecer a nivel de operación en la especificación de OpenAPI que se pasa en el elemento <OASResource> de esta política. Para obtener más información, consulta Problemas conocidos de Apigee

.

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

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

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>

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

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>

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

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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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.

Fault code	HTTP status	Cause
steps.oasvalidation.Failed	400	The Request message body cannot be validated against the provided OpenAPI Specification.
steps.oasvalidation.Failed	500	The Response message body cannot be validated against the provided OpenAPI Specification.
steps.oasvalidation.SourceMessageNotAvailable	500	Variable specified in the <Source> element of the policy is either out of scope or cannot be resolved.
steps.oasvalidation.NonMessageVariable	500	<Source> element is set to a variable that is not of type message.

Deployment errors

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

Error name	Cause
ResourceDoesNotExist	OpenAPI Specification referenced in the <OASResource> element does not exist.
ResourceCompileFailed	OpenAPI Specification that is included in the deployment contains errors that prevent it from being compiled. This generally indicates that the specification is not a well-formed OpenAPI Specification 3.0.
BadResourceURL	OpenAPI Specification referenced in the <OASResource> element cannot be processed. This can occur if the file is not a JSON or YAML file or the file URL is not specified correctly.

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.

Variable	Description	Example
fault.category	The category of the fault. When the policy rejects a request, this will always hold Step.	fault.category = "Step"
fault.name	The name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "ResourceDoesNotExist"
fault.reason	The reason for the fault. It is a human-readable string explaining the reason for the fault.	OASValidation OAS-1 with resource "oas://my-spec1.yaml": failed with reason: "[ERROR - POST operation not allowed on path '/persons/13'.: []]"
fault.subcategory	The subcategory of the fault. When the policy rejects a request, this will always hold OASValidationFailure.	fault.subcategory = "OASValidationFailure"
OASValidation.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	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.

Nota: La política OASValidation rechazará las especificaciones de OpenAPI que usen funciones no admitidas. En este caso, la política no pasará la validación de las funciones no compatibles y la implementación del proxy de API fallará.

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

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