Como usar o GraphQL

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

A política GraphQL pode analisar payloads de solicitação do GraphQL em variáveis de fluxo de mensagens, verificar a solicitação em um esquema do GraphQL ou ambos.

A política GraphQL pode analisar payloads do GraphQL em variáveis de fluxo de mensagens, verificar as solicitações do GraphQL em relação a um esquema ou ambos.

Use a política GraphQL para:

• Garanta que as APIs só processem solicitações em conformidade com o esquema fornecido.
• Impor restrições no payload definindo um máximo no número de fragmentos permitidos.
• Associar o GraphQL aos produtos de API.
• Aproveitar os recursos das políticas Oauth2, VerifyAPIKey e Quota, assim como em REST.

O GraphQL é compatível com os seguintes tipos de payloads:

• POST de payloads do GraphQL com Content-Type : application/graphql
• POST de payloads do GraphQL com Content-Type: applcation/json
• GET de payloads do GraphQL em que o payload é um parâmetro de consulta

Observação: para payloads de application/json do formulário.

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

No momento, a Apigee ignora os campos opcionais operationName e variables.

Para um resumo rápido das opções da política GraphQL, consulte as opções do GraphQL abaixo.

Para saber mais sobre o GraphQL, consulte GraphQL.org.

Exemplo

No exemplo a seguir, mostramos como fazer upload de um esquema GraphQL na Apigee e usá-lo para validar solicitações com conteúdo GraphQL.

Cuidado: a verificação do payload em relação ao esquema geralmente é uma operação cara, e recomendamos que você realize a validação de esquema com cuidado. As operações de validação de esquema podem consumir muita CPU, especialmente quando o payload e o esquema são complexos e podem resultar em latências significativas.

Observação: só é possível fornecer um esquema por política. Se você precisar incluir vários esquemas, adicione várias políticas do GraphQL ao proxy.

Criar um arquivo de esquema

Para executar o exemplo, primeiro crie um arquivo de esquema GraphQL com o seguinte conteúdo:

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!
}

Salve o arquivo com o nome que você quer usar, seguido pela extensão .graphql.

Adicionar a política GraphQL na interface da Apigee

Primeiro, crie a política GraphQL da seguinte maneira:

1. Na interface da Apigee, acesse a página Desenvolvimento de proxy > Proxies de API.

   Acessar proxies de API

2. Na lista de proxies, selecione o proxy de API em que você quer usar a política GraphQL.
3. Clique na guia Desenvolver.
4. No painel à esquerda, clique no botão + ao lado da pasta Políticas.

5. Na caixa de diálogo Criar política, clique no campo Selecionar tipo de política, role para baixo até Mediação e selecione GraphQL.

   

   Insira um Nome de exibição e um Nome.

   Em seguida, selecione um arquivo de esquema GraphQL da seguinte maneira:

   1. Clique no campo Arquivo de esquema. Com isso, as seguintes opções serão exibidas:
      • Nenhum esquema. Se você selecionar essa opção, a Apigee não usará um esquema para validar solicitações.
      • Importar esquema do GraphQL (.graphql)

   2. Selecione Importar esquema do GraphQL (.graphql). Com isso, você verá os campos a seguir:

      

   3. Clique em Escolher arquivo e selecione o arquivo de esquema criado anteriormente (que precisa ter a extensão .graphql). O arquivo aparece no campo Nome do esquema.

      
6. Clique em Criar para criar a política.

Agora que você criou a política GraphQL, pode anexá-la a uma etapa no Pré-fluxo:

1. Selecione Endpoints de Proxy > padrão > Pré-fluxo no painel à esquerda:

   

2. Clique no botão + ao lado de PreFlow no painel Response no canto inferior direito do Editor de recursos visuais:

   

3. Na caixa de diálogo Adicionar etapa de política, selecione a política GQL.
   Observação: este exemplo usa o nome padrão, GQL, para a política GraphQL. Você pode alterar o nome no elemento DisplayName no XML para a política, adicionando uma frase descritiva após GQL:. Consulte Alterar o nome da política.
4. Clique em Adicionar para anexar a política.
5. Clique em Salvar para salvar a revisão atual com as alterações.
6. Para implantar as alterações, clique na guia Visão geral e selecione Implantar.

Consulte as Opções do GraphQL abaixo para ver as opções que podem ser definidas na política GraphQL.

Agora você pode testar a política GraphQL com o seguinte comando curl:

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

Em que PROXY_BASEPATH é o caminho base do proxy e HOST_NAME é o nome do proxy, incluindo o número de revisão mais recente. Quando você executa o comando, a Apigee valida a solicitação em relação ao esquema e retorna a saída a seguir.

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

Veja outro exemplo de uma solicitação:

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

Desta vez, a validação da solicitação falha com a seguinte mensagem de erro:

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

Opções de GraphQL

A GraphPolicy tem as seguintes opções:

• OperationType: o tipo de operação. As opções são:
  • query: o equivalente em GraphQL da operação REST GET.
  • mutation: o equivalente em GraphQL da operação REST PUT.
  • query_mutation: query e mutation.
• MaxDepth: a profundidade máxima da consulta, quando representada como uma árvore. MaxDepth permite bloquear consultas profundas no payload, para que a Apigee não precise criar variáveis de fluxo muito grandes para armazenar os valores. No entanto, o payload é enviado como está, independentemente do valor de MaxDepth.
• MaxCount: o número máximo de fragmentos que podem estar no payload. É possível usar isso para evitar que o servidor de back-end GraphQL do cliente execute consultas altamente complexas, forçando os clientes a dividir a lógica em payloads menores.
• Action: uma das seguintes ações do GraphQL:
  • parse: a Apigee analisa o payload GraphQL em variáveis de fluxo de mensagens. Em seguida, use o conteúdo das variáveis de fluxo em políticas como JavaCallout. Observe que parse também verifica o payload.
  • verify: a Apigee verifica se o payload do GraphQL está em conformidade com o esquema enviado ao proxy. É possível usar verify para garantir que você não receba solicitações que não estejam em conformidade com o esquema. Isso pode economizar um tempo de CPU valioso no back-end.
  • parse_verify: analisa e verifica o payload.
• ResourceURL: o caminho para o arquivo de esquema do GraphQL usado pela Apigee para verificar a solicitação do GraphQL.

Para saber mais sobre essas opções, consulte a página de referência da política GraphQL.