Esta página se aplica à Apigee e à Apigee híbrida.
Confira a documentação da Apigee Edge.
O que
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 Opcionalmente, use o elemento |
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 quandoAction
é definido comoparse
. Isso pode economizar um tempo de CPU valioso no back-end. Observe queverify
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.
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 GraphQLquery_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.
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 graphQLroot-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, valoressub-indices
: índices filhoschild-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 |