Usar o GraphQL

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

A política GraphQL pode analisar payloads de pedidos GraphQL em variáveis de fluxo de mensagens, validar o pedido em relação a um esquema GraphQL ou ambos.

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

Pode usar a política de GraphQL para:

• Certifique-se de que as suas APIs apenas processam pedidos em conformidade com o esquema que fornece.
• Imponha restrições ao payload definindo um máximo para o número de fragmentos permitidos.
• Associe o GraphQL a produtos de API.
• Tirar partido das funcionalidades Oauth2, VerifyAPIKey e Quota policy, tal como no REST.

O GraphQL suporta os seguintes tipos de payloads:

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

Nota: para payloads application/json do formulário

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

Atualmente, o Apigee ignora os campos opcionais operationName e variables.

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

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

Exemplo

O exemplo seguinte mostra como carregar um esquema GraphQL para o Apigee e usá-lo para validar pedidos com conteúdo GraphQL.

Atenção: a validação do conteúdo útil em relação ao esquema é, geralmente, uma operação dispendiosa e recomendamos que opte por realizar a validação do esquema com cuidado. As operações de validação de esquemas podem exigir muito da CPU, especialmente quando a carga útil e o esquema são complexos, e podem resultar em latências significativas.

Nota: só pode fornecer um esquema por política. Se precisar de incluir vários esquemas, adicione várias políticas de GraphQL ao seu proxy.

Notas: apenas para o editor de proxy clássico:

• Só pode carregar um ficheiro de esquema GraphQL quando adiciona uma política GraphQL. Não pode carregá-lo no painel Recursos no editor de proxy.
• Depois de carregar um ficheiro de esquema GraphQL, não pode vê-lo nem editá-lo no editor de proxy.

Estas limitações não se aplicam ao novo editor de proxies.

Crie um ficheiro de esquema

Para executar o exemplo, comece por criar um ficheiro 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!
}

Guarde o ficheiro com o nome que quiser usar, seguido da extensão .graphql.

Adicione a política GraphQL na IU do Apigee

Nota: o Apigee vai introduzir uma nova versão do editor de proxies, o que vai facilitar a gestão de proxies.

As instruções nos dois primeiros separadores abaixo explicam como usar o novo editor de proxies ou o editor de proxies clássico.

Novo editor de proxy

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

1. Inicie sessão na IU do Apigee.
2. Na barra de navegação, selecione Desenvolver > Proxies de API.
3. Na lista de proxies, selecione o proxy de API para o qual quer usar a política GraphQL.
4. Clique no separador DESENVOLVER.
5. No painel do lado esquerdo, clique no botão + junto à pasta Políticas.

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

   

   Introduza um Nome a apresentar e um Nome.

   Em seguida, selecione um ficheiro de esquema GraphQL da seguinte forma:

   1. Clique no campo Ficheiro de esquema. São apresentadas as seguintes opções:
      • Sem esquema. Se selecionar esta opção, o Apigee não usa um esquema para validar pedidos.
      • Importe o esquema GraphQL (.graphql)

   2. Selecione Importar esquema GraphQL (.graphql). Apresenta o seguinte:

      

   3. Clique em Escolher ficheiro e selecione o ficheiro de esquema que criou anteriormente (que tem de ter a extensão .graphql). O ficheiro é apresentado no campo Nome do esquema.

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

Agora que criou a política GraphQL, pode anexá-la a um passo no PreFlow:

1. Selecione Proxy Endpoints > default > PreFlow no painel do lado esquerdo:

   

2. Clique no botão + junto a PreFlow no painel Resposta na parte inferior direita do editor visual:

   

3. Na caixa de diálogo Adicionar passo de política, selecione a política GQL-.
   Nota: este exemplo usa o nome predefinido, GQL, para a política GraphQL. Pode alterar o nome no elemento DisplayName no XML da política, adicionando uma expressão descritiva após GQL-. Consulte o artigo Alterar o nome da política.
4. Clique em Adicionar para anexar a política.
5. Clique em Guardar para guardar a revisão atual com as suas alterações.
6. Para implementar as alterações, clique no separador Vista geral e selecione Implementar.

Consulte as opções do GraphQL abaixo para ver as opções que pode definir para a política de GraphQL.

Editor de proxy clássico

1. Inicie sessão na IU do Apigee.
2. Na barra de navegação, selecione Desenvolver > Proxies de API.
3. Na lista de proxies, selecione o proxy de API para o qual quer usar a política GraphQL.
4. Clique no separador DESENVOLVER.

5. No painel Fluxo: PreFlow, clique no botão + Passo.

   

6. No painel Adicionar passo, desloque a página para baixo até à parte inferior da secção Mediação e selecione GraphQL.

   

   O painel Adicionar passo apresenta as seguintes opções:

   • Nome a apresentar: nome a apresentar da política.
   • Nome: nome interno da política.
   • Ficheiro de esquema: opção para carregar um ficheiro que contenha um esquema GraphQL que o Apigee vai usar para validar pedidos com conteúdo GraphQL.

   Para usar um esquema, faça o seguinte:

   1. Clique no campo Ficheiro de esquema. São apresentadas as seguintes opções:
      • Sem esquema. Se selecionar esta opção, o Apigee não usa um esquema para validar pedidos.
      • Importe o esquema GraphQL (.graphql)

   2. Selecione Importar esquema GraphQL (.graphql). Apresenta o seguinte:

      

   3. Clique em Escolher ficheiro e selecione o ficheiro de esquema que criou anteriormente (que tem de ter a extensão .graphql). O ficheiro é apresentado no campo Nome do esquema.

      

7. Clique em Adicionar. O painel Fluxo: PreFlow é agora apresentado conforme indicado abaixo:

   

   Consulte as opções do GraphQL abaixo para ver as opções que pode definir para a política de GraphQL. Para este exemplo, deixe-os como estão.

8. Para implementar o proxy, clique no separador Vista geral e selecione Implementar.

   

Agora, pode testar a política de 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 seu proxy, incluindo o número da revisão mais recente. Quando executa o comando, o Apigee valida o pedido em relação ao esquema e devolve o seguinte resultado.

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

Segue-se outro exemplo de um pedido:

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

Desta vez, a validação do pedido falha com a seguinte mensagem de erro.

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

Opções do 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: ambos query e mutation.
• MaxDepth: a profundidade máxima da consulta, quando representada como uma árvore. MaxDepth permite-lhe bloquear consultas detalhadas no payload, para que o Apigee não precise de criar variáveis de fluxo muito grandes para armazenar os valores. No entanto, a carga útil é enviada tal como está, independentemente do valor de MaxDepth.
• MaxCount: o número máximo de fragmentos que podem estar na carga útil. Pode usar esta opção para impedir que o servidor de back-end GraphQL do cliente execute consultas altamente complexas, o que obriga os clientes a dividir a respetiva lógica em payloads mais pequenos.
• Action: Uma das seguintes ações do GraphQL:
  • parseO Apigee analisa a carga útil do GraphQL nas variáveis de fluxo. Em seguida, pode usar o conteúdo das variáveis de fluxo em políticas como JavaCallout. Tenha em atenção que o parse também valida a carga útil.
  • verify: o Apigee verifica se a carga útil do GraphQL está em conformidade com o esquema carregado para o proxy. Pode usar verify para garantir que não recebe pedidos que não estejam em conformidade com o seu esquema. Isto pode poupar tempo valioso da CPU no back-end.
  • parse_verify: analise e valide a carga útil.
• ResourceURL: O caminho para o ficheiro de esquema GraphQL que o Apigee usa para validar o pedido GraphQL.`

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