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 delle richieste GraphQL in variabili di flusso di messaggi, verificare la richiesta rispetto a uno schema GraphQL o entrambe le cose.

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

Per scoprire di più 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.

Creare un file di schema

Per eseguire l'esempio, crea prima un file dello schema GraphQL con i seguenti contenuti:

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 nell'interfaccia utente di Apigee

Nuovo editor proxy

Innanzitutto, crea il criterio GraphQL come segue:

  1. Accedi all'interfaccia utente di Apigee.
  2. Nella barra di navigazione, seleziona Sviluppa > Proxy API.
  3. Nell'elenco dei proxy, seleziona il proxy API per cui vuoi utilizzare il criterio GraphQL.
  4. Fai clic sulla scheda SVILUPPA.
  5. Nel riquadro a sinistra, fai clic sul pulsante + accanto alla cartella Criteri.
  6. Nella finestra di dialogo Crea criterio, fai clic nel campo Seleziona il tipo di criterio, scorri verso il basso fino a Mediazione e seleziona GraphQL.

    Finestra di dialogo Crea criterio GraphQL.

    Inserisci un Nome visualizzato e un Nome.

    Quindi, seleziona un file schema GraphQL come segue:

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

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

      Schema selezionato.
  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 proxy > predefinito > PreFlow nel riquadro di sinistra:

    Endpoint di destinazione per PreFlow selezionati in Esplora proxy.

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

    Fai clic sul pulsante + accanto a PreFlow nel riquadro Risposta.

  3. Nella finestra di dialogo Passaggio Aggiungi criterio, seleziona il criterio GQL-.
  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 la sezione Opzioni 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 Sviluppa > Proxy API.
  3. Nell'elenco dei proxy, seleziona il proxy API per cui vuoi utilizzare il criterio GraphQL.
  4. Fai clic sulla scheda SVILUPPA.
  5. Nel riquadro Flusso: PreFlow, fai clic sul pulsante + Passaggio.

    Pulsante Passaggio successivo.
  6. Nel riquadro Aggiungi passaggio, scorri verso il basso fino alla fine della sezione Mediazione e seleziona GraphQL.

    Aggiungi il criterio GraphQL.

    Il riquadro Aggiungi passaggio mostra le seguenti opzioni:

    • Nome visualizzato: il nome visualizzato della policy.
    • Nome: il nome interno del criterio.
    • File schema: opzione per 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 schema. Vengono visualizzate le seguenti opzioni:
      • Nessun schema. Se selezioni questa opzione, Apigee non utilizzerà uno schema per convalidare le richieste.
      • Importa schema GraphQL (.graphql)
    2. Seleziona Importa schema GraphQL (.graphql). Verranno visualizzate le seguenti informazioni:

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

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

    Riquadro PreFlow con il criterio GraphQL.

    Consulta la sezione Opzioni 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.

    Riquadro PreFlow con il criterio GraphQL.

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 della revisione più recente. Quando esegui il comando, Apigee convalida la richiesta in base allo schema e restituisce il seguente output.

{
  "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 la convalida della richiesta non va a buon fine e viene visualizzato il seguente messaggio di errore.

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

Opzioni GraphQL

GraphPolicy ha 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: sia query che mutation.
  • 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.
  • 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.
  • Action: una delle seguenti azioni GraphQL:
    • parseApigee analizza il payload GraphQL nelle variabili del 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. In questo modo puoi risparmiare tempo prezioso della CPU nel backend.
    • parse_verify: analizza e verifica il payload.
  • ResourceURL: il percorso del file dello schema GraphQL utilizzato da Apigee per verificare la richiesta GraphQL.`

Per scoprire di più su queste opzioni, consulta la pagina di riferimento delle norme GraphQL.