Política GraphQL

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

Confira a documentação da Apigee Edge.

O que

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 saber mais, acesse os recursos a seguir (links em inglês):

• Introdução ao GraphQL
• Consultas e mutações
• Referência de variáveis de fluxo

Esta é uma política padrão e pode ser implantada em qualquer tipo de ambiente. Para informações sobre os tipos de políticas e a disponibilidade de cada tipo de ambiente, consulte Tipos de políticas.

Consulte Como usar GraphQL para ver um exemplo que usa essa política.

Cuidado : verificar o payload em relação ao esquema geralmente é uma operação cara. Recomendamos que você considere isso com cuidado ao decidir se deve executar a validação do esquema. 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.

Elemento <GraphQL>

Define uma política <GraphQL>.

Valor padrão	Consulte a guia Política padrão a seguir
Obrigatório?	Obrigatório
Tipo	TYPE
Elemento pai	n/a
Elementos filhos	<Action> <MaxDepth> <MaxCount> <MaxPayloadSizeInBytes> <OperationType> <Source> <ResourceURL>

Sintaxe

O elemento <GraphQL> usa a seguinte sintaxe:

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Source>request</Source>
  <OperationType>[query|mutuation|all]</OperationType>
  <MaxDepth>MAX_DEPTH</MaxDepth>
  <MaxCount>MAX_NUMBER_OF_QUERIES</MaxCount>
  // [Start maxpayloadsize]
  <MaxPayloadSizeInBytes>MAX_PAYLOAD_SIZE_IN_BYTES&lt/MaxPayloadSizeInBytes>
  <Action>parse</Action>
  <ResourceURL>PATH/TO/SCHEMA.xsd</ResourceURL>
</GraphQL>

Política padrão

O exemplo a seguir mostra as configurações padrão quando você adiciona uma política <GraphQL> ao fluxo na IU do Apigee:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GraphQL name="GraphQLParser">
  <Source>request</Source>
  <OperationType>query</OperationType>
  <MaxDepth>10</MaxDepth>
  <MaxCount>10</MaxCount>
  <MaxPayloadSizeInBytes></MaxPayloadSizeInBytes>
  <Action>parse</Action>
  <ResourceURL></ResourceURL>
</GraphQL>

Este elemento tem os seguintes atributos comuns a todas as políticas:

Atributo	Padrão	Obrigatório?	Descrição
name	N/A	Valor	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.
continueOnError	falso	Opcional	Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado para a maioria das políticas. Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual
enabled	true	Opcional	Defina como true para aplicar a política. Defina como false para desativar a política. A política não será aplicada mesmo que permaneça vinculada a um fluxo.
async	falso	Obsoleto	Esse atributo está obsoleto.

A tabela a seguir fornece uma descrição de alto nível dos elementos filhos de <GraphQL>:

Elemento filho	Obrigatório?	Descrição
Operações comuns
<Action>	Opcional	Especifica a ação a ser realizada para uma solicitação: parse, verify ou parse_verify (ambos).
<MaxCount>	Opcional	O número máximo de consultas ou fragmentos que uma solicitação GraphQL pode gerar. O valor padrão é 10.
<MaxDepth>	Opcional	A profundidade máxima da árvore para a consulta. O valor padrão é 4.
<MaxPayloadSizeInBytes>	Opcional	O tamanho máximo de um payload em kilobytes.
<OperationType>	Obrigatório	Especifica o tipo de solicitação que pode ser analisado: query, mutation ou query_mutation (qualquer um).
<ResourceURL>	Opcional	DESCRIÇÃO. O local do arquivo de esquema do GraphQL.
<Source>	Obrigatório	request

Cada um desses elementos filhos é descrito nas seções a seguir.

Referência a elementos filhos

Esta seção descreve os elementos filhos de <GraphQL>.

<Action>

A ação representa uma das seguintes ações de GraphQL:

• parse: a Apigee analisa o payload GraphQL em variáveis de fluxo de mensagens. Consulte Exemplos de representações de variáveis de fluxo de mensagens para uma explicação sobre as variáveis que são definidas quando Action é definido como parse. Isso pode economizar um tempo de CPU valioso no back-end. Observe que verify também analisa o payload.
• verify: a Apigee verifica se o payload do GraphQL está em conformidade com o esquema enviado ao proxy.
• parse_verify: a Apigee analisa e verifica a solicitação do GraphQL.

Valor padrão	parse
Obrigatório?	Opcional
Tipo	String
Elemento pai	<GraphQL>
Elemento filho	nenhum

O elemento <Action> usa a seguinte sintaxe:

Sintaxe

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Action>parse</Action>
</GraphQL>

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

Valor padrão	10
Obrigatório?	Opcional
Tipo	String
Elemento pai	<GraphQL>
Elemento filho	nenhum

O elemento <MaxCount> usa a seguinte sintaxe:

Sintaxe

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxCount>MAX_NUMBER_OF_QUERIES</MaxCount>
</GraphQL>

<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. O valor padrão é 10.

Observação: MaxDepth funciona quando o elemento Action está definido como parse ou parse-verify. É recomendável usar MaxDepth com essas ações para verificar a profundidade, em vez de usar a ação verify mais cara.

Valor padrão	10
Obrigatório?	Opcional
Tipo	Número inteiro
Elemento pai	<GraphQL>
Elemento filho	nenhum

O elemento <MaxDepth> usa a seguinte sintaxe:

Sintaxe

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxDepth>MAX_DEPTH</MaxDepth>
</GraphQL>

<MaxPayloadSizeInBytes>

O tamanho máximo de um payload em kilobytes. Use-o para limitar o tamanho do payload, para evitar problemas de desempenho.

Observação: se MaxPayloadSizeInByte não for informado na política, nenhuma restrição de tamanho será aplicada.

Valor padrão	request
Obrigatório?	Opcional
Tipo	String
Elemento pai	<GraphQL>
Elemento filho	nenhum

O elemento <MaxPayloadSizeInBytes> usa a seguinte sintaxe:

Sintaxe

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxPayloadSizeInBytes>MAX_PAYLOAD_SIZE_IN_BYTES</MaxPayloadSizeInBytes>
</GraphQL>

<OperationType>

Indica o tipo de solicitação que pode ser analisada:

• query: uma consulta GraphQL.
• mutation: uma mutação GraphQL
• query_mutation: uma consulta ou mutação GraphQL.

Se o escopo for query e uma solicitação de mutação for transmitida, a solicitação falhará e retornará um erro 4xx.

Valor padrão	query
Obrigatório?	Opcional
Tipo	String
Elemento pai	<GraphQL>
Elemento filho	nenhum

O elemento <OperationType> usa a seguinte sintaxe:

Sintaxe

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <OperationType>[query|mutation|query_mutation]</OperationType>
</GraphQL>

<ResourceURL>

O caminho para o arquivo de esquema GraphQL em que a política GraphQL verifica solicitações. Consulte Exemplo para ver como fazer upload de um esquema GraphQL para a Apigee.

Se o nome do arquivo de esquema enviado for my-schema.graphql, o elemento <ResourceURL> será

<ResourceURL>graphql://my-schema.graphql</ResourceURL>

Valor padrão	n/a
Obrigatório?	Opcional
Tipo	String
Elemento pai	<GraphQL>
Elemento filho	nenhum

O elemento ResourceURL usa a seguinte sintaxe:

Sintaxe

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <ResourceURL>PATH/TO/SCHEMA.graphql</ResourceURL>
</GraphQL>

<Source>

Origem em que essa política é executada.

Observação: a origem precisa ser a string de consulta bruta chartql, e não uma consulta Graphql encapsulada em JSON.

Valor padrão	request
Obrigatório?	Opcional
Tipo	String
Elemento pai	<GraphQL>
Elemento filho	nenhum

O elemento <Source> usa a seguinte sintaxe:

Sintaxe

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Source>request</Source>
</GraphQL>

Analisador do GraphQL

O analisador do graphQL é compatível com todos os recursos de uma consulta graphQL e o representa como um gráfico na notação pontilhada de fluxo de mensagens. Uma consulta pode ser composta pela definição da operação e, opcionalmente, por fragmentos identificados como definições de fragmento. Consulte a especificação do GraphQL.

Anatomia de uma solicitação de GraphQL

O diagrama abaixo mostra a anatomia de uma solicitação graphQL.

Representação no fluxo de mensagens da definição da operação

A implementação do analisador abrange todos os aspectos da sintaxe do GraphQL, incluindo suporte para consulta e mutações. Consulte Variável de fluxo de mensagens.

As variáveis do fluxo de mensagens seguem esta convenção:

graphql.(root-index).(root definition)[(sub-indices).(child-definitions)…]

em que:

• graphql: prefixo estático que indica que são variáveis de fluxo de mensagens relacionadas ao graphQL
• root-Index: índice baseado que indica o índice de definições de consulta no nível raiz (padrão até 4 por solicitação)
• root-definition: corpo da mensagem do gráfico GQL de nível raiz, args, valores
• sub-indices: índices filhos
• child-definitions: definições de nível de folha correlacionadas a campos específicos e seus valores

Representação na variável de fluxo de mensagens da definição de operação

Campos na mensagem	Tipo	Descrição
name	String	Nome da operação do graphQL. Esse nome não está relacionado ao nome no fluxo de mensagens.
definição	String - Operação	Indica que ele contém o corpo da mensagem principal da solicitação de consulta
operationType	consulta ou mutação	O tipo de operação que está sendo executada.
variableDefinition	Número inteiro	Funcionam como as definições de argumentos de uma função em uma linguagem tipada. Lista todas as variáveis, com o prefixo $ e o tipo delas.
diretivas	Número inteiro	@include e @skip são as duas diretivas oferecidas atualmente, que podem filtrar com base em valores transmitidos dinamicamente.
selectionSet	Número inteiro	Um agrupamento lógico de nível de todos os atributos associados a um objeto.

Representação no fluxo de mensagens das definições de fragmento

Nome da variável do fluxo de mensagens	Tipo	Descrição
name	String	Nome do fragmento.
definição	String - fragmento	Indica que o corpo da solicitação é um fragmento da solicitação principal.
typeCondition	String	A condição em que o fragmento é invocado.
variableDefinition	Número inteiro	A definição das variáveis transmitidas como argumentos para o fragmento.

Exemplos de representações de variáveis de fluxo de mensagens

Os exemplos a seguir mostram as representações de variáveis do fluxo de mensagens para payloads de solicitação de amostra.

Amostra de consulta 1

Neste exemplo, mostramos uma consulta feita com argumentos passados como entrada, que consultam três atributos para funcionários.

{
 employee(id: 123) {
   id
   firstName
   lastName
 }
}

A tabela mostra as representações de variáveis do fluxo de mensagens correspondentes.

Variável de fluxo de mensagens	Valor
graphql.operation.operationType	QUERY
graphql.fragment.count	1
graphql.operation.selectionSet.count	1
graphql.operation.variableDefinitions.count	0
graphql.operation.selectionSet.1.name	employee
graphql.operation.selectionSet.1.argument.count	1
graphql.operation.selectionSet.1.argument.1.name	id
graphql.operation.selectionSet.1.argument.1.value	IntValue{value=123}
graphql.operation.selectionSet.1.directive.count	0
graphql.operation.selectionSet.1.selectionSet.count	3
graphql.operation.selectionSet.1.selectionSet.1.name	id
graphql.operation.selectionSet.1.selectionSet.2.name	firstName
graphql.operation.selectionSet.1.selectionSet.3.name	lastName

Amostra de consulta 2

Neste exemplo, mostramos uma consulta feita com argumentos passados como entrada, que consultam os nomes dos amigos.

query Characters($episode: Episode, $withFriends: Boolean!) {
   friends @include(if: $withFriends) {
     friendsName
    }
}

A tabela abaixo mostra as representações correspondentes da variável de fluxo de mensagens.

Variável de fluxo de mensagens	Valor
graphql.operation.operationType	QUERY
graphql.operation.selectionSet.count	1
graphql.operation.name	Characters
graphql.fragment.count	0
graphql.operation.selectionSet.1.name	friends
graphql.operation.variableDefinitions.count	2
graphql.operation.variableDefinitions.1.name	episode
graphql.operation.variableDefinitions.1.type	TypeName{name='Episode'}
graphql.operation.variableDefinitions.2.name	withFriends
graphql.operation.variableDefinitions.2.type	NonNullType{type=TypeName{name='Boolean'}}
graphql.operation.selectionSet.1.argument.count	0
graphql.operation.selectionSet.1.selectionSet.count	1
graphql.operation.selectionSet.1.selectionSet.1.name	friendsName
graphql.operation.selectionSet.1.directive.count	1
graphql.operation.selectionSet.1.directive.1.argument.1.name	if
graphql.operation.selectionSet.1.directive.1.argument.1.value	VariableReference{name='withFriends'}

Amostra de consulta 3

Este exemplo tem uma definição de variável com alias.

query getUsers {
  admins: users(role: ADMIN) {
    lastName
  }
  accountants: users(role: ACCOUNTANT) {
    firstName
  }
}

A tabela abaixo mostra as representações correspondentes da variável de fluxo de mensagens.

Variável de fluxo de mensagens	Valor
graphql.operation.operationType	QUERY
graphql.operation.selectionSet.count	2
graphql.operation.selectionSet.1.name	users
graphql.operation.selectionSet.1.alias	admins
graphql.operation.variableDefinitions.count	0
graphql.operation.selectionSet.1.argument.count	1
graphql.operation.selectionSet.1.argument.1.name	role
graphql.operation.selectionSet.1.argument.1.value	EnumValue{name='ADMIN'}
graphql.operation.selectionSet.1.argument.2.name	null
graphql.operation.selectionSet.1.argument.2.value	null
graphql.operation.selectionSet.1.selectionSet.count	1
graphql.operation.selectionSet.1.selectionSet.count	1
graphql.operation.selectionSet.1.selectionSet.1.name	lastName
graphql.operation.selectionSet.1.selectionSet.1.alias	null
graphql.operation.selectionSet.1.selectionSet.2.name	null
graphql.operation.selectionSet.1.selectionSet.2.alias	null
graphql.operation.selectionSet.1.directive.count	0
graphql.operation.selectionSet.1.directive.1.argument.1.name	null
graphql.operation.selectionSet.1.directive.1.argument.1.value	null
graphql.operation.selectionSet.2.name	users
graphql.operation.selectionSet.2.alias	accountants
graphql.operation.selectionSet.2.argument.count	1
graphql.operation.selectionSet.2.argument.1.name	role
graphql.operation.selectionSet.2.argument.1.value	EnumValue{name='ACCOUNTANT'}
graphql.operation.selectionSet.2.selectionSet.count	1
graphql.operation.selectionSet.2.selectionSet.1.name	firstName
graphql.operation.selectionSet.2.directive.count	0
graphql.operation.selectionSet.2.selectionSet.1.alias	null
graphql.operation.selectionSet.2.selectionSet.2.name	null
graphql.operation.selectionSet.2.selectionSet.2.alias	null
graphql.operation.selectionSet.2.directive.count	0

Temas relacionados

Como usar o GraphQL