Compartir vía

Validación de la solicitud de GraphQL

  • Artículo

SE APLICA A: todos los niveles de API Management

La directiva validate-graphql-request valida la solicitud GraphQL y autoriza el acceso a rutas de la consulta específicas en una Graph API. Una consulta no válida es un "error de solicitud". La autorización solo se realiza para solicitudes válidas.

Nota:

Establezca los elementos de la directiva y los elementos secundarios en el orden proporcionado en la instrucción de directiva. Obtenga más información sobre el establecimiento o modificación de directivas de API Management.

Instrucción de la directiva

<validate-graphql-request error-variable-name="variable name" max-size="size in bytes" max-depth="query depth">
    <authorize>
        <rule path="query path, for example: '/listUsers' or '/__*'" action="string or policy expression that evaluates to 'allow | remove | reject | ignore'" />
    </authorize>
</validate-graphql-request>

Atributos

Atributo Descripción Necesario Valor predeterminado
error-variable-name Nombre de la variable de context.Variables en la que se registrarán los errores de validación. Se permiten expresiones de directiva. No N/D
max-size Tamaño máximo de la carga útil de la solicitud en bytes. Valor máximo permitido: 102 400 bytes (100 KB). (Póngase en contacto con el soporte técnico si necesita aumentar este límite). Se permiten expresiones de directiva. Sí N/D
max-depth Entero. Profundidad de consulta máxima. Se permiten expresiones de directiva. No 6

Elementos

Nombre Descripción Obligatorio
autorización Agregue este elemento para establecer una regla de autorización adecuada para una o varias rutas de acceso. No
rule Agregue uno o varios de estos elementos para autorizar rutas de acceso de consulta específicas. Opcionalmente, cada regla puede especificar una acción diferente. Se puede especificar condicionalmente mediante una expresión de directiva. No

Atributos de regla

Atributo Descripción Necesario Valor predeterminado
path Ruta de la consulta en la que se ejecuta la validación de la autorización. Debe seguir el patrón: /type/field. Sí N/D
action Acción que se realiza si se aplica la regla. Se puede especificar condicionalmente mediante una expresión de directiva. No allow

Sistema de introspección

La directiva de path=/__* es el sistema de introspección. Puede usarla para rechazar solicitudes de introspección (__schema, __type, etc.).

Acciones de solicitud

Las acciones disponibles se describen en la tabla siguiente.

Acción Descripción
reject Se produce un error de solicitud y la solicitud no se envía al back-end. No se aplican reglas adicionales, aunque estén configuradas.
remove Se produce un error de campo y el campo se quita de la solicitud.
allow El campo se pasa al back-end.
ignore La regla no es válida para este caso y se aplica la siguiente regla.

Uso

Notas de uso

  • Configure la directiva para una API GraphQL pass-through o sintética API GraphQL que se ha importado a API Management.

  • Esta directiva solo se puede usar una vez en una sección de directiva.

  • Dado que las consultas de GraphQL usan un esquema sin formato, los permisos se pueden aplicar en cualquier nodo hoja de un tipo de salida:

    • Mutación, consulta o suscripción
    • Campo individual en una declaración de tipos

    Es posible que los permisos no se apliquen a:

    • Tipos de entrada
    • Fragments
    • Uniones
    • Interfaces
    • El elemento de esquema

  • La directiva puede validar las solicitudes de GraphQL con hasta 250 campos de consulta en todos los niveles.

Control de errores

Si no se valida con el esquema GraphQL o se produce un error en el tamaño o la profundidad de la solicitud, se trata de un error de solicitud y se produce un error en la solicitud con un bloque de errores (pero sin bloque de datos).

De forma similar a la propiedad Context.LastError, todos los errores de validación de GraphQL se propagan automáticamente en la variable GraphQLErrors. Si los errores deben propagarse por separado, puede especificar un nombre de variable de error. Los errores se insertan en la variable error y en la variable GraphQLErrors.

Ejemplos

Validación de consultas

En este ejemplo se aplican las siguientes reglas de validación y autorización a una consulta de GraphQL:

  • Las solicitudes que tienen más de 100 kb o una profundidad de consulta superior a 4 se rechazan.
  • Las solicitudes al sistema de introspección se rechazan.
  • El campo /Missions/name se quita de las solicitudes que contienen más de dos encabezados.
<validate-graphql-request error-variable-name="name" max-size="102400" max-depth="4"> 
    <authorize>
        <rule path="/__*" action="reject" /> 
        <rule path="/Missions/name" action="@(context.Request.Headers.Count > 2 ? "remove" : "allow")" />
    </authorize>
</validate-graphql-request>

Validación de mutaciones

En este ejemplo se aplican las siguientes reglas de validación y autorización a una mutación de GraphQL:

  • Las solicitudes que tienen más de 100 kb o una profundidad de consulta superior a 4 se rechazan.
  • Las solicitudes para mutar el campo deleteUser se deniegan, excepto cuando proviene de la dirección IP 198.51.100.1.
<validate-graphql-request error-variable-name="name" max-size="102400" max-depth="4"> 
    <authorize>
        <rule path="/Mutation/deleteUser" action="@(context.Request.IpAddress <> "198.51.100.1" ? "deny" : "allow")" />
    </authorize>
</validate-graphql-request>

Contenido relacionado

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