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 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 De forma opcional, usa el elemento |
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 cuandoAction
se establece enparse
. Esto puede ahorrar tiempo de CPU valioso en el backend. Ten en cuenta queverify
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 GraphQLquery_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.
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 GraphQLroot-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 valoressub-indices
: Índices secundarioschild-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 |