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.
¿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 |
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 |
Parámetros |
|
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 |
|
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 De forma opcional, usa el elemento |
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>
<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>
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 |
steps.oasvalidation.NonMessageVariable |
500 |
El elemento |
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 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 (objeto encoding 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 |