La règle GraphQL peut analyser les charges utiles de requêtes GraphQL dans des variables de flux de messages, vérifier la requête par rapport à un schéma GraphQL, ou les deux.
La règle GraphQL peut analyser les charges utiles GraphQL dans des variables de flux de messages, vérifier les requêtes GraphQL par rapport à un schéma, ou les deux.
Vous pouvez utiliser la règle GraphQL pour :
Assurez-vous que vos API ne traitent que les requêtes conformes au schéma que vous fournissez.
Imposer des restrictions sur la charge utile en définissant un nombre maximal de fragments autorisés.
Associer GraphQL aux produits d'API.
Utiliser les fonctionnalités des règles OAuth2, VerifyAPIKey et Quota exactement comme dans REST.
GraphQL est compatible avec les types de charges utiles suivants :
POST des charges utiles graphQL avec Content-Type : application/graphql
POST des charges utiles graphQL avec Content-Type: applcation/json
GET des charges utiles graphQL où la charge utile est un paramètre de requête.
Pour obtenir un résumé rapide des options de la règle GraphQL, consultez la section Options GraphQL ci-dessous.
Pour en savoir plus sur GraphQL, consultez la page GraphQL.org.
Exemple
L'exemple suivant montre comment importer un schéma GraphQL dans Apigee puis l'utiliser pour valider les requêtes avec du contenu GraphQL.
Créer un fichier de schéma
Pour exécuter l'exemple, commencez par créer un fichier de schéma GraphQL avec le contenu suivant :
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!
}
Enregistrez le fichier avec le nom que vous souhaitez utiliser, suivi de l'extension .graphql.
Ajouter la règle GraphQL dans l'interface utilisateur d'Apigee
Dans la barre de navigation, sélectionnez Développer > Proxys d'API.
Dans la liste des proxys, sélectionnez le proxy d'API pour lequel vous souhaitez utiliser la règle GraphQL.
Cliquez sur l'onglet DEVELOP.
Dans le volet de gauche, cliquez sur le bouton + à côté du dossier Policies (Règles).
Dans la boîte de dialogue Create policy (Créer une règle), cliquez dans le champ Select policy type (Sélectionner un type de règle) et faites défiler la page jusqu'à Mediation (Médiation), puis sélectionnez GraphQL.
Saisissez un nom à afficher et un nom.
Sélectionnez ensuite un fichier de schéma GraphQL comme suit :
Cliquez sur le champ Fichier de schéma. Les options suivantes s'affichent :
Aucun schéma. Si vous sélectionnez cette option, Apigee n'utilisera pas de schéma pour valider les requêtes.
Importer le schéma GraphQL (.graphql)
Sélectionnez Importer le schéma GraphQL (.graphql). Les éléments suivants s'affichent :
Cliquez sur Sélectionner un fichier, puis sélectionnez le fichier de schéma que vous avez créé précédemment (qui doit avoir l'extension .graphql). Le fichier apparaît dans le nom du schéma.
Cliquez sur Create (Créer) pour créer la règle.
Maintenant que vous avez créé la règle GraphQL, vous pouvez l'associer à une étape du PreFlow :
Sélectionnez Proxy Endpoints > default > PreFlow (Points de terminaison du proxy > Par défaut > PreFlow) dans le volet de gauche :
Cliquez sur le bouton + à côté de PreFlow dans le volet Réponse en bas à droite de l'éditeur visuel :
Dans la boîte de dialogue Ajouter une étape de règle, sélectionnez la règle GQL-.
Cliquez sur Ajouter pour associer la règle.
Cliquez sur Save (Enregistrer) pour enregistrer vos modifications dans la révision actuelle.
Pour déployer vos modifications, cliquez sur l'onglet Overview (Présentation) et sélectionnez Deploy (Déployer).
Consultez les options GraphQL ci-dessous pour découvrir les options que vous pouvez définir pour la règle GraphQL.
Dans la barre de navigation, sélectionnez Développer > Proxys d'API.
Dans la liste des proxys, sélectionnez le proxy d'API pour lequel vous souhaitez utiliser la règle GraphQL.
Cliquez sur l'onglet DEVELOP.
Dans le volet Flow: PreFlow (Flux : PreFlow), cliquez sur le bouton + Step (Ajouter une étape).
Dans le volet Add Step (Ajouter une étape), faites défiler la page jusqu'en bas de la section Mediation (Médiation) puis sélectionnez GraphQL.
Le volet Add Step (Ajouter une étape) affiche les options suivantes :
Nom à afficher : nom à afficher de la règle.
Nom : nom interne de la règle.
Fichier de schéma : option permettant d'importer un fichier contenant un schéma GraphQL qui permettra à Apigee de valider les requêtes avec du contenu GraphQL.
Pour utiliser un schéma, procédez comme suit :
Cliquez sur le champ Fichier de schéma. Les options suivantes s'affichent :
Aucun schéma. Si vous sélectionnez cette option, Apigee n'utilisera pas de schéma pour valider les requêtes.
Importer le schéma GraphQL (.graphql)
Sélectionnez Importer le schéma GraphQL (.graphql). Les éléments suivants s'affichent :
Cliquez sur Sélectionner un fichier, puis sélectionnez le fichier de schéma que vous avez créé précédemment (qui doit avoir l'extension .graphql). Le fichier apparaît dans le champ nom du schéma.
Cliquez sur Ajouter. Le volet Flow: PreFlow (Flux : PreFlow) s'affiche désormais comme suit :
Consultez les options GraphQL ci-dessous pour découvrir les options que vous pouvez définir pour la règle GraphQL. Pour cet exemple, laissez-les telles quelles.
Pour déployer votre proxy, cliquez sur l'onglet Overview (Présentation) et sélectionnez Deploy (Déployer).
Vous pouvez maintenant tester la règle GraphQL avec la commande curl suivante :
Où PROXY_BASEPATH est le chemin de base de proxy et HOST_NAME est le nom de votre proxy (dernier numéro de révision inclus). Lorsque vous exécutez la commande, Apigee valide la requête par rapport au schéma et renvoie le résultat suivant.
OperationType : type d'opération. Les options disponibles sont les suivantes :
query : équivalent GraphQL de l'opération REST GET.
mutation : équivalent GraphQL de l'opération REST PUT.
query_mutation : query et mutation.
MaxDepth : profondeur maximale de la requête lorsqu'elle est représentée sous forme d'arborescence.
MaxDepth vous permet de bloquer les requêtes avancées dans la charge utile afin qu'Apigee n'ait pas besoin de créer des variables de flux très volumineuses pour contenir les valeurs.
Cependant, la charge utile est envoyée telle quelle, quelle que soit la valeur de MaxDepth.
MaxCount : nombre maximal de fragments dans la charge utile.
Cela permet d'empêcher le serveur de backend GraphQL du client d'exécuter des requêtes très complexes, ce qui oblige les clients à fractionner leur logique en charges utiles plus petites.
Action : une des actions GraphQL suivantes :
parse : Apigee analyse la charge utile GraphQL dans les variables de flux. Vous pouvez ensuite utiliser le contenu des variables de flux dans des règles telles que JavaCallout. Notez que parse vérifie également la charge utile.
verify : Apigee vérifie que la charge utile GraphQL est conforme au schéma importé dans le proxy. Vous pouvez utiliser verify pour vous assurer que vous n'obtenez pas de requêtes non conformes à votre schéma. Cela peut vous faire gagner un temps CPU précieux dans le backend.
parse_verify : analyse et vérification de la charge utile.
ResourceURL : chemin d'accès au fichier de schéma GraphQL utilisé par Apigee pour vérifier la requête GraphQL.
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/09/04 (UTC).
[[["Facile à comprendre","easyToUnderstand","thumb-up"],["J'ai pu résoudre mon problème","solvedMyProblem","thumb-up"],["Autre","otherUp","thumb-up"]],[["Difficile à comprendre","hardToUnderstand","thumb-down"],["Informations ou exemple de code incorrects","incorrectInformationOrSampleCode","thumb-down"],["Il n'y a pas l'information/les exemples dont j'ai besoin","missingTheInformationSamplesINeed","thumb-down"],["Problème de traduction","translationIssue","thumb-down"],["Autre","otherDown","thumb-down"]],["Dernière mise à jour le 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)."]]
