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

GraphQL 政策可以将 GraphQL 载荷解析为消息流变量，并且/或者针对架构验证 GraphQL 请求。

您可以使用 GraphQL 政策执行以下操作：

• 确保您的 API 仅处理符合您提供的架构的请求。
• 通过设置允许的片段数量上限来限制载荷。
• 将 GraphQL 与 API 产品相关联。
• 就像在 REST 中一样，利用 Oauth2、VerifyAPIKey 和配额政策功能。

GraphQL 支持以下类型的载荷：

• 符合 Content-Type : application/graphql 的 graphQL 载荷的 POST
• 符合 Content-Type: applcation/json 的 graphQL 载荷的 POST
• GraphQL 载荷的 GET，其中载荷是查询参数

注意：对于以下格式的 application/json 载荷

{
"query": "...",
"operationName": "...",
"variables": { "myVariable": "someValue", ... }
}

Apigee 目前会忽略可选的 operationName 和 variables 字段。

Per un rapido riepilogo delle opzioni per la policy GraphQL, consulta la sezione Opzioni GraphQL di seguito.

Per saperne di più su GraphQL, visita GraphQL.org.

Esempio

Il seguente esempio 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 è in genere un'operazione costosa e ti consigliamo di scegliere di eseguire la convalida dello schema con attenzione. Le operazioni di convalida dello schema possono richiedere un utilizzo elevato della CPU, soprattutto quando il payload e lo schema sono complessi e possono comportare latenze significative.

Nota:puoi fornire un solo schema per norma. Se devi includere più schemi, aggiungi più policy GraphQL al proxy.

Crea un file di schema

Per eseguire l'esempio, crea innanzitutto un file di 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 Apigee

Innanzitutto, crea la policy GraphQL come segue:

1. Nell'interfaccia utente Apigee, vai alla pagina Sviluppo proxy > Proxy API.

   Vai a Proxy API

2. Nell'elenco dei proxy, seleziona il proxy API per il quale vuoi utilizzare il criterio GraphQL.
3. Fai clic sulla scheda Sviluppa.
4. Nel riquadro a sinistra, fai clic sul pulsante + accanto alla cartella Policy.

5. Nella finestra di dialogo Crea policy, fai clic sul campo Seleziona tipo di policy e scorri verso il basso fino a Mediazione e seleziona GraphQL.

   

   Inserisci un Nome visualizzato e un Nome.

   Successivamente, seleziona un file schema GraphQL come segue:

   1. Fai clic sul campo File 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). Vengono visualizzate le seguenti informazioni:

      

   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.

      
6. Fai clic su Crea per creare la policy.

Ora che hai creato la policy GraphQL, puoi collegarla a un passaggio nel PreFlow:

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

   

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

   

3. Nella finestra di dialogo Aggiungi passaggio policy, seleziona la policy GQL-.
   Nota: questo esempio utilizza il nome predefinito GQL per il criterio GraphQL. Puoi modificare il nome nell'elemento DisplayName nel file XML per la policy, aggiungendo una frase descrittiva dopo GQL-. Consulta Modificare il nome della policy.
4. Fai clic su Aggiungi per allegare la policy.
5. Fai clic su Salva per salvare la revisione corrente con le modifiche.
6. Per implementare le modifiche, fai clic sulla scheda Panoramica e seleziona Implementa.

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

Ora puoi testare la policy 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 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, 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.
• MaxCount: il numero massimo di frammenti che possono essere nel payload. Puoi utilizzare questa funzionalità 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 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 nel proxy. Puoi utilizzare verify per assicurarti di non ricevere richieste non conformi al tuo 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 che Apigee utilizza per verificare la richiesta GraphQL.

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