Criterio GraphQL

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Cosa

Il criterio GraphQL può analizzare i payload di GraphQL in variabili del flusso dei messaggi, verificare le richieste di GraphQL rispetto a uno schema o entrambi.

Puoi utilizzare il criterio GraphQL per:

• Assicurati che le API elaborino solo le richieste conformi allo schema che fornisci.
• Imponi limitazioni sul payload impostando un valore massimo sul numero di frammenti consentiti.
• Associare GraphQL ai prodotti API.
• Utilizza le funzionalità dei criteri Oauth2, VerificationAPIKey e Quota, proprio come in REST.

GraphQL supporta i seguenti tipi di payload:

• POST di payload GraphQL con Content-Type : application/graphql
• POST di payload GraphQL con Content-Type: applcation/json
• GET di payload GraphQL in cui il payload è un parametro di ricerca

Nota: per application/json payload del modulo

{
"query": "...",
"operationName": "...",
"variables": { "myVariable": "someValue", ... }
}

Attualmente Apigee ignora i campi facoltativi operationName e variables.

Per maggiori informazioni, consulta le seguenti risorse:

• Introduzione a GraphQL
• Query e mutazioni
• Riferimento per le variabili di flusso

Questo è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Non tutti gli utenti devono conoscere i tipi di criteri e di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità con ogni tipo di ambiente, consulta Tipi di criteri.

Per un esempio in cui viene utilizzato questo criterio, consulta Utilizzo di GraphQL.

Attenzione: la verifica del payload rispetto allo schema è generalmente un'operazione costosa e ti consigliamo di valutarla con attenzione quando decidi se eseguire la convalida dello schema. Le operazioni di convalida dello schema possono richiedere un utilizzo intensivo della CPU, soprattutto quando il payload e lo schema sono complessi e possono generare latenze significative.

Nota: puoi fornire un solo schema per criterio. Se devi includere più schemi, aggiungi più criteri GraphQL al tuo proxy.

<GraphQL> elemento

Definisce un criterio <GraphQL>.

Valore predefinito	Consulta la scheda Criterio predefinito di seguito
Obbligatorio?	Obbligatorio
Tipo	TIPO
Elemento principale	n/d
Elementi secondari	<Action> <MaxDepth> <MaxCount> <MaxPayloadSizeInBytes> <OperationType> <Source> <ResourceURL>

Sintassi

L'elemento <GraphQL> utilizza la seguente sintassi:

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Source>request</Source>
  <OperationType>[query|mutuation|all]</OperationType>
  <MaxDepth>MAX_DEPTH</MaxDepth>
  <MaxCount>MAX_NUMBER_OF_QUERIES</MaxCount>
  // [Start maxpayloadsize]
  <MaxPayloadSizeInBytes>MAX_PAYLOAD_SIZE_IN_BYTES</MaxPayloadSizeInBytes>
  <Action>parse</Action>
  <ResourceURL>PATH/TO/SCHEMA.xsd</ResourceURL>
</GraphQL>

Criterio predefinito

L'esempio seguente mostra le impostazioni predefinite quando aggiungi un criterio <GraphQL> al flusso nella UI di Apigee:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GraphQL name="GraphQLParser">
  <Source>request</Source>
  <OperationType>query</OperationType>
  <MaxDepth>10</MaxDepth>
  <MaxCount>10</MaxCount>
  <MaxPayloadSizeInBytes></MaxPayloadSizeInBytes>
  <Action>parse</Action>
  <ResourceURL></ResourceURL>
</GraphQL>

Questo elemento ha i seguenti attributi comuni a tutti i criteri:

Attributo	Predefinito	Obbligatorio?	Descrizione
name	N/A	Obbligatorio	Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri. Facoltativamente, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.
continueOnError	falso	Facoltativo	Imposta su false per restituire un errore in caso di errore del criterio. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un errore nel criterio. Vedi anche: Le regole di errore vengono attivate SOLO in uno stato di errore (su continueOnError) Gestione degli errori nel flusso corrente
enabled	true	Facoltativo	Imposta su true per applicare il criterio. Imposta su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.
async	falso	Deprecato	Questo attributo è stato ritirato.

La tabella seguente fornisce una descrizione generale degli elementi secondari di <GraphQL>:

Elemento secondario	Obbligatorio?	Descrizione
Operazioni comuni
<Action>	Facoltativo	Specifica l'azione da intraprendere per una richiesta: parse, verify o parse_verify (entrambe).
<MaxCount>	Facoltativo	Il numero massimo di query o frammenti che una richiesta GraphQL può generare. Il valore predefinito è 10.
<MaxDepth>	Facoltativo	La profondità massima dell'albero per la query. Il valore predefinito è 4.
<MaxPayloadSizeInBytes>	Facoltativo	La dimensione massima di un payload in kilobyte.
<OperationType>	Obbligatorio	Specifica il tipo di richiesta che può essere analizzato: query, mutation o query_mutation (uno dei due).
<ResourceURL>	Facoltativo	DESCRIPTION. La posizione del file di schema GraphQL.
<Source>	Obbligatorio	request

Ciascuno di questi elementi secondari è descritto nelle sezioni seguenti.

Riferimento elemento secondario

In questa sezione vengono descritti gli elementi secondari di <GraphQL>.

<Action>

L'azione rappresenta una delle seguenti azioni GraphQL:

• parse: Apigee analizza il payload GraphQL nelle variabili di flusso dei messaggi. Consulta gli esempi di rappresentazioni delle variabili del flusso dei messaggi per una spiegazione delle variabili impostate quando Action è impostato su parse. In questo modo, puoi risparmiare tempo di CPU prezioso nel backend. Tieni presente che verify analizza anche il payload.
• verify: Apigee verifica che il payload GraphQL sia conforme allo schema caricato sul proxy.
• parse_verify: Apigee analizza e verifica la richiesta GraphQL.

Valore predefinito	parse
Obbligatorio?	Optional
Tipo	Stringa
Elemento principale	<GraphQL>
Elementi secondari	nessuno

L'elemento <Action> utilizza la seguente sintassi:

Sintassi

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Action>parse</Action>
</GraphQL>

<MaxCount>

Il numero massimo di frammenti che possono essere presenti nel payload. Puoi utilizzarla per impedire al server di backend GraphQL del cliente di eseguire query molto complesse, costringendo i client a violare la loro logica in payload più piccoli.

Valore predefinito	10
Obbligatorio?	Optional
Tipo	Stringa
Elemento principale	<GraphQL>
Elementi secondari	nessuno

L'elemento <MaxCount> utilizza la seguente sintassi:

Sintassi

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxCount>MAX_NUMBER_OF_QUERIES</MaxCount>
</GraphQL>

<MaxDepth>

La profondità massima della query, quando rappresentata come albero. MaxDepth consente di bloccare query approfondite nel payload, in modo che Apigee non abbia bisogno di creare variabili di flusso molto grandi per contenere i valori. Tuttavia, il payload viene inviato così com'è, indipendentemente dal valore di MaxDepth. Il valore predefinito è 10.

Nota: MaxDepth funziona quando l'elemento Action è impostato su parse o parse-verify. È buona norma usare MaxDepth con queste azioni per verificare la profondità anziché utilizzare l'azione verify, più costosa.

Valore predefinito	10
Obbligatorio?	Optional
Tipo	Numero intero
Elemento principale	<GraphQL>
Elementi secondari	nessuno

L'elemento <MaxDepth> utilizza la seguente sintassi:

Sintassi

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxDepth>MAX_DEPTH</MaxDepth>
</GraphQL>

<MaxPayloadSizeInBytes>

La dimensione massima di un payload in kilobyte. Puoi utilizzarla per limitare le dimensioni del payload, ed evitare problemi di prestazioni.

Nota: se non viene fornito il valore MaxPayloadSizeInByte nel criterio, non viene applicata alcuna limitazione relativa alle dimensioni.

Valore predefinito	request
Obbligatorio?	Optional
Tipo	Stringa
Elemento principale	<GraphQL>
Elementi secondari	nessuno

L'elemento <MaxPayloadSizeInBytes> utilizza la seguente sintassi:

Sintassi

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxPayloadSizeInBytes>MAX_PAYLOAD_SIZE_IN_BYTES</MaxPayloadSizeInBytes>
</GraphQL>

<OperationType>

Indica il tipo di richiesta che può essere analizzata:

• query: una query GraphQL.
• mutation: una mutazione GraphQL
• query_mutation: una query GraphQL o una mutazione.

Se l'ambito è query e viene passata una richiesta di modifica, la richiesta non riesce e restituisce un errore 4xx.

Valore predefinito	query
Obbligatorio?	Optional
Tipo	Stringa
Elemento principale	<GraphQL>
Elementi secondari	nessuno

L'elemento <OperationType> utilizza la seguente sintassi:

Sintassi

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <OperationType>[query|mutation|query_mutation]</OperationType>
</GraphQL>

<ResourceURL>

Il percorso del file di schema GraphQL in base al quale il criterio GraphQL verifica le richieste. Consulta Esempio per un esempio di caricamento di uno schema GraphQL su Apigee.

Se il nome del file di schema caricato è my-schema.graphql, l'elemento <ResourceURL> sarà

<ResourceURL>graphql://my-schema.graphql</ResourceURL>

Valore predefinito	n/d
Obbligatorio?	Facoltativo
Tipo	Stringa
Elemento principale	<GraphQL>
Elementi secondari	nessuno

L'elemento ResourceURL utilizza la seguente sintassi:

Sintassi

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <ResourceURL>PATH/TO/SCHEMA.graphql</ResourceURL>
</GraphQL>

<Source>

Origine su cui viene eseguito il criterio.

Nota: l'origine deve essere la stringa di query Graphql non elaborata e non una query Graphql con wrapping in JSON.

Valore predefinito	request
Obbligatorio?	Optional
Tipo	Stringa
Elemento principale	<GraphQL>
Elementi secondari	nessuno

L'elemento <Source> utilizza la seguente sintassi:

Sintassi

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Source>request</Source>
</GraphQL>

Parser GraphQL

L'analizzatore sintattico di GraphQL supporta tutte le funzionalità di una query GraphQL e la rappresenta come grafico nella notazione punteggiata del flusso dei messaggi. Una query può comprendere la definizione di operazioni e, facoltativamente, frammenti identificati come definizioni di frammenti. Consulta la specifica di GraphaphQL.

Anatomia di una richiesta GraphQL

Il diagramma seguente mostra l'anatomia di una richiesta GraphQL.

Rappresentazione nel flusso di messaggi delle definizioni delle operazioni

L'implementazione del parser copre tutti gli aspetti della sintassi di graphQL, compreso il supporto di query e mutazioni. Consulta Variabile di flusso dei messaggi.

Le variabili di flusso dei messaggi seguono questa convenzione:

graphql.(root-index).(root definition)[(sub-indices).(child-definitions)…]

dove:

• graphql: prefisso statico che indica che si tratta di variabili di flusso dei messaggi relative a GraphQL
• root-Index: indice basato che indica l'indice delle definizioni delle query di livello principale (valore predefinito fino a 4 per richiesta)
• root-definition: corpo del messaggio della richiesta GraphQL a livello radice, argomenti e valori
• sub-indices: indici secondari
• child-definitions: definizioni a livello di foglia correlate a campi specifici e ai relativi valori.

Variabile di rappresentazione nella variabile del flusso di messaggi delle definizioni delle operazioni

Campi nel messaggio	Tipo	Descrizione
name	Stringa	Nome dell'operazione GraphQL. Tieni presente che questo nome non è correlato al nome nel flusso di messaggi.
definizione	Stringa - Operazione	Indica che contiene il corpo del messaggio principale della richiesta di query
operationType	query o mutazione	Il tipo di operazione eseguita.
variableDefinition	Numero intero	Funzionano esattamente come le definizioni di argomenti per una funzione in un linguaggio digitato. Elenca tutte le variabili, con il prefisso $, seguite dal tipo.
istruzioni	Numero intero	@include e @skip sono le due istruzioni attualmente offerte che possono filtrare in base a valori trasferiti dinamicamente.
selectionSet	Numero intero	Raggruppamento logico a un livello di tutti gli attributi associati a un oggetto.

Rappresentazione nel flusso di messaggi delle definizioni di frammenti

Nome variabile del flusso di messaggi	Tipo	Descrizione
name	Stringa	Nome del frammento.
definizione	Stringa - frammento	Indica che il corpo della richiesta è un frammento della richiesta principale.
typeCondition	Stringa	La condizione in cui viene richiamato il frammento.
variableDefinition	Numero intero	La definizione delle variabili passata come argomento al frammento.

Esempi di rappresentazioni di variabili del flusso di messaggi

I seguenti esempi mostrano le rappresentazioni delle variabili del flusso dei messaggi per i payload di richieste di esempio.

Query di esempio 1

Questo esempio mostra una query eseguita con argomenti passati come input, che esegue query su tre attributi per i dipendenti.

{
 employee(id: 123) {
   id
   firstName
   lastName
 }
}

La tabella mostra le rappresentazioni delle variabili del flusso dei messaggi corrispondenti.

Variabile di flusso message	Valore
graphql.operation.operationType	QUERY
graphql.fragment.count	1
graphql.operation.selectionSet.count	1
graphql.operation.variableDefinitions.count	0
graphql.operation.selectionSet.1.name	employee
graphql.operation.selectionSet.1.argument.count	1
graphql.operation.selectionSet.1.argument.1.name	id
graphql.operation.selectionSet.1.argument.1.value	IntValue{value=123}
graphql.operation.selectionSet.1.directive.count	0
graphql.operation.selectionSet.1.selectionSet.count	3
graphql.operation.selectionSet.1.selectionSet.1.name	id
graphql.operation.selectionSet.1.selectionSet.2.name	firstName
graphql.operation.selectionSet.1.selectionSet.3.name	lastName

Query di esempio 2

Questo esempio mostra una query eseguita con argomenti passati come input, che esegue query per i nomi degli amici.

query Characters($episode: Episode, $withFriends: Boolean!) {
   friends @include(if: $withFriends) {
     friendsName
    }
}

La tabella seguente mostra le rappresentazioni delle variabili del flusso dei messaggi corrispondenti.

Variabile di flusso message	Valore
graphql.operation.operationType	QUERY
graphql.operation.selectionSet.count	1
graphql.operation.name	Characters
graphql.fragment.count	0
graphql.operation.selectionSet.1.name	friends
graphql.operation.variableDefinitions.count	2
graphql.operation.variableDefinitions.1.name	episode
graphql.operation.variableDefinitions.1.type	TypeName{name='Episode'}
graphql.operation.variableDefinitions.2.name	withFriends
graphql.operation.variableDefinitions.2.type	NonNullType{type=TypeName{name='Boolean'}}
graphql.operation.selectionSet.1.argument.count	0
graphql.operation.selectionSet.1.selectionSet.count	1
graphql.operation.selectionSet.1.selectionSet.1.name	friendsName
graphql.operation.selectionSet.1.directive.count	1
graphql.operation.selectionSet.1.directive.1.argument.1.name	if
graphql.operation.selectionSet.1.directive.1.argument.1.value	VariableReference{name='withFriends'}

Query di esempio 3

Questo esempio ha una definizione di variabile con alias.

query getUsers {
  admins: users(role: ADMIN) {
    lastName
  }
  accountants: users(role: ACCOUNTANT) {
    firstName
  }
}

La tabella seguente mostra le rappresentazioni delle variabili del flusso dei messaggi corrispondenti.

Variabile di flusso message	Valore
graphql.operation.operationType	QUERY
graphql.operation.selectionSet.count	2
graphql.operation.selectionSet.1.name	users
graphql.operation.selectionSet.1.alias	admins
graphql.operation.variableDefinitions.count	0
graphql.operation.selectionSet.1.argument.count	1
graphql.operation.selectionSet.1.argument.1.name	role
graphql.operation.selectionSet.1.argument.1.value	EnumValue{name='ADMIN'}
graphql.operation.selectionSet.1.argument.2.name	null
graphql.operation.selectionSet.1.argument.2.value	null
graphql.operation.selectionSet.1.selectionSet.count	1
graphql.operation.selectionSet.1.selectionSet.count	1
graphql.operation.selectionSet.1.selectionSet.1.name	lastName
graphql.operation.selectionSet.1.selectionSet.1.alias	null
graphql.operation.selectionSet.1.selectionSet.2.name	null
graphql.operation.selectionSet.1.selectionSet.2.alias	null
graphql.operation.selectionSet.1.directive.count	0
graphql.operation.selectionSet.1.directive.1.argument.1.name	null
graphql.operation.selectionSet.1.directive.1.argument.1.value	null
graphql.operation.selectionSet.2.name	users
graphql.operation.selectionSet.2.alias	accountants
graphql.operation.selectionSet.2.argument.count	1
graphql.operation.selectionSet.2.argument.1.name	role
graphql.operation.selectionSet.2.argument.1.value	EnumValue{name='ACCOUNTANT'}
graphql.operation.selectionSet.2.selectionSet.count	1
graphql.operation.selectionSet.2.selectionSet.1.name	firstName
graphql.operation.selectionSet.2.directive.count	0
graphql.operation.selectionSet.2.selectionSet.1.alias	null
graphql.operation.selectionSet.2.selectionSet.2.name	null
graphql.operation.selectionSet.2.selectionSet.2.alias	null
graphql.operation.selectionSet.2.directive.count	0

Argomenti correlati

Utilizzo di GraphQL