Validación de encabezados
SE APLICA A: todos los niveles de API Management
La directiva validate-headers valida los encabezados de respuesta con el esquema de la API.
Importante
Si importó una API mediante una versión de API de administración anterior a 2021-01-01-preview, es posible que la directiva validate-headers no funcione. Es posible que tenga que volver a importar la API con la versión 2021-01-01-preview de la administración de API o posterior.
Nota
El tamaño máximo del esquema de API que puede usar esta directiva de validación es de 4 MB. Si el esquema supera este límite, las directivas de validación devolverán errores en tiempo de ejecución. Para aumentarlo, póngase en contacto con el servicio de soporte técnico.
Nota
Establezca los elementos de la directiva y los elementos secundarios en el orden proporcionado en la instrucción de directiva. Para que pueda configurar esta directiva, el portal proporciona un editor guiado basado en formularios. Obtenga más información sobre el establecimiento o modificación de directivas de API Management.
Instrucción de la directiva
<validate-headers specified-header-action="ignore | prevent | detect" unspecified-header-action="ignore | prevent | detect" errors-variable-name="variable name">
<header name="header name" action="ignore | prevent | detect" />
</validate-headers>
Atributos
| Atributo | Descripción | Necesario | Valor predeterminado |
|---|---|---|---|
| specified-header-action | Acción que se va a realizar para los encabezados de respuesta especificados en el esquema de la API. Se permiten expresiones de directiva. | Sí | N/D |
| unspecified-header-action | Acción que se va a realizar para los encabezados de respuesta que no están especificados en el esquema de la API. Se permiten expresiones de directiva. | Sí | N/D |
| errors-variable-name | Nombre de la variable de context.Variables en la que se registrarán los errores de validación. No se permiten expresiones de directiva. |
No | N/D |
Elementos
| Nombre | Descripción | Obligatorio |
|---|---|---|
| header | Agregue uno o más elementos para los encabezados con nombre para invalidar las acciones de validación predeterminadas para los encabezados en las respuestas. | No |
Acciones
Las directivas de validación de contenido incluyen uno o más atributos que especifican una acción, que API Management realiza al validar una entidad de una solicitud o respuesta de API con el esquema de API.
Se puede especificar una acción para los elementos que se representan en el esquema de la API y, en función de la directiva, para los elementos que no están representados en el esquema de la API.
Una acción especificada en un elemento secundario de la directiva invalida la acción especificada para su elemento primario.
Acciones disponibles:
| Acción | Descripción |
|---|---|
| ignore | Omitir validación. |
| prevent | Bloquear el procesamiento de la solicitud o la respuesta, registrar el error de validación detallado y devolver un error. El procesamiento se interrumpe cuando se detecta el primer conjunto de errores. |
| detectar | Registrar los errores de validación, sin interrumpir el procesamiento de la solicitud o respuesta. |
Uso
- Secciones de directiva: saliente, en error
- Ámbitos de la directiva: global, área de trabajo, producto, API, operación
- Puertas de enlace: clásica, v2, consumo, autohospedada y área de trabajo
Notas de uso
- Esta directiva solo se puede usar una vez en una sección de directiva.
Registros
Los detalles sobre los errores de validación generados durante la ejecución de la directiva se registran en la variable context.Variables especificada en el atributo errors-variable-name del elemento raíz de la directiva. Cuando se configura en una acción prevent, un error de validación bloquea el procesamiento adicional de la solicitud o la respuesta y también se propaga a la propiedad context.LastError.
Para investigar los errores, utilice una directiva de seguimiento para registrar los errores de las variables de contexto en Application Insights.
Implicaciones de rendimiento
Agregar una directiva de validación puede afectar al rendimiento de la API. Se aplican los siguientes principios generales:
- Cuanto mayor sea el tamaño del esquema de la API, menor será el rendimiento.
- Cuanto mayor sea la carga en una solicitud o respuesta, menor será el rendimiento.
- El tamaño del esquema de la API tiene un mayor impacto en el rendimiento que el tamaño de la carga.
- La validación con un esquema de API de varios megabytes de tamaño puede generar tiempos de expiración de la solicitud o respuesta en determinadas condiciones. El efecto es más pronunciado en los niveles de Consumo y Desarrollador del servicio.
Se recomienda realizar pruebas de carga con las cargas de trabajo de producción esperadas para evaluar el impacto de las directivas de validación en el rendimiento de la API.
Ejemplo
<validate-headers specified-header-action="ignore" unspecified-header-action="prevent" errors-variable-name="responseHeadersValidation" />
Errores de validación
API Management genera errores de validación de contenido en el formato siguiente:
{
"Name": string,
"Type": string,
"ValidationRule": string,
"Details": string,
"Action": string
}
En la tabla siguiente se enumeran todos los errores posibles de las directivas de validación.
- Detalles: se pueden usar para investigar los errores. No debe compartirse públicamente.
- Respuesta pública: error devuelto al cliente. No filtra los detalles de la implementación.
Cuando una directiva de validación especifica la acción prevent y genera un error, la respuesta de la administración de API incluye un código de estado HTTP: 400 cuando se aplica la directiva en la sección entrante y 502 cuando la directiva se aplica en la sección saliente.
| Nombre | Tipo | Regla de validación | Detalles | Respuesta pública | Acción |
|---|---|---|---|---|---|
| validate-content | |||||
| RequestBody | SizeLimit | El cuerpo de la solicitud es de {size} bytes y supera el límite configurado de {maxSize} bytes. | El cuerpo de la solicitud es de {size} bytes y supera el límite de {maxSize} bytes. | detect/prevent | |
| ResponseBody | SizeLimit | El cuerpo de la respuesta es de {size} bytes y supera el límite configurado de {maxSize} bytes. | No se pudo procesar la solicitud debido a un error interno. Póngase en contacto con el propietario de la API. | detect/prevent | |
| {messageContentType} | RequestBody | Sin especificar | No se permite el tipo de contenido {messageContentType} sin especificar. | No se permite el tipo de contenido {messageContentType} sin especificar. | detect/prevent |
| {messageContentType} | ResponseBody | Sin especificar | No se permite el tipo de contenido {messageContentType} sin especificar. | No se pudo procesar la solicitud debido a un error interno. Póngase en contacto con el propietario de la API. | detect/prevent |
| ApiSchema | El esquema de la API no existe o no se pudo resolver. | No se pudo procesar la solicitud debido a un error interno. Póngase en contacto con el propietario de la API. | detect/prevent | ||
| ApiSchema | El esquema de la API no especifica definiciones. | No se pudo procesar la solicitud debido a un error interno. Póngase en contacto con el propietario de la API. | detect/prevent | ||
| {messageContentType} | RequestBody/ResponseBody | MissingDefinition | El esquema de la API no contiene la definición {definitionName}, que está asociada con el tipo de contenido {messageContentType}. | No se pudo procesar la solicitud debido a un error interno. Póngase en contacto con el propietario de la API. | detect/prevent |
| {messageContentType} | RequestBody | IncorrectMessage | El cuerpo de la solicitud no se ajusta a la definición {definitionName}, que está asociada con el tipo de contenido {messageContentType}. Línea {valError.Message}: {valError.LineNumber}, posición: {valError.LinePosition} |
El cuerpo de la solicitud no se ajusta a la definición {definitionName}, que está asociada con el tipo de contenido {messageContentType}. Línea {valError.Message}: {valError.LineNumber}, posición: {valError.LinePosition} |
detect/prevent |
| {messageContentType} | ResponseBody | IncorrectMessage | El cuerpo de la respuesta no se ajusta a la definición {definitionName}, que está asociada con el tipo de contenido {messageContentType}. Línea {valError.Message}: {valError.LineNumber}, posición: {valError.LinePosition} |
No se pudo procesar la solicitud debido a un error interno. Póngase en contacto con el propietario de la API. | detect/prevent |
| RequestBody | ValidationException | No se puede validar el cuerpo de la solicitud para el tipo de contenido {messageContentType}. {exception details} |
No se pudo procesar la solicitud debido a un error interno. Póngase en contacto con el propietario de la API. | detect/prevent | |
| ResponseBody | ValidationException | No se puede validar el cuerpo de la respuesta para el tipo de contenido {messageContentType}. {exception details} |
No se pudo procesar la solicitud debido a un error interno. Póngase en contacto con el propietario de la API. | detect/prevent | |
| validate-parameters/validate-headers | |||||
| {paramName}/{headerName} | QueryParameter/PathParameter/RequestHeader | Sin especificar | No se permite {path parameter/query parameter/header} {paramName} sin especificar. | No se permite {path parameter/query parameter/header} {paramName} sin especificar. | detect/prevent |
| {headerName} | ResponseHeader | Sin especificar | No se permite el encabezado {headerName} sin especificar. | No se pudo procesar la solicitud debido a un error interno. Póngase en contacto con el propietario de la API. | detect/prevent |
| ApiSchema | El esquema de la API no existe o no se pudo resolver. | No se pudo procesar la solicitud debido a un error interno. Póngase en contacto con el propietario de la API. | detect/prevent | ||
| ApiSchema | El esquema de la API no especifica definiciones. | No se pudo procesar la solicitud debido a un error interno. Póngase en contacto con el propietario de la API. | detect/prevent | ||
| {paramName} | QueryParameter/PathParameter/RequestHeader/ResponseHeader | MissingDefinition | El esquema de la API no contiene la definición {definitionName}, que está asociada con {query parameter/path parameter/header} {paramName}. | No se pudo procesar la solicitud debido a un error interno. Póngase en contacto con el propietario de la API. | detect/prevent |
| {paramName} | QueryParameter/PathParameter/RequestHeader | IncorrectMessage | La solicitud no puede contener varios valores para el {query parameter/path parameter/header} {paramName}. | La solicitud no puede contener varios valores para el {query parameter/path parameter/header} {paramName}. | detect/prevent |
| {headerName} | ResponseHeader | IncorrectMessage | La respuesta no puede contener varios valores para el encabezado {headerName}. | No se pudo procesar la solicitud debido a un error interno. Póngase en contacto con el propietario de la API. | detect/prevent |
| {paramName} | QueryParameter/PathParameter/RequestHeader | IncorrectMessage | El valor de {query parameter/path parameter/header} {paramName} no se ajusta a la definición. Línea {valError.Message}: {valError.LineNumber}, posición: {valError.LinePosition} |
El valor de {query parameter/path parameter/header} {paramName} no se ajusta a la definición. Línea {valError.Message}: {valError.LineNumber}, posición: {valError.LinePosition} |
detect/prevent |
| {headerName} | ResponseHeader | IncorrectMessage | El valor del encabezado {headerName} no se ajusta a la definición. Línea {valError.Message}: {valError.LineNumber}, posición: {valError.LinePosition} |
No se pudo procesar la solicitud debido a un error interno. Póngase en contacto con el propietario de la API. | detect/prevent |
| {paramName} | QueryParameter/PathParameter/RequestHeader | IncorrectMessage | No se puede analizar el valor de {query parameter/path parameter/header} {paramName} según la definición. {ex.Message} |
No se puede analizar el valor de {query parameter/path parameter/header} {paramName} según la definición. {ex.Message} |
detect/prevent |
| {headerName} | ResponseHeader | IncorrectMessage | No se pudo analizar el valor del encabezado {headerName} según la definición. | No se pudo procesar la solicitud debido a un error interno. Póngase en contacto con el propietario de la API. | detect/prevent |
| {paramName} | QueryParameter/PathParameter/RequestHeader | ValidationError | {Query parameter/Path parameter/Header} {paramName} no se puede validar. {exception details} |
No se pudo procesar la solicitud debido a un error interno. Póngase en contacto con el propietario de la API. | detect/prevent |
| {headerName} | ResponseHeader | ValidationError | No se puede validar el encabezado {headerName}. {exception details} |
No se pudo procesar la solicitud debido a un error interno. Póngase en contacto con el propietario de la API. | detect/prevent |
| validate-status-code | |||||
| {status-code} | StatusCode | Sin especificar | No se permite el código de estado de respuesta {status-code}. | No se pudo procesar la solicitud debido a un error interno. Póngase en contacto con el propietario de la API. | detect/prevent |
En la tabla siguiente se enumeran todos los valores del motivo posible de un error de validación junto con los posibles valores del mensaje:
| Motivo | Mensaje |
|---|---|
| Solicitud incorrecta | {Details} para la variable de contexto, {Public response} para el cliente |
| Respuesta no permitida | {Details} para la variable de contexto, {Public response} para el cliente |
Directivas relacionadas
Contenido relacionado
Para más información sobre el trabajo con directivas, vea:
- Tutorial: Transformación y protección de una API
- Referencia de directivas para una lista completa de instrucciones de directivas y su configuración
- Expresiones de directiva
- Establecimiento o edición de directivas
- Reutilización de configuraciones de directivas
- Repositorio de fragmentos de código de directiva
- Kit de herramientas de directivas de Azure API Management
- Creación de directivas mediante Microsoft Copilot en Azure