Utilizzo di GraphQL

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Il criterio GraphQL può analizzare i payload di richieste GraphQL nelle variabili di flusso dei messaggi, verificare la richiesta in base a uno schema GraphQL o entrambi.

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 un breve riepilogo delle opzioni per il criterio GraphQL, consulta la sezione Opzioni di GraphQL di seguito.

Per ulteriori informazioni su GraphQL, consulta GraphQL.org.

Esempio

L'esempio seguente mostra come caricare uno schema GraphQL in Apigee e utilizzarlo per convalidare le richieste con contenuti GraphQL.

Attenzione: la verifica del payload rispetto allo schema è generalmente un'operazione costosa e ti consigliamo di scegliere di eseguire la convalida dello schema con cautela. 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.

Note: solo per l'editor proxy classico:

• Puoi caricare un file di schema GraphQL solo quando aggiungi un criterio GraphQL. Non puoi caricarlo nel riquadro Risorse dell'editor proxy.
• Dopo aver caricato un file di schema GraphQL, non puoi visualizzarlo o modificarlo nell'editor proxy.

Queste limitazioni non si applicano al nuovo Editor proxy.

Creare un file di schema

Per eseguire l'esempio, crea prima un file di schema GraphQL con il seguente contenuto:

type Query {
  allPersons(last: Int): [Person!]!
}

type Mutation {
  createPerson(name: String!, age: Int!): Person!
}

type Subscription {
  newPerson: Person!
}

type Person {
  name: String!
  sex: String!
  age: Int!
  posts: [Post!]!
}

type Post {
  title: String!
  author: Person!
}

Salva il file con il nome che preferisci, seguito dall'estensione .graphql.

Aggiungi il criterio GraphQL nella UI di Apigee

Nota: Apigee sta introducendo una nuova versione dell'editor proxy, che semplificherà la gestione dei proxy.

Le istruzioni nelle prime due schede di seguito spiegano come utilizzare il nuovo Proxy Editor o la versione classica.

Nuovo editor proxy

Innanzitutto, crea il criterio GraphQL nel seguente modo:

1. Accedi all'interfaccia utente di Apigee.
2. Nella barra di navigazione, seleziona Sviluppo > Proxy API.
3. Nell'elenco dei proxy, seleziona il proxy API per cui vuoi utilizzare il criterio GraphQL.
4. Fai clic sulla scheda SVILUPPO.
5. Nel riquadro a sinistra, fai clic sul pulsante + accanto alla cartella Policies (Norme).

6. Nella finestra di dialogo Crea criterio, fai clic sul campo Seleziona il tipo di criterio, scorri verso il basso fino a Mediazione e seleziona Grafico.

   

   Inserisci un Nome visualizzato e un Nome.

   Quindi, seleziona un file di schema GraphQL come segue:

   1. Fai clic sul campo File di schema. Vengono visualizzate le seguenti opzioni:
      • Nessuno schema. Se selezioni questa opzione, Apigee non utilizzerà uno schema per convalidare le richieste.
      • Importa schema GraphQL (.graphql)

   2. Seleziona Importa schema GraphQL (.graphql). Viene visualizzato quanto segue:

      

   3. Fai clic su Scegli file e seleziona il file di schema creato in precedenza (che deve avere l'estensione .graphql). Il file viene visualizzato nel campo Nome schema.

      
7. Fai clic su Crea per creare il criterio.

Ora che hai creato il criterio GraphQL, puoi collegarlo a un passaggio nel PreFlow:

1. Seleziona Endpoint del proxy > predefinito > PreFlow nel riquadro a sinistra:

   

2. Fai clic sul pulsante + accanto a PreFlow nel riquadro Risposta in basso a destra nell'Editor visivo:

   

3. Nella finestra di dialogo Aggiungi passaggio del criterio, seleziona il criterio GQL-.
   Nota: in questo esempio viene utilizzato il nome predefinito, GQL, per il criterio GraphQL. Puoi modificare il nome nell'elemento DisplayName del codice XML del criterio, aggiungendo una frase descrittiva dopo GQL-. Consulta la sezione Modificare il nome del criterio.
4. Fai clic su Aggiungi per allegare il criterio.
5. Fai clic su Salva per salvare la revisione corrente con le modifiche.
6. Per eseguire il deployment delle modifiche, fai clic sulla scheda Panoramica e seleziona Esegui il deployment.

Consulta le Opzioni di GraphQL di seguito per conoscere le opzioni che puoi impostare per il criterio GraphQL.

Editor proxy classico

1. Accedi all'interfaccia utente di Apigee.
2. Nella barra di navigazione, seleziona Sviluppo > Proxy API.
3. Nell'elenco dei proxy, seleziona il proxy API per cui vuoi utilizzare il criterio GraphQL.
4. Fai clic sulla scheda SVILUPPO.

5. Nel riquadro Flusso: PreFlow, fai clic sul pulsante + Passaggio.

   

6. Nel riquadro Aggiungi passaggio, scorri verso il basso fino in fondo alla sezione Mediazione e seleziona Grafico.

   

   Il riquadro Aggiungi passaggio mostra le seguenti opzioni:

   • Nome visualizzato: il nome visualizzato del criterio.
   • Nome: nome interno del criterio.
   • File di schema: è possibile caricare un file contenente uno schema GraphQL che Apigee utilizzerà per convalidare le richieste con contenuti GraphQL.

   Per utilizzare uno schema:

   1. Fai clic sul campo File di schema. Vengono visualizzate le seguenti opzioni:
      • Nessuno schema. Se selezioni questa opzione, Apigee non utilizzerà uno schema per convalidare le richieste.
      • Importa schema GraphQL (.graphql)

   2. Seleziona Importa schema GraphQL (.graphql). Viene visualizzato quanto segue:

      

   3. Fai clic su Scegli file e seleziona il file di schema creato in precedenza (che deve avere l'estensione .graphql). Il file viene visualizzato nel campo Nome schema.

      

7. Fai clic su Aggiungi. Il riquadro Flusso: PreFlow ora viene visualizzato come mostrato di seguito:

   

   Consulta le Opzioni di GraphQL di seguito per conoscere le opzioni che puoi impostare per il criterio GraphQL. Per questo esempio, lasciali invariati.

8. Per eseguire il deployment del proxy, fai clic sulla scheda Panoramica e seleziona Esegui il deployment.

   

Ora puoi testare il criterio GraphQL con il seguente comando curl:

curl --location --request POST 'https://PROXY_BASEPATH/HOST_NAME' --data-raw 'query query_name {allPersons {name}}' -k

Dove PROXY_BASEPATH è il percorso di base del proxy e HOST_NAME è il nome del proxy, incluso il numero di revisione più recente. Quando esegui il comando, Apigee convalida la richiesta in base allo schema e restituisce l'output seguente.

{
  "query query_name {allPersons {name}}": "",
  "id": 101
}

Ecco un altro esempio di richiesta:

curl --location --request POST 'https://PROXY_BASEPATH/HOST_NAME' --data-raw 'query ilovegql {DEADBEEF}' -k

Questa volta che la convalida della richiesta ha esito negativo e viene visualizzato il seguente messaggio di errore.

{"fault":{"faultstring":"steps.graphQL.SchemaValidationFailed","detail":{"errorcode":"steps.graphQL.SchemaValidationFailed"}}}

Opzioni GraphQL

GraphPolicy offre le seguenti opzioni:

• OperationType: il tipo di operazione. Le opzioni sono:
  • query: l'equivalente GraphQL dell'operazione REST GET.
  • mutation: l'equivalente GraphQL dell'operazione REST PUT.
  • query_mutation: query e mutation.
• MaxDepth: la profondità massima della query, se 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.
• 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 suddividere la loro logica in payload più piccoli.
• Action: una delle seguenti azioni GraphQL:
  • parseApigee analizza il payload GraphQL nelle variabili di flusso. Puoi quindi utilizzare i contenuti delle variabili di flusso in criteri come JavaCallout. Tieni presente che parse verifica anche il payload.
  • verify: Apigee verifica che il payload GraphQL sia conforme allo schema caricato sul proxy. Puoi utilizzare verify per assicurarti di non ricevere richieste non conformi allo schema. Ciò può far risparmiare tempo prezioso della CPU nel backend.
  • parse_verify: analizza e verifica il payload.
• ResourceURL: il percorso del file di schema GraphQL che Apigee utilizza per verificare la richiesta GraphQL."

Per ulteriori informazioni su queste opzioni, consulta la pagina di riferimento dei criteri di GraphaQL.