Validación de código de estado

  • Artículo

SE APLICA A: todos los niveles de API Management

La directiva validate-status-code valida los códigos de estado HTTP en las respuestas con el esquema de la API. Esta directiva se puede usar para evitar que se escapen errores de back-end, que pueden contener seguimientos de la pila.

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-status-code unspecified-status-code-action="ignore | prevent | detect" errors-variable-name="variable name">
    <status-code code="HTTP status code number" action="ignore | prevent | detect" />
</validate-status-code>

Atributos

Atributo Descripción Necesario Valor predeterminado
unspecified-status-code-action Acción que se va a realizar para los códigos de estado HTTP en las respuestas que no se especifican 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
status-code Agregue uno o varios elementos para códigos de estado HTTP para invalidar la acción de validación predeterminada para los códigos de estado en las respuestas. No

Atributos status-code

Atributo Descripción Necesario Valor predeterminado
código Código de estado HTTP para el que se va a invalidar la acción de validación. Sí N/D
action Acción que se va a realizar para el código de estado coincidente, que no se especifica en el esquema de la API. Si el código de estado se especifica en el esquema de la API, esta invalidación no surte efecto. Sí N/D

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

<validate-status-code unspecified-status-code-action="prevent" errors-variable-name="responseStatusCodeValidation" />

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: