Política GraphQL

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

Consulta la documentación de Apigee Edge.

Ícono de la política de GraphQL

Qué

La política de GraphQL puede analizar cargas útiles de GraphQL en variables de flujo de mensajes, verificar solicitudes de GraphQL en un esquema o ambas.

Puedes usar la política de GraphQL para lo siguiente:

  • Asegúrate de que tus API solo procesen solicitudes que se ajusten al esquema que proporciones.
  • Para imponer restricciones en la carga útil estableciendo un máximo en la cantidad de fragmentos permitidos.
  • Para asociar graphQL con productos de API.
  • Para aprovechar las funciones de la política de Oauth2, VerifyAPIKey y Quota, como en REST.

GraphQL admite los siguientes tipos de cargas útiles:

  • POST de cargas útiles de graphQL con Content-Type : application/graphql
  • POST de cargas útiles de graphQL con Content-Type: applcation/json
  • GET de las cargas útiles de graphQL en las que la carga útil es un parámetro de consulta

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

Esta es una política estándar y se puede implementar en cualquier tipo de entorno. No todos los usuarios necesitan conocer los tipos de políticas y el 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.

Elemento <GraphQL>

Define una política <GraphQL>.

Valor predeterminado Consulta la pestaña Política predeterminada, a continuación
¿Es obligatorio? Obligatorio
Tipo TIPO
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</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:
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 ninguna

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 ninguna

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.

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

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 ninguna

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 ninguna

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 ninguna

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.

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

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.

Diagrama de una consulta de 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.
definition 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.
directives 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.
definition 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