Política GraphQL

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Qué

The GraphQL policy can parse GraphQL payloads into message flow variables, verify GraphQL requests against a schema, or both.

You can use the GraphQL policy to:

• Ensure that your APIs only process requests that conform to the schema you provide.
• Impose restrictions on the payload by setting a maximum on the number of fragments allowed.
• Associate GraphQL with API products.
• Leverage the Oauth2, VerifyAPIKey, and Quota policy features, just as in REST.

GraphQL supports the following types of payloads:

• POST of graphQL payloads with Content-Type : application/graphql
• POST of graphQL payloads with Content-Type: applcation/json
• GET of graphQL payloads where the payload is a query parameter

Note: For application/json payloads of the form

{
"query": "...",
"operationName": "...",
"variables": { "myVariable": "someValue", ... }
}

Apigee currently ignores the optional operationName and variables fields.

Para obtener más información, consulta los siguientes recursos:

• Introducción a GraphQL
• Consultas y mutaciones
• Referencia de las variables de flujo

Esta es una política estándar y se puede implementar en cualquier tipo de entorno. Para obtener información sobre los tipos de políticas y la disponibilidad con cada tipo de entorno, consulta Tipos de políticas.

Consulta Usa GraphQL para ver un ejemplo que usa esta política.

Precaución: Verificar la carga útil en el esquema suele ser una operación costosa, por lo que te recomendamos que consideres con cuidado decidir si debes realizar la validación del esquema. Las operaciones de validación de esquema pueden consumir mucha CPU, en especial cuando la carga útil y el esquema son complejos, y pueden generar latencias significativas.

Nota: Solo puedes proporcionar un esquema por política. Si necesitas incluir varios esquemas, agrega varias políticas de GraphQL a tu proxy.

Elemento <GraphQL>

Define una política <GraphQL>.

Valor predeterminado	Consulta la pestaña Política predeterminada, a continuación
¿Es obligatorio?	Obligatorio
Tipo	TYPE
Elemento principal	n/a
Elementos secundarios	<Action> <MaxDepth> <MaxCount> <MaxPayloadSizeInBytes> <OperationType> <Source> <ResourceURL>

Sintaxis

El elemento <GraphQL> usa la siguiente sintaxis:

<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 predeterminada

En el siguiente ejemplo, se muestra la configuración predeterminada cuando agregas una política de <GraphQL> a tu flujo en la IU de 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 tiene los siguientes atributos que son comunes a todas las políticas:

Atributo	Predeterminada	(obligatorio)	Descripción
name	N/A	Obligatorio	El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres. De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.
continueOnError	falso	Opcional	Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle. También consulta: Las reglas de fallas se activan SOLAMENTE en un estado de error (sobre el continueOnError) Controla fallas dentro del flujo actual
enabled	true	Opcional	Configúralo como true para aplicar la política. Configúralo como false para desactivar la política. La política no se aplicará, incluso si permanece conectada a un flujo.
async	falso	Obsoleta	Este atributo dejó de estar disponible.

En la siguiente tabla, se proporciona una descripción de alto nivel de los elementos secundarios de <GraphQL>.

Elemento secundario	¿Es obligatorio?	Descripción
Operaciones comunes
<Action>	Opcional	Especifica la acción que se debe realizar para una solicitud: parse, verify o parse_verify (ambas).
<MaxCount>	Opcional	La cantidad máxima de consultas o fragmentos que puede generar una solicitud de GraphQL. El valor predeterminado es 10.
<MaxDepth>	Opcional	La profundidad máxima del árbol para la consulta. El valor predeterminado es 4.
<MaxPayloadSizeInBytes>	Opcional	El tamaño máximo de una carga útil en kilobytes.
<OperationType>	Obligatorio	Especifica el tipo de solicitud que se puede analizar: query, mutation o query_mutation (cualquiera de las dos).
<ResourceURL>	Opcional	DESCRIPCIÓN. La ubicación del archivo de esquema de GraphQL.
<Source>	Obligatorio	request

Cada uno de estos elementos secundarios se describe en las siguientes secciones.

Referencia del elemento secundario

En esta sección, se describen los elementos secundarios de <GraphQL>.

<Action>

Acción representa una de las siguientes acciones de GraphQL:

• parse: Apigee analiza la carga útil de GraphQL en variables de flujo de mensajes. Consulta Ejemplos de representaciones de variables de flujo de mensajes para obtener una explicación de las variables que se establecen cuando Action se establece en parse. Esto puede ahorrar tiempo de CPU valioso en el backend. Ten en cuenta que verify también analiza la carga útil.
• verify: Apigee verifica que la carga útil de GraphQL cumpla con el esquema subido al proxy.
• parse_verify: Apigee analiza y verifica la solicitud de GraphQL.

Valor predeterminado	parse
¿Es obligatorio?	Opcional
Tipo	String
Elemento principal	<GraphQL>
Elementos secundarios	ninguno

El elemento <Action> usa la siguiente sintaxis:

Sintaxis

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Action>parse</Action>
</GraphQL>

<MaxCount>

La cantidad máxima de fragmentos que pueden estar en la carga útil. Puedes usar esto para evitar que el servidor de backend de GraphQL del cliente ejecute consultas muy complejas que obligue a los clientes a dividir su lógica en cargas útiles más pequeñas.

Valor predeterminado	10
¿Es obligatorio?	Opcional
Tipo	String
Elemento principal	<GraphQL>
Elementos secundarios	ninguno

El elemento <MaxCount> usa la siguiente sintaxis:

Sintaxis

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxCount>MAX_NUMBER_OF_QUERIES</MaxCount>
</GraphQL>

<MaxDepth>

La profundidad máxima de la consulta, cuando se representa como un árbol. MaxDepth te permite bloquear consultas profundas en la carga útil, de modo que Apigee no necesite crear variables de flujo muy grandes para contener los valores. Sin embargo, la carga útil se envía tal y como está, sin importar el valor de MaxDepth. El valor predeterminado es 10.

Nota: MaxDepth funciona cuando el elemento Action se establece como parse o parse-verify. Se recomienda usar MaxDepth con estas acciones para verificar la profundidad, en lugar de usar la acción verify más costosa.

Valor predeterminado	10
¿Es obligatorio?	Opcional
Tipo	Entero
Elemento principal	<GraphQL>
Elementos secundarios	ninguno

El elemento <MaxDepth> usa la siguiente sintaxis:

Sintaxis

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxDepth>MAX_DEPTH</MaxDepth>
</GraphQL>

<MaxPayloadSizeInBytes>

El tamaño máximo de una carga útil en kilobytes. Puedes usar esto para limitar el tamaño de la carga útil, a fin de evitar problemas de rendimiento.

Nota: Si no se proporciona MaxPayloadSizeInByte en la política, no se aplica ninguna restricción de tamaño.

Valor predeterminado	request
¿Es obligatorio?	Opcional
Tipo	String
Elemento principal	<GraphQL>
Elementos secundarios	ninguno

El elemento <MaxPayloadSizeInBytes> usa la siguiente sintaxis:

Sintaxis

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxPayloadSizeInBytes>MAX_PAYLOAD_SIZE_IN_BYTES</MaxPayloadSizeInBytes>
</GraphQL>

<OperationType>

Indica el tipo de solicitud que se puede analizar:

• query: Una consulta de GraphQL.
• mutation: Una mutación de GraphQL
• query_mutation: Una consulta de GraphQL o una mutación.

Si el alcance es query y se pasa una solicitud de mutación, la solicitud falla y muestra un error 4xx.

Valor predeterminado	query
¿Es obligatorio?	Opcional
Tipo	String
Elemento principal	<GraphQL>
Elementos secundarios	ninguno

El elemento <OperationType> usa la siguiente sintaxis:

Sintaxis

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <OperationType>[query|mutation|query_mutation]</OperationType>
</GraphQL>

<ResourceURL>

La ruta al archivo del esquema GraphQL con el que la política de GraphQL verifica las solicitudes. Consulta Ejemplo para ver un ejemplo de cómo subir un esquema de GraphQL a Apigee.

Si el nombre de tu archivo de esquema subido es my-schema.graphql, el elemento <ResourceURL> sería

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

Valor predeterminado	n/a
¿Es obligatorio?	Opcional
Tipo	String
Elemento principal	<GraphQL>
Elementos secundarios	ninguno

El elemento ResourceURL usa la siguiente sintaxis:

Sintaxis

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <ResourceURL>PATH/TO/SCHEMA.graphql</ResourceURL>
</GraphQL>

<Source>

Es la fuente en la que se ejecuta esta política.

Nota: La fuente debe ser la string de consulta graphql sin procesar, en lugar de una consulta de graphql unida en JSON.

Valor predeterminado	request
¿Es obligatorio?	Opcional
Tipo	String
Elemento principal	<GraphQL>
Elementos secundarios	ninguno

El elemento <Source> usa la siguiente sintaxis:

Sintaxis

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

Analizador de GraphQL

El analizador de graphQL admite todas las características de una consulta de graphQL y la representa como un gráfico en la notación de puntos del flujo de mensajes. Una consulta puede contener la definición de operación y, de forma opcional, fragmentos identificados como definiciones de fragmentos. Consulta la especificación de GraphQL.

Anatomía de una solicitud graphQL

En el siguiente diagrama, se muestra la anatomía de una solicitud graphQL.

Representación en el flujo de mensajes de definición de operación

La implementación del analizador abarca todos los aspectos de la sintaxis de GraphQL, incluida la compatibilidad con consultas y mutaciones. Consulta Variable de flujo de mensajes.

Las variables de flujo de mensajes siguen esta convención:

graphql.(root-index).(root definition)[(sub-indices).(child-definitions)…]

donde:

• graphql: Prefijo estático que indica que hay variables de flujo de mensajes relacionadas con GraphQL
• root-Index: Índice basado que indica el índice de definiciones de consulta de nivel raíz (el valor predeterminado es hasta 4 por solicitud)
• root-definition: Cuerpo de mensaje de solicitud de graphQL a nivel raíz, argumentos y sus valores
• sub-indices: Índices secundarios
• child-definitions: Definiciones de nivel de hoja que se correlacionan con campos específicos y sus valores

Representación en la variable de flujo de mensajes de definición de operación

Campos del mensaje	Tipo	Descripción
nombre	String	Nombre de la operación graphQL. Ten en cuenta que este nombre no está relacionado con el nombre del flujo de mensajes.
definición	String - Operación	Indica que contiene el cuerpo principal del mensaje de la solicitud de consulta.
operationType	consulta o mutación	El tipo de operación que se realiza.
variableDefinition	Entero	Funciona como las definiciones de argumentos para una función en un lenguaje escrito. Enumera todas las variables, con el prefijo $, seguidas de su tipo.
directivas	Entero	@include y @skip son las dos directivas que se ofrecen en la actualidad, que pueden filtrar según los valores que se pasan de forma dinámica.
selectionSet	Entero	Una agrupación lógica de un nivel de todos los atributos asociados con un objeto.

Representación en el flujo de mensajes de la definición de fragmento

Nombre de la variable del flujo de mensajes	Tipo	Descripción
nombre	String	Nombre del fragmento.
definición	String - fragmento	Indica que el cuerpo de la solicitud es un fragmento de la solicitud principal.
typeCondition	String	La condición en la que se invoca el fragmento.
variableDefinition	Entero	La definición de variables que se pasan como argumentos al fragmento.

Ejemplos de representaciones de variables de flujo de mensajes

En los siguientes ejemplos, se muestran las representaciones de variables de flujo de mensajes para las cargas útiles de solicitud de muestra.

Consulta de muestra 1

Este ejemplo muestra una consulta realizada con argumentos pasados como entrada, que consultan tres atributos para empleados.

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

En la tabla, se muestran las representaciones de variables de flujo de mensaje correspondientes.

Variable de flujo de mensajes	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

Consulta de muestra 2

Este ejemplo muestra una consulta realizada con argumentos pasados como entrada, que consultan los nombres de amigos.

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

En la siguiente tabla, se muestran las representaciones de variables de flujo de mensaje correspondientes.

Variable de flujo de mensajes	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'}

Consulta de muestra 3

En este ejemplo, hay una definición de variable con alias.

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

En la siguiente tabla, se muestran las representaciones de variables de flujo de mensaje correspondientes.

Variable de flujo de mensajes	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

Usa GraphQL