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

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.

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

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

    Caixa de diálogo Criar política do 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:

      Escolha um arquivo de esquema.

    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.

      Esquema selecionado.
  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:

    Os endpoints de destino do Pré-fluxo são selecionados no explorador de Proxy.

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

    Clique no botão "+" ao lado de "PreFlow" no painel "Response".

  3. Na caixa de diálogo Adicionar etapa de política, selecione a política GQL-.
  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 DEVELOP.

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

    Botão de adição de etapa.

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

    Adicione a política 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:

      Escolha um arquivo de esquema.

    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.

      Esquema selecionado.

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

    Painel Pré-fluxo com a política GraphQL.

    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.

    Painel Pré-fluxo com a 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.