Convalidare la richiesta GraphQL

  • Articolo

SI APPLICA A: Tutti i livelli di Gestione API

Il criterio validate-graphql-request convalida la richiesta GraphQL e autorizza l'accesso a percorsi di query specifici in un'API GraphQL. Una query non valida è un "errore di richiesta". L'autorizzazione viene eseguita solo per le richieste valide.

Nota

Impostare gli elementi e gli elementi figlio del criterio nell'ordine specificato nell'istruzione del criterio. Altre informazioni su come impostare o modificare i criteri di API Management.

Istruzione del criterio

<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>

Attributi

Attributo Descrizione Richiesto Valore predefinito
error-variable-name Nome della variabile in context.Variables per registrare gli errori di convalida. Le espressioni di criteri sono consentite. No N/D
max_size Dimensioni massime del payload della richiesta in byte. Valore massimo consentito: 102.400 byte (100 KB). (se è necessario aumentare questo limite, contattare l'assistenza). Le espressioni di criteri sono consentite. Sì N/D
max_depth Valore intero. Profondità massima della query. Le espressioni di criteri sono consentite. No 6

Elementi

Nome Descrizione Richiesto
authorize Aggiungere questo elemento per impostare una regola di autorizzazione appropriata per uno o più percorsi. No
regola Aggiungere uno o più di questi elementi per autorizzare percorsi di query specifici. Ogni regola può facoltativamente specificare un'azione diversa. Può essere specificato in modo condizionale usando un'espressione di criteri. No

attributi delle regole

Attributo Descrizione Richiesto Valore predefinito
path Percorso in cui eseguire la convalida dell'autorizzazione. Deve seguire il modello: /type/field. Sì N/D
action Azione da eseguire se la regola viene applicata. Può essere specificato in modo condizionale usando un'espressione di criteri. No allow

Sistema di introspezione

Il criterio per path=/__* è il sistema di introspezione. È possibile usarlo per rifiutare le richieste di introspezione (__schema, __typee così via).

Richiedere azioni

Le azioni disponibili sono descritte nella tabella seguente.

Azione Descrizione
rifiuta Si verifica un errore di richiesta e la richiesta non viene inviata al back-end. Le regole aggiuntive, se configurate, non vengono applicate.
remove Si verifica un errore di campo e il campo viene rimosso dalla richiesta.
allow Il campo viene passato al back-end.
ignore La regola non è valida per questo caso e viene applicata la regola successiva.

Utilizzo

Note sull'utilizzo

  • Configurare i criteri per un'API GraphQL pass-through o sintetica importata in Gestione API.

  • Questo criterio può essere usato una sola volta in una sezione di criteri.

  • Poiché le query GraphQL usano uno schema flat, le autorizzazioni possono essere applicate a qualsiasi nodo foglia di un tipo di output:

    • Mutazione, query o sottoscrizione
    • Campo singolo in una dichiarazione di tipo

    Le autorizzazioni non possono essere applicate a:

    • Tipi di input
    • Frammenti
    • Unioni
    • Interfacce
    • Elemento dello schema

Gestione degli errori

L'errore di convalida dello schema GraphQL o un errore per le dimensioni o la profondità della richiesta è un errore di richiesta e la richiesta non riesce con un blocco di errori (ma nessun blocco di dati).

Analogamente alla proprietà Context.LastError, tutti gli errori di convalida GraphQL vengono propagati automaticamente nella variabile GraphQLErrors. Se gli errori devono essere propagati separatamente, è possibile specificare un nome di variabile di errore. Gli errori vengono inseriti nella variabile error e nella variabile GraphQLErrors.

Esempi

Convalida delle query

Questo esempio applica le regole di convalida e autorizzazione seguenti a una query GraphQL:

  • Le richieste superiori a 100 kb o con profondità di query superiori a 4 vengono rifiutate.
  • Le richieste al sistema di introspezione vengono rifiutate.
  • Il campo /Missions/name viene rimosso dalle richieste contenenti più di due intestazioni.
<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>

Convalida della mutazione

Questo esempio applica le regole di convalida e autorizzazione seguenti a una mutazione GraphQL:

  • Le richieste superiori a 100 kb o con profondità di query superiori a 4 vengono rifiutate.
  • Le richieste di modifica del campo deleteUser vengono negate tranne quando la richiesta proviene dall'indirizzo 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>

Contenuto correlato

Per ulteriori informazioni sull'utilizzo dei criteri, vedere: