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
Per maggiori informazioni, consulta le seguenti risorse:
Questo criterio è 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à per ogni tipo di ambiente, consulta Tipi di criteri.
Per un esempio in cui viene utilizzato questo criterio, consulta la sezione Utilizzo di GraphQL.
Elemento <GraphQL>
Definisce un criterio <GraphQL>
.
Valore predefinito | Vedi la scheda Criterio predefinito di seguito |
Obbligatorio? | Obbligatorio |
Tipo | TIPO |
Elemento principale | n/d |
Elementi secondari | <Action> <MaxDepth> <MaxCount> <MaxPayloadSizeInBytes> <OperationType> <Source> <ResourceURL> |
Sintassi
La sintassi dell'elemento <GraphQL>
è la seguente:
<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>
Norma predefinita
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 Facoltativamente, utilizza l'elemento |
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:
|
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 seguente tabella 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 può generare una richiesta GraphQL. Il valore predefinito è 10. |
<MaxDepth> |
Facoltativo | La profondità massima della struttura 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 è possibile analizzare: query ,
mutation o query_mutation (uno dei due). |
<ResourceURL> |
Facoltativo | DESCRIZIONE. La posizione del file di schema GraphQL. |
<Source> |
Obbligatorio | request |
Ciascuno di questi elementi secondari è descritto nelle sezioni seguenti.
Riferimento per l'elemento secondario
Questa sezione descrive 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 Esempi di rappresentazioni delle variabili per il flusso di messaggi per una spiegazione delle variabili impostate quandoAction
è impostato suparse
. Ciò può far risparmiare tempo di CPU prezioso nel backend. Tieni presente cheverify
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 |
La sintassi dell'elemento <Action>
è la seguente:
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 back-end GraphQL del cliente di eseguire query molto complesse, costringendo i client a violare la propria logica in payload più piccoli.
Valore predefinito | 10 |
Obbligatorio? | Optional |
Tipo | Stringa |
Elemento principale | <GraphQL> |
Elementi secondari | nessuno |
La sintassi dell'elemento <MaxCount>
è la seguente:
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 una struttura ad 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.
Valore predefinito | 10 |
Obbligatorio? | Optional |
Tipo | Numero intero |
Elemento principale | <GraphQL> |
Elementi secondari | nessuno |
La sintassi dell'elemento <MaxDepth>
è la seguente:
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, in modo da evitare problemi di prestazioni.
Nota: se MaxPayloadSizeInByte
non viene fornito nel criterio,
non viene applicata alcuna limitazione di dimensioni.
Valore predefinito | request |
Obbligatorio? | Optional |
Tipo | Stringa |
Elemento principale | <GraphQL> |
Elementi secondari | nessuno |
La sintassi dell'elemento <MaxPayloadSizeInBytes>
è la seguente:
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 è possibile analizzare:
query
: una query GraphQL.mutation
: una mutazione GraphQLquery_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 |
La sintassi dell'elemento <OperationType>
è la seguente:
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. Vedi Esempio per un esempio di caricamento di uno schema GraphQL in Apigee.
Se il nome del file di schema caricato è my-schema.graphql
, l'elemento <ResourceURL>
sarebbe
<ResourceURL>graphql://my-schema.graphql</ResourceURL>
Valore predefinito | n/d |
Obbligatorio? | Facoltativo |
Tipo | Stringa |
Elemento principale | <GraphQL> |
Elementi secondari | nessuno |
La sintassi dell'elemento ResourceURL
è la seguente:
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.
Valore predefinito | request |
Obbligatorio? | Optional |
Tipo | Stringa |
Elemento principale | <GraphQL> |
Elementi secondari | nessuno |
La sintassi dell'elemento <Source>
è la seguente:
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 un grafico nella notazione punteggiata del flusso del messaggio. Una query può comprendere la definizione dell'operazione e, facoltativamente, frammenti identificati come definizioni di frammenti. Consulta la specifica GraphQL.
Struttura 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 graphQL, compreso il supporto di query e mutazioni. Vedi 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 di messaggi relative a GraphQLroot-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 di livello radice, argomenti, relativi valorisub-indices
: indici secondarichild-definitions
: definizioni a livello di foglia correlate a campi specifici e relativi valori
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 una lingua digitata. Elenca tutte le variabili, precedute dal prefisso $, seguite dal tipo. |
istruzioni | Numero intero | @include e @skip sono le due istruzioni attualmente offerte che possono filtrare in base a valori passati dinamicamente. |
selectionSet | Numero intero | Raggruppamento logico di un livello di tutti gli attributi associati a un oggetto. |
Rappresentazione nel flusso di messaggi delle definizioni di frammenti
Nome variabile flusso messaggio | 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 passate come argomenti al frammento. |
Esempi di rappresentazioni delle variabili per il flusso di messaggi
Gli esempi seguenti mostrano le rappresentazioni delle variabili di flusso dei messaggi per i payload di richiesta di esempio.
Esempio di query 1
Questo esempio mostra una query eseguita con argomenti passati come input, che esegue query per tre attributi per i dipendenti.
{ employee(id: 123) { id firstName lastName } }
La tabella mostra le rappresentazioni della variabile di 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 |
Esempio di query 2
Questo esempio mostra una query realizzata 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 corrispondenti rappresentazioni delle variabili di flusso dei messaggi.
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 corrispondenti rappresentazioni delle variabili di flusso dei messaggi.
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 |