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
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</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 Opcionalmente, use o elemento |
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 quandoAction
está definido comoparse
. Isto pode poupar tempo valioso da CPU no backend. Tenha em atenção queverify
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 GraphQLquery_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.

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 GraphQLroot-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 valoressub-indices
: índices subordinadoschild-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 |