Questa pagina si applica a Apigee e Apigee ibridi.
Visualizza 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 tutte gli utenti devono conoscere i tipi di criteri e di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità per ciascun tipo di ambiente, consulta Tipi di criteri.
Consulta Utilizzo di GraphQL per un esempio che utilizza questo criterio.
<GraphQL>
elemento
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
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 tuo 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 tabella seguente fornisce una descrizione generale degli elementi secondari di
<GraphQL>
:
Elemento secondario | Obbligatorio? | Descrizione |
---|---|---|
Operazioni comuni | ||
<Action> |
Facoltativo | Specifica l'azione da eseguire per una richiesta: parse , verify oppure
parse_verify (entrambi).
|
<MaxCount> |
Facoltativo | Il numero massimo di query o frammenti che può generare una richiesta GraphQL. 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 viene 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 del flusso dei messaggi. Vedi Esempi di flusso di messaggi rappresentazioni delle variabili per una spiegazione delle variabili impostate quandoAction
impostato suparse
. Ciò consente di risparmiare tempo di CPU prezioso di un backend cloud. Tieni presente che ancheverify
analizza il payload.verify
: Apigee verifica che il payload GraphQL sia conforme allo schema caricati 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 nel payload. Puoi utilizzarlo per impedire che il server di back-end GraphQL del cliente venga eseguito altamente complesse query, costringendo i clienti a suddividere 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, se 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 |
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 utilizzarlo per limitare il payload per evitare problemi di prestazioni.
Nota:se MaxPayloadSizeInByte
non è specificato nelle norme,
non viene applicato alcun limite di 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 GraphQLquery_mutation
: una query GraphQL o una mutazione.
Se l'ambito è query
e viene passata una richiesta di modifica, la richiesta non va a buon fine
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 a cui il criterio GraphQL verifica le richieste. Consulta: Esempio: caricando uno schema GraphQL su Apigee.
Se il nome del file di schema caricato è my-schema.graphql
, allora
<ResourceURL>
elemento sarebbe
<ResourceURL>graphql://my-schema.graphql</ResourceURL>
Valore predefinito | n/a |
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 in cui viene eseguito questo criterio.
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 GraphQL supporta tutte le funzionalità di una query GraphQL la rappresenta come un grafico nella notazione puntata del flusso dei messaggi. Una query può comprendere operazioni e facoltativamente frammenti identificati come definizioni di frammenti. Consulta le Specifiche 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 Sintassi GraphQL, compreso il supporto di query e mutazioni. Consulta: Variabile del flusso dei messaggi.
Le variabili del 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 di query a livello principale (il valore predefinito è fino a 4 per richiesta)root-definition
: corpo del messaggio di richiesta di GraphQL a livello di directory principale, argomenti e 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 |
---|---|---|
nome | Stringa | Nome dell'operazione graphicQL. 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 un argomento per una funzione in un linguaggio digitato. it elenca tutte le variabili, precedute dal prefisso $, seguite dal tipo. |
direttive | Numero intero | @include e @skip sono le due istruzioni attualmente offerte, che possono filtrare in base 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 del flusso di messaggi | Tipo | Descrizione |
---|---|---|
nome | 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 del flusso di messaggi
I seguenti esempi mostrano le rappresentazioni delle variabili di flusso dei messaggi per di esempio per i payload di richieste di esempio.
Query di esempio 1
Questo esempio mostra una query effettuata con argomenti passati come input, che esegue query tre attributi per i dipendenti.
{ employee(id: 123) { id firstName lastName } }
La tabella mostra le rappresentazioni delle variabili del flusso di 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 effettuata con argomenti passati come input, che esegue query i nomi degli amici.
query Characters($episode: Episode, $withFriends: Boolean!) { friends @include(if: $withFriends) { friendsName } }
La tabella seguente mostra le corrispondenti rappresentazioni delle variabili del flusso di 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 del flusso di 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 |