Mediante la política de GraphQL, se pueden analizar cargas útiles de solicitudes de GraphQL en variables de flujo de mensajes, así como verificar la solicitud con un esquema de GraphQL o realizar ambas opciones.
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 un resumen rápido de las opciones de la política GraphQL, consulta las siguientes opciones de GraphQL.
Para obtener más información sobre GraphQL, visista GraphQL.org.
Ejemplo
En el siguiente ejemplo, se muestra cómo subir un esquema de GraphQL a Apigee y usarlo para validar solicitudes con contenido de GraphQL.
Crea un archivo de esquema
Para ejecutar el ejemplo, primero crea un archivo de esquema de GraphQL con el siguiente contenido:
type Query {
allPersons(last: Int): [Person!]!
}
type Mutation {
createPerson(name: String!, age: Int!): Person!
}
type Subscription {
newPerson: Person!
}
type Person {
name: String!
sex: String!
age: Int!
posts: [Post!]!
}
type Post {
title: String!
author: Person!
}
Guarda el archivo con el nombre que quieras usar, seguido de la extensión .graphql.
Agrega la política de GraphQL en la IU de Apigee
Editor de proxies nuevo
Primero, crea la política de GraphQL de la siguiente manera:
En la barra de navegación, selecciona Desarrollar > Proxies de API.
En la lista de proxies, selecciona el proxy de API para el que deseas usar la política de GraphQL.
Haz clic en la pestaña DEVELOP.
En el panel izquierdo, haz clic en el botón + junto a la carpeta Políticas.
En el cuadro de diálogo Crear política, haz clic en el campo Seleccionar tipo de política, desplázate hacia abajo hasta mediación y selecciona GraphQL.
Ingresa un Nombre visible y un Nombre.
A continuación, selecciona un archivo de esquema de GraphQL de la siguiente manera:
Haz clic en el campo Archivo de esquema. Se mostrarán las siguientes opciones:
Sin esquema. Si seleccionas esta opción, Apigee no usará un esquema para validar las solicitudes.
Importa el esquema de GraphQL (.graphql)
Selecciona Importar esquema de GraphQL (.graphql). Esto muestra lo siguiente:
Haz clic en Elegir archivo y selecciona el archivo de esquema que creaste antes (que debe tener la extensión .graphql). El archivo aparece en Nombre del esquema.
Haz clic en Crear para crear la política.
Ahora que creaste la política de GraphQL, puedes adjuntarla a un paso en el PreFlow:
Selecciona Extremos de Proxy > configuración predeterminada> PreFlow en el panel izquierdo:
Haz clic en el botón + junto a PreFlow en el panel Respuesta en la esquina inferior derecha del editor visual:
En el cuadro de diálogo Agregar paso de la política, selecciona la política GQL-.
Haz clic en Agregar para adjuntar la política.
Haz clic en Guardar para guardar la revisión actual con sus cambios.
Para implementar los cambios, haz clic en la pestaña Descripción general y selecciona Implementar.
Consulta las siguientes Opciones de GraphQL para conocer lo que puedes configurar para la política de GraphQL.
En la barra de navegación, selecciona Desarrollar > Proxies de API.
En la lista de proxies, selecciona el proxy de API para el que deseas usar la política de GraphQL.
Haz clic en la pestaña DEVELOP.
En el panel Flujo: PreFlow, haz clic en el botón Paso +.
En el panel Agregar paso, desplázate hasta la parte inferior de la sección Mediación y selecciona GraphQL.
En el panel Agregar paso, se muestran las siguientes opciones:
Nombre visible: Muestra el nombre de la política.
Nombre: Nombre interno de la política.
Archivo de esquema: Opción para subir un archivo con un esquema GraphQL que Apigee usará a fin de validar solicitudes con contenido de GraphQL.
Para usar un esquema, haz lo siguiente:
Haz clic en el campo Archivo de esquema. Se mostrarán las siguientes opciones:
Sin esquema. Si seleccionas esta opción, Apigee no usará un esquema para validar las solicitudes.
Importa el esquema de GraphQL (.graphql)
Selecciona Importar esquema de GraphQL (.graphql). Esto muestra lo siguiente:
Haz clic en Elegir archivo y selecciona el archivo de esquema que creaste antes (que debe tener la extensión .graphql). El archivo aparece en el campo Nombre del esquema.
Haz clic en Agregar. El panel Flujo: Flujo previo ahora aparece como se muestra a continuación:
Consulta las siguientes Opciones de GraphQL para conocer lo que puedes configurar para la política de GraphQL. En este ejemplo, déjalas como están.
Para implementar tu proxy, haz clic en la pestaña Descripción general y selecciona Implementar.
Ahora, puedes probar la política de GraphQL con el siguiente comando curl:
En el ejemplo anterior, PROXY_BASEPATH es la ruta base del proxy y HOST_NAME es el nombre de tu proxy, incluido el número de revisión más reciente. Cuando ejecutas el comando, Apigee valida la solicitud en el esquema y muestra el siguiente resultado.
OperationType: El tipo de operación. Las opciones son las siguientes:
query: El equivalente de GraphQL de la operación GET de REST
mutation: El equivalente de GraphQL de la operación PUT de REST
query_mutation: query y mutation.
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.
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.
Action: Es una de las siguientes acciones de GraphQL:
parseApigee analiza la carga útil de GraphQL en las variables de flujo. Luego, puedes usar el contenido de las variables de flujo en políticas como JavaCallout. Ten en cuenta que parse también verifica la carga útil.
verify: Apigee verifica que la carga útil de GraphQL cumpla con el esquema subido al proxy. Puedes usar verify para asegurarte de no recibir solicitudes que no se ajusten a tu esquema. Esto puede ahorrar tiempo de CPU valioso en el backend.
parse_verify: Analiza y verifica la carga útil.
ResourceURL: La ruta de acceso al archivo de esquema de GraphQL que Apigee usa para verificar la solicitud de GraphQL.
[[["Fácil de comprender","easyToUnderstand","thumb-up"],["Resolvió mi problema","solvedMyProblem","thumb-up"],["Otro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Información o código de muestra incorrectos","incorrectInformationOrSampleCode","thumb-down"],["Faltan la información o los ejemplos que necesito","missingTheInformationSamplesINeed","thumb-down"],["Problema de traducción","translationIssue","thumb-down"],["Otro","otherDown","thumb-down"]],["Última actualización: 2025-09-04 (UTC)"],[[["\u003cp\u003eThe GraphQL policy in Apigee and Apigee hybrid allows parsing GraphQL request payloads into message flow variables, verifying requests against a GraphQL schema, or both.\u003c/p\u003e\n"],["\u003cp\u003eThis policy enables ensuring that APIs process only schema-conforming requests, setting limits on the number of fragments, and associating GraphQL with API products.\u003c/p\u003e\n"],["\u003cp\u003eApigee supports various GraphQL payload types, including POST with \u003ccode\u003eapplication/graphql\u003c/code\u003e or \u003ccode\u003eapplication/json\u003c/code\u003e, and GET with the payload as a query parameter.\u003c/p\u003e\n"],["\u003cp\u003eSchema validation is a resource-intensive operation, and only one schema per policy can be included, requiring multiple policies for multiple schemas, and the schema file needs to be uploaded during policy creation.\u003c/p\u003e\n"],["\u003cp\u003eThe GraphQL policy options include actions such as \u003ccode\u003eparse\u003c/code\u003e, \u003ccode\u003everify\u003c/code\u003e, and \u003ccode\u003eparse_verify\u003c/code\u003e, along with parameters like \u003ccode\u003eOperationType\u003c/code\u003e, \u003ccode\u003eMaxDepth\u003c/code\u003e, and \u003ccode\u003eMaxCount\u003c/code\u003e to manage GraphQL operations and payload complexity.\u003c/p\u003e\n"]]],[],null,["# Using GraphQL\n\n*This page\napplies to **Apigee** and **Apigee hybrid**.*\n\n\n*View [Apigee Edge](https://docs.apigee.com/api-platform/get-started/what-apigee-edge) documentation.*\n\nThe [GraphQL policy](/apigee/docs/api-platform/reference/policies/graphql-policy) can\nparse GraphQL request payloads into message flow\nvariables, verify the request against a GraphQL schema, or both.\n\nThe GraphQL policy can parse GraphQL payloads into message flow\nvariables, verify GraphQL requests against a schema, or both.\n\nYou can use the GraphQL policy to:\n\n- Ensure that your APIs only process requests that conform to the schema you provide.\n- Impose restrictions on the payload by setting a maximum on the number of fragments allowed.\n- Associate GraphQL with API products.\n- Leverage the Oauth2, VerifyAPIKey, and Quota policy features, just as in REST.\n\nGraphQL supports the following types of payloads:\n\n- POST of graphQL payloads with `Content-Type : application/graphql`\n- POST of graphQL payloads with `Content-Type: applcation/json`\n- GET of graphQL payloads where the payload is a query parameter\n\n| **Note:** For `application/json` payloads of the form \n|\n| ```\n| {\n| \"query\": \"...\",\n| \"operationName\": \"...\",\n| \"variables\": { \"myVariable\": \"someValue\", ... }\n| }\n| ```\n| Apigee currently ignores the optional `operationName` and `variables` fields.\n\nFor a quick summary of the options for the GraphQL policy, see [GraphQL\noptions](#graphql-options) below.\n\nTo learn more about GraphQL,\nsee [GraphQL.org](https://graphql.org/).\n\nExample\n-------\n\nThe following example shows how to upload a GraphQL schema to Apigee, and use it to\nvalidate requests with GraphQL content.\n| **Caution:** Verifying the payload against the schema is generally an expensive operation, and we recommend choosing to perform schema validation with care. Schema validation operations can be CPU intensive, especially when the payload and the schema are complex, and can result in significant latencies.\n| **Note:** You can only provide one schema per policy. If you need to include multiple schemas, add multiple GraphQL policies to your proxy.\n| **Notes:** For the classic Proxy Editor only:\n|\n| - You can only upload a GraphQL schema file when you add a GraphQL policy. You *cannot* upload it in the **Resources** pane in the Proxy Editor.\n| - After uploading a GraphQL schema file, you cannot view or edit it in the Proxy Editor.\n|\n| These limitations do not apply to the new Proxy Editor.\n\n### Create a schema file\n\nTo run the example, first create a GraphQL schema file with the following contents: \n\n```\ntype Query {\n allPersons(last: Int): [Person!]!\n}\n\ntype Mutation {\n createPerson(name: String!, age: Int!): Person!\n}\n\ntype Subscription {\n newPerson: Person!\n}\n\ntype Person {\n name: String!\n sex: String!\n age: Int!\n posts: [Post!]!\n}\n\ntype Post {\n title: String!\n author: Person!\n}\n```\n\nSave the file with whatever name you'd like to use, followed by the extension `.graphql`.\n\n### Add the GraphQL policy in the Apigee UI\n\n| **Note:** Apigee is introducing a new version of the Proxy\n| Editor, which will make it easier to manage proxies.\n|\n| The instructions in the first two tabs below explain how to\nuse either the new Proxy Editor or the classic Proxy Editor. \n\n### New Proxy Editor\n\nFirst, create the GraphQL policy as follows:\n\n1. Sign in to the [Apigee UI](https://apigee.google.com).\n2. In the navigation bar, select **Develop \\\u003e API Proxies**.\n3. In the list of proxies, select the API proxy for which you want to use the GraphQL policy.\n4. Click the **DEVELOP** tab.\n5. In the left-hand pane, click the **+** button next to the **Policies** folder.\n6. In the **Create policy** dialog, click in the **Select policy type** field and\n scroll down to **Mediation** and select\n [**GraphQL**](/apigee/docs/api-platform/reference/policies/graphql-policy).\n\n Enter a **Display name** and **Name**.\n\n Next, select a GraphQL schema file as follows:\n 1. Click the **Schema File** field. This displays the following choices:\n - **No Schema**. If you select this option, Apigee will not use a schema to validate requests.\n - **Import GraphQL schema (.graphql)**\n 2. Select **Import GraphQL schema (.graphql)**. This displays the\n following:\n\n 3. Click **Choose File** and select the schema file you created previously\n (which must have the extension `.graphql`).\n The file appears in the **Schema name** field.\n\n7. Click **Create** to create the policy.\n\nNow that you have created the **GraphQL** policy, you can attach it to a step in\nthe PreFlow:\n\n1. Select **Proxy Endpoints \\\u003e default \\\u003e PreFlow** in the left-hand pane:\n\n2. Click the **+** button next to **PreFlow** in the **Response** pane at the bottom-right of the Visual Editor:\n\n3. In the **Add policy step** dialog, select the **GQL-** policy. **Note:** This example uses the default name, **GQL** , for the GraphQL policy. You can change the name in the **DisplayName** element in the XML for the policy, by adding a descriptive phrase after **GQL-** . See [Change the policy name](/apigee/docs/api-platform/get-started/add-policy#change-the-policy-name).\n4. Click **Add** to attach the policy.\n5. Click **Save** to save the current revision with your changes.\n6. To deploy your changes, click the **Overview** tab and select **Deploy**.\n\nSee [GraphQL options](#graphql-options) below for the options you can set for\nthe GraphQL policy.\n\n### Classic Proxy Editor\n\n1. Sign in to the [Apigee UI](https://apigee.google.com).\n2. In the navigation bar, select **Develop \\\u003e API Proxies**.\n3. In the list of proxies, select the API proxy for which you want to use the GraphQL policy.\n4. Click the **DEVELOP** tab.\n5. In the **Flow: PreFlow** pane, click the **+ Step** button.\n\n6. In the **Add Step** pane, scroll down to\n the bottom of the **Mediation** section, and select **GraphQL**.\n\n The **Add Step** pane displays the following options:\n - **Display Name**: Display name of the policy.\n - **Name**: Internal name of the policy.\n - **Schema file**: Option to upload a file containing a GraphQL schema that Apigee will use to validate requests with GraphQL content.\n\n To use a schema, do the following:\n 1. Click the **Schema File** field. This displays the following choices:\n - **No Schema**. If you select this option, Apigee will not use a schema to validate requests.\n - **Import GraphQL schema (.graphql)**\n 2. Select **Import GraphQL schema (.graphql)**. This displays the\n following:\n\n 3. Click **Choose File** and select the schema file you\n [created previously](#create-a-schema-file)\n (which must have the extension `.graphql`).\n The file appears in the **Schema name** field.\n\n7. Click **Add** . The **Flow: PreFlow** pane now appears as shown below:\n\n\n See [GraphQL options](#graphql-options) below for the options you can set for\n the GraphQL policy. For this example, leave them as they are.\n8. To deploy your proxy, click the **Overview** tab and select **Deploy**.\n\n\nNow you can test the GraphQL policy with the following `curl` command: \n\n```\ncurl --location --request POST 'https://PROXY_BASEPATH/HOST_NAME' --data-raw 'query query_name {allPersons {name}}' -k\n```\n\nWhere \u003cvar translate=\"no\"\u003ePROXY_BASEPATH\u003c/var\u003e is the proxy basepath and \u003cvar translate=\"no\"\u003eHOST_NAME\u003c/var\u003e is the name of\nyour proxy, including the latest revision number. When you\nrun the command, Apigee validates the request against the schema and returns the following\noutput. \n\n```\n{\n \"query query_name {allPersons {name}}\": \"\",\n \"id\": 101\n}\n```\n\nHere's another example of a request: \n\n```\ncurl --location --request POST 'https://PROXY_BASEPATH/HOST_NAME' --data-raw 'query ilovegql {DEADBEEF}' -k\n```\n\nThis time the request validation fails with the following error message. \n\n```\n{\"fault\":{\"faultstring\":\"steps.graphQL.SchemaValidationFailed\",\"detail\":{\"errorcode\":\"steps.graphQL.SchemaValidationFailed\"}}}\n```\n\nGraphQL options\n---------------\n\nThe GraphPolicy has the following options:\n\n- `OperationType`: The operation type. The options are:\n - `query`: The GraphQL equivalent of the REST `GET` operation.\n - `mutation`: The GraphQL equivalent of the REST `PUT` operation.\n - `query_mutation`: Both `query` and `mutation`.\n- `MaxDepth`: The maximum depth of the query, when represented as a tree. `MaxDepth` allows you to block deep queries in the payload, so that Apigee does not need to create very large flow variables to hold the values. However, the payload is sent as is, regardless of the value of `MaxDepth`.\n- `MaxCount`: The maximum number of fragments that can be in the payload. You can use this to prevent the GraphQL back-end server of the customer from executing highly complex queries, forcing clients to break their logic into smaller payloads.\n- `Action`: One the following GraphQL actions:\n - `parse`Apigee parses the GraphQL payload into the flow variables. You can then use the contents of the flow variables in policies such as JavaCallout. Note that `parse` also verifies the payload.\n - `verify`: Apigee verifies that the GraphQL payload conforms to the schema uploaded to the proxy. You can use `verify` to ensure that you do not get requests that don't conform to your schema. This can save valuable CPU time in the backend.\n - `parse_verify`: Parse and verify the payload.\n- `ResourceURL`: The path to the GraphQL schema file that Apigee uses to verify the GraphQL request.\\`\n\nTo learn more about these options, see the\n[GraphQL policy reference\npage](/apigee/docs/api-platform/reference/policies/graphql-policy)."]]
