Questa pagina si applica a Apigee e Apigee ibrido.
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à di ciascun tipo di ambiente, consulta Tipi di criteri.
Consulta Utilizzo di GraphQL per un esempio di impiego di questo criterio.
<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 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 seguente tabella 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 o
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 |
Nelle sezioni che seguono viene descritto ognuno di questi elementi secondari.
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. Consulta Esempi di rappresentazioni delle variabili del flusso di messaggi per una spiegazione delle variabili impostate quandoAction
è impostato suparse
. Ciò consente di risparmiare tempo di CPU prezioso nel backend. Tieni presente che ancheverify
analizza 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 | String |
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 al server di backend GraphQL del cliente di eseguire query altamente complesse, costringendo i client a interrompere la logica in payload più piccoli.
Valore predefinito | 10 |
Obbligatorio? | Optional |
Tipo | String |
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
consente di bloccare 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 | Integer |
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 la dimensione del payload ed evitare problemi di prestazioni.
Nota: se MaxPayloadSizeInByte
non è specificato nel criterio,
non viene applicata alcuna limitazione di dimensioni.
Valore predefinito | request |
Obbligatorio? | Optional |
Tipo | String |
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 mutazione, la richiesta non va a buon fine e restituisce un errore 4xx
.
Valore predefinito | query |
Obbligatorio? | Optional |
Tipo | String |
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 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 | String |
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 | String |
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
Il parser GraphQL supporta tutte le funzionalità di una query GraphQL e lo rappresenta come un grafico nella notazione puntata del flusso dei messaggi. 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.
![Diagramma di query GraphQL.](https://cloud.google.com/static/apigee/docs/api-platform/develop/images/graphql-query.png?authuser=7&hl=it)
Rappresentazione nel flusso di messaggi delle definizioni delle operazioni
L'implementazione del parser copre tutti gli aspetti della sintassi di GraphQL, compreso il supporto per query e mutazioni. Vedi 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 è di 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 Fogliolina correlate a campi specifici e relativi valori
Rappresentazione nella variabile del flusso di messaggi delle definizioni delle operazioni
Campi nel messaggio | Tipo | Descrizione |
---|---|---|
nome | String | 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 | Integer | Funzionano esattamente come le definizioni di un argomento per una funzione in un linguaggio digitato. Elenca tutte le variabili, precedute dal prefisso $, seguite dal tipo. |
direttive | Integer | @include e @skip sono le due istruzioni attualmente offerte, che possono filtrare in base a valori passati dinamicamente. |
selectionSet | Integer | 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 | String | Nome del frammento. |
definizione | Stringa - Frammento | Indica che il corpo della richiesta è un frammento della richiesta principale. |
typeCondition | String | La condizione in cui viene richiamato il frammento. |
variableDefinition | Integer | La definizione delle variabili passate come argomenti al frammento. |
Esempi di rappresentazioni delle variabili del flusso di messaggi
Gli esempi seguenti mostrano le rappresentazioni delle variabili di flusso dei messaggi 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 per 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 sui 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 |