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.

Observações: somente para o editor proxy clássico:

• Só é possível fazer upload de um arquivo de esquema do GraphQL ao adicionar uma política do GraphQL. Não é possível fazer isso no painel Recursos do editor de proxies.
• Depois de fazer o upload de um arquivo de esquema do GraphQL, não será possível ver nem modificar o documento no editor.

Essas limitações não são válidas para o novo editor 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

Observação: a Apigee está introduzindo uma nova versão do Editor de Proxy, que facilitará o gerenciamento de proxies.

As instruções nas duas primeiras guias abaixo explicam como usar o novo Editor de proxy ou o Proxy Editor clássico.

Novo Editor de Proxy

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

1. Faça login na IU da Apigee.
2. Na barra de navegação, selecione Develop > API Proxies.
3. Na lista de proxies, selecione o proxy de API em que você quer usar a política GraphQL.
4. Clique na guia DESENVOLVER.
5. No painel à esquerda, clique no botão + ao lado da pasta Políticas.

6. 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.

      
7. 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.

Editor de Proxy clássico

1. Faça login na IU da Apigee.
2. Na barra de navegação, selecione Develop > API Proxies.
3. Na lista de proxies, selecione o proxy de API em que você quer usar a política GraphQL.
4. Clique na guia DESENVOLVER.

5. No painel Fluxo: Pré-fluxo, clique no botão + Etapa.

   

6. No painel Adicionar etapa, role para baixo até o final da seção Mediação e selecione GraphQL.

   

   O painel Adicionar etapa exibe as seguintes opções:

   • Nome de exibição: o nome de exibição da política.
   • Nome: nome interno da política.
   • Arquivo de esquema: opção de fazer upload de um arquivo contendo um esquema GraphQL que a Apigee usará para validar solicitações com conteúdo do GraphQL.

   Para usar um esquema, siga estas etapas:

   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.

      

7. Clique em Adicionar. O painel Fluxo: Pré-fluxo agora aparece como mostrado abaixo:

   

   Consulte as Opções do GraphQL abaixo para ver as opções que podem ser definidas na política GraphQL. Neste exemplo, deixe-as como estão.

8. Para implantar o proxy, clique na guia Visão geral e selecione Implantar.

   

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.