Política de GraphQL

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

Veja a documentação do Apigee Edge.

Ícone de política de GraphQL

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

Para obter mais informações, consulte os seguintes recursos:

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.

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

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.

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.

Diagrama de consulta 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