Política de GraphQL

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

Consulta la documentación de Apigee Edge.

Qué

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

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

• Asegúrate de que tus APIs solo procesen solicitudes que se ajusten al esquema que proporciones.
• Imponer restricciones en la carga útil definiendo un máximo en el número de fragmentos permitidos.
• Asocia GraphQL con productos de API.
• Aprovecha las funciones de las políticas Oauth2, VerifyAPIKey y Quota, al igual que 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 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:

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

Esta política 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 de cada tipo de entorno, consulta Tipos de políticas.

Consulta un ejemplo de uso de esta política en la sección Usar GraphQL.

Elemento <GraphQL>

Define una política <GraphQL>.

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

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

En la siguiente tabla se ofrece una descripción general de los elementos secundarios de <GraphQL>:

Cada uno de estos elementos secundarios se describe en las secciones que aparecen a continuación.

Referencia de elemento secundario

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

<Action>

Action 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 ver una explicación de las variables que se definen cuando Action se define como parse. De esta forma, se 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 se ajusta al esquema subido al proxy.
• parse_verify: Apigee analiza y verifica la solicitud de GraphQL.

El elemento <Action> utiliza la siguiente sintaxis:

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

<MaxCount>

Número máximo de fragmentos que puede haber en la carga útil. Puedes usar esta opción para evitar que el servidor backend de GraphQL del cliente ejecute consultas muy complejas, lo que obliga a los clientes a dividir su lógica en cargas útiles más pequeñas.

El elemento <MaxCount> utiliza la siguiente 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 tenga que crear variables de flujo muy grandes para contener los valores. Sin embargo, la carga útil se envía tal cual, independientemente del valor de MaxDepth. El valor predeterminado es 10.

El elemento <MaxDepth> utiliza la siguiente sintaxis:

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

<MaxPayloadSizeInBytes>

Tamaño máximo de una carga útil en kilobytes. Puedes usarlo para limitar el tamaño de la carga útil y evitar problemas de rendimiento.

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

El elemento <MaxPayloadSizeInBytes> utiliza la siguiente 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 GraphQL.
• mutation: una mutación de GraphQL
• query_mutation: una consulta o una mutación de GraphQL.

Si el ámbito es query y se envía una solicitud de mutación, la solicitud falla y devuelve un error 4xx.

El elemento <OperationType> utiliza la siguiente sintaxis:

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

<ResourceURL>

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

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

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

El elemento ResourceURL utiliza la siguiente sintaxis:

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

<Source>

Fuente en la que se ejecuta esta política.

El elemento <Source> utiliza la siguiente 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 funciones de una consulta graphQL y la representa como un gráfico en la notación punteada del flujo de mensajes. Una consulta puede constar de una definición de operación y, opcionalmente, de fragmentos identificados como definiciones de fragmentos. Consulta la especificación de GraphQL.

Anatomía de una solicitud de GraphQL

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

Representación en el flujo de mensajes de las definiciones de operaciones

La implementación del analizador cubre todos los aspectos de la sintaxis de GraphQL, incluido el soporte para consultas y mutaciones. Consulta Variable de flujo message.

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 se trata de variables de flujo de mensajes relacionadas con GraphQL.
• root-Index: índice basado en 0 que indica el índice de definiciones de consulta de nivel raíz (hasta 4 por solicitud de forma predeterminada).
• root-definition: cuerpo del mensaje de solicitud de GraphQL de nivel raíz, argumentos y sus valores.
• sub-indices: índices secundarios
• child-definitions: definiciones de nivel de hoja que se corresponden con campos específicos y sus valores.

Representación en la variable de flujo de mensajes de las definiciones de operaciones

Representación en el flujo de mensajes de las definiciones de fragmentos

Ejemplos de representaciones de variables de flujo de mensajes

En los siguientes ejemplos se muestran las representaciones de variables de flujo de mensajes para cargas útiles de solicitudes de ejemplo.

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

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

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

Temas relacionados

Usar GraphQL