Política GraphQL

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

Confira a documentação da Apigee Edge.

Ícone da política GraphQL

O quê?

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

Esta é uma política padrão e pode ser implantada em qualquer tipo de ambiente. Nem todos os usuários têm necessidade de saber sobre os tipos de política e 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.

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</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:
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>
Elementos filhos 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>
Elementos filhos 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.

Valor padrão 10
Obrigatório? Opcional
Tipo Inteiro
Elemento pai <GraphQL>
Elementos filhos 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>
Elementos filhos 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>
Elementos filhos 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>
Elementos filhos 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.

Valor padrão request
Obrigatório? Opcional
Tipo String
Elemento pai <GraphQL>
Elementos filhos 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.

Diagrama de consulta do 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)…]

onde:

  • 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
Nome String Nome da operação do graphQL. Esse nome não está relacionado ao nome no fluxo de mensagens.
definition 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 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 Inteiro @include e @skip são as duas diretivas oferecidas atualmente, que podem filtrar com base em valores transmitidos dinamicamente.
selectionSet 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
Nome String Nome do fragmento.
definition 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 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