Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di Apigee Edge.
Cosa
Il criterio GraphQL può analizzare i payload GraphQL in variabili di flusso di messaggi, verificare le richieste GraphQL rispetto a uno schema o entrambe le cose.
Puoi utilizzare il criterio GraphQL per:
- Assicurati che le tue API elaborino solo le richieste conformi allo schema che fornisci.
- Impostare limitazioni sul payload impostando un numero massimo di frammenti consentiti.
- Associa GraphQL ai prodotti API.
- Utilizza le funzionalità Oauth2, VerifyAPIKey e Quota policy, 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 dei payload GraphQL in cui il payload è un parametro di query
Per maggiori informazioni, consulta le seguenti risorse:
Questo criterio è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Per informazioni sui tipi di criteri e sulla loro disponibilità in base a ciascun tipo di ambiente, consulta Tipi di criteri.
Consulta Utilizzo di GraphQL per un esempio che utilizza questo criterio.
Elemento <GraphQL>
Definisce un criterio <GraphQL>
.
Valore predefinito | Consulta la scheda Criterio predefinito di seguito |
Obbligatorio? | Obbligatorio |
Tipo | TIPO |
Elemento principale | n/a |
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>
Norme predefinite
L'esempio seguente mostra le impostazioni predefinite quando aggiungi un criterio <GraphQL>
al flusso nell'interfaccia utente 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/D | Obbligatorio |
Il nome interno del criterio. Il valore dell'attributo Se vuoi, utilizza l'elemento |
continueOnError |
falso | Facoltativo | Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del 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 | Ritirato | 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 | DESCRIZIONE. La posizione del file dello schema GraphQL. |
<Source> |
Obbligatorio | request |
Ciascuno di questi elementi secondari è descritto nelle sezioni che seguono.
Riferimento all'elemento secondario
Questa sezione descrive gli elementi secondari di <GraphQL>
.
<Action>
Azione rappresenta una delle seguenti azioni GraphQL:
parse
: Apigee analizza il payload GraphQL in variabili di flusso dei messaggi. Consulta Esempi di rappresentazioni delle variabili del flusso di messaggi per una spiegazione delle variabili impostate quandoAction
è impostato suparse
. In questo modo puoi risparmiare tempo prezioso della CPU nel backend. Tieni presente cheverify
esegue anche l'analisi del 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 utilizzarlo per impedire al server di backend GraphQL del cliente di eseguire query molto complesse, costringendo i client a suddividere la 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 un albero.
MaxDepth
ti consente di bloccare le query approfondite nel payload,
in modo che Apigee non debba 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 utilizzarlo per limitare le dimensioni del payload per evitare problemi di rendimento.
Nota:se MaxPayloadSizeInByte
non è specificato 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 può essere analizzata:
query
: una query GraphQL.mutation
: una mutazione GraphQLquery_mutation
: una query o una mutazione GraphQL.
Se l'ambito è query
e viene passata una richiesta di mutazione, 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 dello schema GraphQL in base al quale il criterio GraphQL convalida le richieste. Consulta Esempio per un esempio di caricamento di uno schema GraphQL in Apigee.
Se il nome del file dello schema caricato è my-schema.graphql
, l'elemento <ResourceURL>
sarà
<ResourceURL>graphql://my-schema.graphql</ResourceURL>
Valore predefinito | n/a |
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 questo 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>
Analizzatore sintattico GraphQL
Il parser GraphQL supporta tutte le funzionalità di una query GraphQL e la rappresenta come un grafo nella notazione a punti del flusso di messaggi. Una query può essere composta da una definizione di operazione e, facoltativamente, da frammenti identificati come definizioni di frammenti. Consulta la specifica GraphQL.
Anatomia di una richiesta GraphQL
Il diagramma seguente mostra l'anatomia di una richiesta GraphQL.
Rappresentazione nel flusso di messaggi delle definizioni di operazioni
L'implementazione del parser copre tutti gli aspetti della sintassi di GraphQL, incluso il supporto di query e mutazioni. Vedi Variabile di flusso messaggio.
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 correlate a GraphQLroot-Index
: indice basato che indica l'indice delle definizioni delle query a livello di radice (valore predefinito fino a 4 per richiesta)root-definition
: corpo del messaggio della richiesta GraphQL a livello di radice, args, i relativi valorisub-indices
: Indici secondarichild-definitions
: definizioni a livello di elemento finale correlate a campi specifici e ai relativi valori
Rappresentazione nella variabile di flusso dei messaggi delle definizioni di operazioni
Campi nel messaggio | Tipo | Descrizione |
---|---|---|
nome | 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 principale del messaggio della richiesta di query |
operationType | query o mutazione | Il tipo di operazione in esecuzione. |
variableDefinition | Numero intero | Funzionano come le definizioni degli argomenti per una funzione in un linguaggio tipizzato. elenca tutte le variabili, precedute da $, seguite dal relativo tipo. |
direttive | Numero intero | @include e @skip sono le due direttive attualmente disponibili, che possono filtrare in base ai valori trasmessi dinamicamente. |
selectionSet | Numero intero | Raggruppamento logico di un livello di tutti gli attributi associati a un oggetto. |
Rappresentazione nel flusso di messaggi delle definizioni dei frammenti
Nome variabile flusso di messaggi | Tipo | Descrizione |
---|---|---|
nome | Stringa | Nome del frammento. |
definizione | Frammento di stringa | Indica che il corpo della richiesta è un frammento della richiesta principale. |
typeCondition | Stringa | La condizione in base alla quale viene richiamato il frammento. |
variableDefinition | Numero intero | La definizione delle variabili passata come argomenti al frammento. |
Esempi di rappresentazioni delle variabili di flusso di messaggi
Gli esempi seguenti mostrano le rappresentazioni delle variabili del flusso di messaggi per i payload delle richieste di esempio.
Query di esempio 1
Questo esempio mostra una query eseguita con gli argomenti passati come input, che esegue query su tre attributi per i dipendenti.
{ employee(id: 123) { id firstName lastName } }
La tabella mostra le rappresentazioni corrispondenti delle variabili del flusso di messaggi.
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 effettuata con gli 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 di 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 contiene 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 di 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 |