Política GraphQL

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

Confira a documentação da Apigee Edge.

O que

The GraphQL policy can parse GraphQL payloads into message flow variables, verify GraphQL requests against a schema, or both.

You can use the GraphQL policy to:

• Ensure that your APIs only process requests that conform to the schema you provide.
• Impose restrictions on the payload by setting a maximum on the number of fragments allowed.
• Associate GraphQL with API products.
• Leverage the Oauth2, VerifyAPIKey, and Quota policy features, just as in REST.

GraphQL supports the following types of payloads:

• POST of graphQL payloads with Content-Type : application/graphql
• POST of graphQL payloads with Content-Type: applcation/json
• GET of graphQL payloads where the payload is a query parameter

Note: For application/json payloads of the form

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

Apigee currently ignores the optional operationName and variables fields.

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

This element has the following attributes that are common to all policies:

Attribute	Default	Required?	Description
name	N/A	Required	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError	false	Optional	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow
enabled	true	Optional	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async	false	Deprecated	This attribute is deprecated.

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