Partekatu honen bidez:

Validar contenido

  • Artikulua

SE APLICA A: todos los niveles de API Management

La directiva validate-content valida el tamaño o el contenido de un cuerpo de solicitud o respuesta con uno o varios esquemas admitidos.

En la tabla siguiente se muestran los formatos de esquema y los tipos de contenido de solicitud o respuesta que admite la directiva. Los valores de tipo de contenido no distinguen mayúsculas y minúsculas.

Formato Tipos de contenido
JSON Ejemplos: application/json
application/hal+json
XML Ejemplo: application/xml
SOAP Valores permitidos: application/soap+xml para las API de SOAP 1.2
text/xml para las API de SOAP 1.1

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.

Qué contenido se valida

La directiva valida el siguiente contenido en la solicitud o respuesta con el esquema:

  • Presencia de todas las propiedades obligatorias.
  • La presencia o ausencia de propiedades adicionales, si el esquema tiene el campo additionalProperties establecido. Se puede invalidar con el atributo allow-additional-properties.
  • Tipos de todas las propiedades. Por ejemplo, si un esquema especifica una propiedad como un entero, la solicitud (o respuesta) debe incluir un entero y no otro tipo, como una cadena.
  • Formato de las propiedades, si se especifica en el esquema; por ejemplo, expresiones regulares (si se especifica la palabra clave pattern), minimum para enteros, etc.

Sugerencia

Para obtener ejemplos de restricciones con patrones de expresiones regulares que se pueden usar en esquemas, consulte el repositorio Expresiones regulares de validación de OWASP.

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-content unspecified-content-type-action="ignore | prevent | detect" max-size="size in bytes" size-exceeded-action="ignore | prevent | detect" errors-variable-name="variable name">
    <content-type-map any-content-type-value="content type string" missing-content-type-value="content type string">
        <type from | when="content type string" to="content type string" />
    </content-type-map>
    <content type="content type string" validate-as="json | xml | soap" schema-id="schema id" schema-ref="#/local/reference/path" action="ignore | prevent | detect" allow-additional-properties="true | false" case-insensitive-property-names="true | false"/>
</validate-content>

Atributos

Atributo Descripción Necesario Valor predeterminado
unspecified-content-type-action Acción que se realiza para las solicitudes o respuestas con un tipo de contenido que no se especifica en el esquema de la API. Se permiten expresiones de directiva. Sí N/D
max-size Longitud máxima del cuerpo de la solicitud o respuesta en bytes, comprobada con el encabezado Content-Length. Si el cuerpo de la solicitud o de la respuesta está comprimido, este valor es la longitud descomprimida. Valor máximo permitido: 4 MB. Se permiten expresiones de directiva. Sí N/D
size-exceeded-action Acción que se realiza para las solicitudes o respuestas cuyo cuerpo supera el tamaño especificado en max-size. 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
content-type-map Agregue este elemento para asignar el tipo de contenido de la solicitud o respuesta entrante a otro tipo de contenido que se usa para desencadenar la validación. No
contenido Agregue uno o varios de estos elementos para validar el tipo de contenido en la solicitud o la respuesta, o el tipo de contenido asignado, y realizar la acción especificada. No

atributos content-type-map

Atributo Descripción Necesario Valor predeterminado
any-content-type-value Tipo de contenido utilizado para la validación del cuerpo de una solicitud o respuesta, independientemente del tipo de contenido entrante. No se permiten expresiones de directiva. No N/D
missing-content-type-value Tipo de contenido usado para la validación del cuerpo de una solicitud o respuesta, cuando falta o está vacío el tipo de contenido entrante. No se permiten expresiones de directiva. No N/D

content-type-map-elements

Nombre Descripción Obligatorio
type Agregue uno o varios de estos elementos para asignar un tipo de contenido entrante a un tipo de contenido usado para la validación del cuerpo de una solicitud o respuesta. Use from para especificar un tipo de contenido entrante conocido o use when con una expresión de directiva para especificar cualquier tipo de contenido entrante que coincida con una condición. Invalida la asignación en any-content-type-value y missing-content-type-value, si se especifica. No

atributos content

Atributo Descripción Necesario Valor predeterminado
type Tipo de contenido para el que se ejecutará la validación del cuerpo, comprobado con el encabezado del tipo de contenido o con el valor asignado en content-type-mapping, si se especifica. Si está vacío, se aplica a todos los tipos de contenido especificados en el esquema de la API.

Para validar las solicitudes y respuestas SOAP (atributo validate-as establecido en "soap"), establezca type en application/soap+xml para las API de SOAP 1.2 o text/xml para las API de SOAP 1.1.		 No N/D
validate-as Motor de validación que se va a usar para la validación del cuerpo de una solicitud o respuesta con un type coincidente. Valores admitidos: "json", "xml", "soap".

Cuando se especifica "soap", el XML de la solicitud o respuesta se extrae de la envoltura SOAP y se valida con un esquema XML.		 Sí N/D
schema-id Nombre de un esquema existente que se agregó a la instancia de API Management para la validación de contenido. Si no se especifica, se usa el esquema predeterminado de la definición de API. No N/D
schema-ref Para un esquema JSON especificado en schema-id, referencia opcional a una ruta de acceso de referencia local válida en el documento JSON. Ejemplo: #/components/schemas/address. El atributo debe devolver un objeto JSON que API Management controla como un esquema JSON válido.

Para un esquema XML, schema-ref no se admite, y cualquier elemento de esquema de nivel superior se puede usar como raíz de la carga de solicitud o respuesta XML. La validación comprueba que todos los elementos que comienzan desde la raíz de carga de solicitud o respuesta XML se adhieren al esquema XML proporcionado.		 No N/D
allow-additional-properties booleano. Para un esquema JSON, especifica si se debe implementar una invalidación en tiempo de ejecución del valor additionalProperties configurado en el esquema:
- true: permite propiedades adicionales en el cuerpo de la solicitud o respuesta, incluso si el campo additionalProperties del esquema JSON está configurado para no permitir propiedades adicionales.
- false: no permite propiedades adicionales en el cuerpo de la solicitud o respuesta, incluso si el campo additionalProperties del esquema JSON está configurado para permitir propiedades adicionales.

Si no se especifica el atributo, la directiva valida propiedades adicionales según la configuración del campo additionalProperties en el esquema.		 No N/D
nombres de propiedad que no distinguen mayúsculas de minúsculas booleano. Para un esquema JSON, especifica si se van a comparar los nombres de propiedad de los objetos JSON sin tener en cuenta el caso.
- true: compara los nombres de propiedad sin distinción entre mayúsculas y minúsculas.
- false: compara los nombres de propiedad distingue mayúsculas de minúsculas.		 No false

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

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.

Esquemas para la validación de contenido

De forma predeterminada, la validación del contenido de solicitud o respuesta usa esquemas JSON o XML de la definición de la API. Estos esquemas pueden especificarse manualmente o generarse automáticamente al importar una API desde una especificación OpenAPI o WSDL en API Management.

Con la directiva validate-content, opcionalmente puede validar con uno o varios esquemas JSON o XML que haya agregado a la instancia de API Management y que no formen parte de la definición de API. Un esquema que agregue a API Management se puede reutilizar en muchas API.

Para agregar un esquema a la instancia de API Management mediante Azure Portal:

  1. En el portal, vaya a la instancia de API Management.

  2. En la sección API del menú de la izquierda, seleccione Esquemas>+ Agregar.

  3. En la ventana Crear esquema, haga lo siguiente:

    1. Escriba un nombre (identificador) para el esquema.
    2. En Tipo de esquema, seleccione JSON o XML.
    3. Escriba una Descripción.
    4. En Crear método, realice una de las acciones siguientes:
      • Seleccione Crear nuevo y escriba o pegue el esquema.
      • Seleccione Importar desde archivo o Importar desde dirección URL y escriba una ubicación de esquema.

        Nota:

        Para importar un esquema desde la dirección URL, el esquema debe ser accesible a través de Internet desde el explorador.

    5. Seleccione Guardar.

    Crear esquema

API Management agrega el recurso de esquema en el URI relativo /schemas/<schemaId> y el esquema aparece en la lista de la página Esquemas. Seleccione un esquema para ver sus propiedades o editar en un editor de esquemas.

Nota:

Un esquema puede hacer referencia cruzada a otro esquema que se agrega a la instancia de API Management. Por ejemplo, incluya un esquema XML agregado a API Management mediante un elemento similar al siguiente:

<xs:include schemaLocation="/schemas/myschema" />

Sugerencia

Las herramientas de código abierto para resolver referencias de esquema WSDL y XSD y para importar por lotes esquemas generados para API Management están disponibles en GitHub.

Ejemplos

Validación de esquema JSON

En el ejemplo siguiente, API Management interpreta las solicitudes con un encabezado de tipo de contenido vacío o las solicitudes con un encabezado de tipo de contenido application/hal+json como solicitudes con el tipo de contenido application/json. A continuación, API Management realiza la validación en el modo de detección con un esquema definido para el tipo de contenido application/json en la definición de la API. Los mensajes con cargas superiores a 100 KB están bloqueados. Las solicitudes que contienen propiedades adicionales se bloquean, incluso si el campo additionalProperties del esquema está configurado para permitir estas últimas.

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map missing-content-type-value="application/json">
        <type from="application/hal+json" to="application/json" />
    </content-type-map>
    <content type="application/json" validate-as="json" action="detect" allow-additional-properties="false" />
</validate-content>

Validación de esquema SOAP

En el ejemplo siguiente, API Management interpreta cualquier solicitud como una solicitud con el tipo de contenido application/soap+xml (el tipo de contenido que usan las API SOAP 1.2), independientemente del tipo de contenido entrante. La solicitud podría llegar con un encabezado de tipo de contenido vacío, un encabezado de tipo de contenido de text/xml (utilizado por las API SOAP 1.1) u otro encabezado de tipo de contenido. A continuación, API Management extrae la carga XML de la envoltura SOAP y realiza la validación en modo de prevención en el esquema denominado "myschema". Los mensajes con cargas superiores a 100 KB están bloqueados.

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map any-content-type-value="application/soap+xml" />
    <content type="application/soap+xml" validate-as="soap" schema-id="myschema" action="prevent" /> 
</validate-content>

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: