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:
- Faça login na IU da Apigee.
- Na barra de navegação, selecione Develop > API Proxies.
- Na lista de proxies, selecione o proxy de API em que você quer usar a política GraphQL.
- Clique na guia DESENVOLVER.
- No painel à esquerda, clique no botão + ao lado da pasta +.
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:
- 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)
Selecione Importar esquema do GraphQL (.graphql). Com isso, você verá os campos a seguir:
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.
- Clique no campo Arquivo de esquema. Com isso, as seguintes opções serão exibidas:
- 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:
- Selecione Endpoints de Proxy > padrão > Pré-fluxo no painel à esquerda:
- Clique no botão + ao lado de PreFlow no painel PreFlow no canto inferior direito do Editor de recursos visuais:
- Na caixa de diálogo Adicionar etapa de política, selecione a política GQL-.
- Clique em Adicionar para anexar a política.
- Clique em Salvar para salvar a revisão atual com as alterações.
- 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
- Faça login na IU da Apigee.
- Na barra de navegação, selecione Develop > API Proxies.
- Na lista de proxies, selecione o proxy de API em que você quer usar a política GraphQL.
- Clique na guia DESENVOLVER.
No painel Fluxo: Pré-fluxo, clique no botão + Etapa.
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:
- 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)
Selecione Importar esquema do GraphQL (.graphql). Com isso, você verá os campos a seguir:
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.
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.
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 RESTGET
.mutation
: o equivalente em GraphQL da operação RESTPUT
.query_mutation
:query
emutation
.
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 deMaxDepth
.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 queparse
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 usarverify
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.