Política de GraphQL

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

Veja a documentação do Apigee Edge.

O quê

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 obter mais informações, consulte os seguintes recursos:

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

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

Consulte o artigo Usar o GraphQL para ver um exemplo que usa esta política.

Aviso: a validação do conteúdo útil em relação ao esquema é, geralmente, uma operação dispendiosa, e recomendamos que considere cuidadosamente este aspeto ao decidir se deve realizar a validação do esquema. 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.

<GraphQL> elemento

Define uma política de <GraphQL>.

Valor predefinido	Consulte o separador Política predefinida abaixo
Obrigatório?	Obrigatória
Tipo	TIPO
Elemento principal	N/A
Elementos secundários	<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 predefinida

O exemplo seguinte mostra as definições predefinidas quando adiciona uma política <GraphQL> ao seu 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	Predefinição	Obrigatório?	Descrição
name	N/A	Obrigatório	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres. Opcionalmente, use o elemento <DisplayName> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.
continueOnError	falso	Opcional	Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também: As regras de falhas são acionadas APENAS num estado de erro (acerca de continueOnError) Processar falhas no fluxo atual
enabled	verdadeiro	Opcional	Defina como true para aplicar a política. Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça anexada a um fluxo.
async	falso	Descontinuado	Este atributo foi descontinuado.

A tabela seguinte apresenta uma descrição geral dos elementos subordinados de <GraphQL>:

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

Cada um destes elementos secundários é descrito nas secções que se seguem.

Referência de elemento secundário

Esta secção descreve os elementos subordinados de <GraphQL>.

<Action>

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

• parse: o Apigee analisa o payload GraphQL em variáveis de fluxo de mensagens. Consulte Exemplos de representações de variáveis do fluxo de mensagens para uma explicação das variáveis que são definidas quando Action está definido como parse. Isto pode poupar tempo valioso da CPU no backend. Tenha em atenção que verify também analisa o conteúdo útil.
• verify: o Apigee verifica se a carga útil do GraphQL está em conformidade com o esquema carregado para o proxy.
• parse_verify: o Apigee analisa e valida o pedido GraphQL.

Valor predefinido	parse
Obrigatório?	Opcional
Tipo	String
Elemento principal	<GraphQL>
Elementos subordinados	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. 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.

Valor predefinido	10
Obrigatório?	Opcional
Tipo	String
Elemento principal	<GraphQL>
Elementos subordinados	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-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. O valor predefinido é 10.

Nota: MaxDepth funciona quando o elemento Action está definido como parse ou parse-verify. É uma boa prática usar MaxDepth com estas ações para verificar a profundidade em vez de usar a ação verify mais dispendiosa.

Valor predefinido	10
Obrigatório?	Opcional
Tipo	Número inteiro
Elemento principal	<GraphQL>
Elementos subordinados	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 uma carga útil em kilobytes. Pode usar esta opção para limitar o tamanho do payload e evitar problemas de desempenho.

Nota: se MaxPayloadSizeInByte não for fornecido na política, não é aplicada nenhuma restrição de tamanho.

Valor predefinido	request
Obrigatório?	Opcional
Tipo	String
Elemento principal	<GraphQL>
Elementos subordinados	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 pedido que pode ser analisado:

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

Se o âmbito for query e for transmitido um pedido de mutação, o pedido falha e devolve um erro 4xx.

Valor predefinido	query
Obrigatório?	Opcional
Tipo	String
Elemento principal	<GraphQL>
Elementos subordinados	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 ficheiro de esquema GraphQL com o qual a política GraphQL valida os pedidos. Consulte o exemplo para ver um exemplo de carregamento de um esquema GraphQL para o Apigee.

Se o nome do ficheiro de esquema carregado for my-schema.graphql, o elemento <ResourceURL> seria

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

Valor predefinido	N/A
Obrigatório?	Opcional
Tipo	String
Elemento principal	<GraphQL>
Elementos subordinados	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 na qual esta política é executada.

Nota: a origem deve ser a string de consulta graphql não processada, em vez de uma consulta graphql envolvida em JSON.

Valor predefinido	request
Obrigatório?	Opcional
Tipo	String
Elemento principal	<GraphQL>
Elementos subordinados	nenhum

O elemento <Source> usa a seguinte sintaxe:

Sintaxe

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

Analisador GraphQL

O analisador GraphQL suporta todas as funcionalidades de uma consulta GraphQL e representa-a como um gráfico na notação pontilhada do fluxo de mensagens. Uma consulta pode incluir uma definição de operação e, opcionalmente, fragmentos identificados como definições de fragmentos. Consulte a especificação GraphQL.

Anatomia de um pedido GraphQL

O diagrama abaixo mostra a anatomia de um pedido GraphQL.

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

A implementação do analisador abrange todos os aspetos da sintaxe GraphQL, incluindo o suporte para consultas e mutações. Consulte a 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)…]

where:

• graphql: prefixo estático que indica que se trata de variáveis de fluxo de mensagens relacionadas com o GraphQL
• root-Index: índice baseado que indica o índice das definições de consulta ao nível da raiz (por predefinição, até 4 por pedido)
• root-definition: corpo da mensagem de pedido GraphQL de nível raiz, args e respetivos valores
• sub-indices: índices subordinados
• child-definitions: definições ao nível da folha que se correlacionam com campos específicos e os respetivos valores

Representação na variável de fluxo de mensagens das definições de operações

Campos na mensagem	Tipo	Descrição
nome	String	Nome da operação GraphQL. Tenha em atenção que este nome não está relacionado com o nome no fluxo de mensagens.
definição	String – Operação	Indica que este contém o corpo da mensagem principal do pedido de consulta
operationType	consulta ou mutação	O tipo de operação que está a ser realizada.
variableDefinition	Número inteiro	Funcionam tal como as definições de argumentos de uma função numa linguagem escrita. Apresenta todas as variáveis, com o prefixo $, seguidas do respetivo tipo.
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	Agrupamento lógico de um nível de todos os atributos associados a um objeto.

Representação no fluxo de mensagens de definições de fragmentos

Nome da variável do fluxo de mensagens	Tipo	Descrição
nome	String	Nome do fragmento.
definição	String- fragment	Indica que o corpo do pedido é um fragmento do pedido principal.
typeCondition	String	A condição sob a qual o fragmento é invocado.
variableDefinition	Número inteiro	A definição de variáveis transmitida como argumentos ao fragmento.

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

Os exemplos seguintes mostram as representações de variáveis de fluxo de mensagens para payloads de pedidos de exemplo.

Exemplo de consulta 1

Este exemplo mostra uma consulta feita com argumentos transmitidos como entrada, que consulta três atributos para funcionários.

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

A tabela mostra as representações das variáveis de 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

Exemplo de consulta 2

Este exemplo mostra uma consulta feita com argumentos transmitidos como entrada, que consulta os nomes de amigos.

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

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

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'}

Exemplo de consulta 3

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

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

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

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

Tópicos relacionados

Usar o GraphQL