Validación de parámetros

  • Artículo

SE APLICA A: todos los niveles de API Management

La directiva validate-parameters valida los parámetros del encabezado, la consulta o la ruta de acceso en las solicitudes 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-parameters no funcione. Es posible que tenga que volver a importar la API con la versión de la administración de API 2021-01-01-preview 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-parameters specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect" errors-variable-name="variable name"> 
    <headers specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </headers>
    <query specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </query>
    <path specified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </path>
</validate-parameters>

Atributos

Atributo Descripción Necesario Valor predeterminado
specified-parameter-action Acción que se va a realizar para los parámetros de solicitud especificados en el esquema de la API.

Cuando se proporciona en un elemento headers,query o path, el valor invalida el valor de specified-parameter-action del elemento validate-parameters. Se permiten expresiones de directiva.		 Sí N/D
unspecified-parameter-action Acción que se va a realizar para los parámetros de solicitud que no se han especificado en el esquema de la API.

Cuando se proporciona en un elemento headers o query, el valor invalida el valor de unspecified-parameter-action del elemento validate-parameters. 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
headers Agregue este elemento y uno o varios subelementos parameter para invalidar las acciones de validación predeterminadas para determinados parámetros con nombre en las solicitudes. Si el parámetro se especifica en el esquema de la API, este valor invalida la configuración de specified-parameter-action de nivel superior. Si el parámetro no se especifica en el esquema de la API, este valor invalida la configuración de unspecified-parameter-action de nivel superior. No
Query Agregue este elemento y uno o varios subelementos parameter para invalidar las acciones de validación predeterminadas para determinados parámetros de consulta con nombre en las solicitudes. Si el parámetro se especifica en el esquema de la API, este valor invalida la configuración de specified-parameter-action de nivel superior. Si el parámetro no se especifica en el esquema de la API, este valor invalida la configuración de unspecified-parameter-action de nivel superior. No
path Agregue este elemento y uno o varios subelementos parameter para invalidar las acciones de validación predeterminadas para determinados parámetros de ruta de URL con nombre en las solicitudes. Si el parámetro se especifica en el esquema de la API, este valor invalida la configuración de specified-parameter-action de nivel superior. Si el parámetro no se especifica en el esquema de la API, este valor invalida la configuración de unspecified-parameter-action de nivel superior. 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

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

En este ejemplo, todos los parámetros de consulta y ruta de acceso se validan en el modo de prevención y los encabezados en el modo de detección. La validación se invalida para varios parámetros de encabezado:

<validate-parameters specified-parameter-action="prevent" unspecified-parameter-action="prevent" errors-variable-name="requestParametersValidation"> 
    <headers specified-parameter-action="detect" unspecified-parameter-action="detect">
        <parameter name="Authorization" action="prevent" />
        <parameter name="User-Agent" action="ignore" />
        <parameter name="Host" action="ignore" />
        <parameter name="Referrer" action="ignore" />
    </headers>   
</validate-parameters>

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

Contenido relacionado

Para más información sobre el trabajo con directivas, vea: