Utiliser GraphQL

Vous consultez la documentation d'Apigee X.
Consultez la documentation d'Apigee Edge.

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. Vous pouvez utiliser la règle GraphQL pour :

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

Remarque : Pour les charges utiles application/json du formulaire

{
  "query": "...",
  "operationName": "...",
  "variables": { "myVariable": "someValue", ... }
}

Apigee ignore actuellement les champs facultatifs operationName et variables.

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.

Attention : La vérification de la charge utile par rapport au schéma est généralement une opération coûteuse, et nous vous recommandons de choisir d'effectuer la validation du schéma avec soin. Les opérations de validation du schéma peuvent utiliser beaucoup de ressources processeur, en particulier lorsque la charge utile et le schéma sont complexes, et peuvent entraîner des latences significatives.

Remarques :

• Vous ne pouvez importer un fichier de schéma GraphQL que lorsque vous ajoutez une règle GraphQL. Vous ne pouvez pas l'importer dans le volet Ressources de l'éditeur de proxy.
• Vous ne pouvez fournir qu'un seul schéma GraphQL pour la validation dans un environnement.
• Une fois que vous avez importé un fichier de schéma GraphQL, vous ne pouvez ni l'afficher ni le modifier dans l'éditeur de proxy.

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

Remarque : Apigee introduit une nouvelle version de l'éditeur de proxys, qui facilite la gestion des proxys. À l'heure actuelle, les nouvelles vues Présentation et Développer de l'éditeur de proxy ont été publiées. Une nouvelle version de la vue Débogage sera publiée ultérieurement.

Le nouvel éditeur de proxys remplacera l'éditeur de proxys classique dans une prochaine version.

Nous vous encourageons à essayer le nouvel éditeur de proxys. Pour ce faire, cliquez simplement sur le bouton Essayer lorsque celui-ci s'affiche dans l'éditeur. Vous pouvez toujours revenir à l'éditeur de proxys classique si vous le souhaitez.

Les instructions des deux premiers onglets ci-dessous expliquent comment utiliser le nouvel éditeur de proxys ou l'éditeur de proxys classique.

Nouvel éditeur de proxys

Commencez par créer la règle GraphQL comme suit :

1. Connectez-vous à l'UI Apigee.
2. Dans la barre de navigation, sélectionnez Développer > Proxys d'API.
3. Dans la liste des proxys, sélectionnez le proxy d'API pour lequel vous souhaitez utiliser la règle GraphQL.
4. Cliquez sur l'onglet DÉVELOPPER. Si le bouton Try now (Essayer) s'affiche, cliquez dessus pour afficher la nouvelle page Développer.

   À propos du bouton Essayer

   Si c'est la première fois que vous utilisez la nouvelle version de l'éditeur de proxy, la bannière suivante s'affiche en haut de la vue Développer :

   

   Cliquez sur le bouton Essayer pour afficher la nouvelle version de la vue Développer :

   Remarque : Si vous avez précédemment cliqué sur le bouton Essayer, celui-ci ne s'affiche pas.

   La vue Développer est présentée ci-dessous.

   

5. Dans le volet de gauche, cliquez sur le bouton + à côté du dossier Policies (Règles).

6. 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 :

   1. 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)

   2. Sélectionnez Importer le schéma GraphQL (.graphql). Les éléments suivants s'affichent :

      

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

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

1. Sélectionnez Proxy Endpoints > default > PreFlow (Points de terminaison du proxy > Par défaut > PreFlow) dans le volet de gauche :

   

2. Cliquez sur le bouton + à côté de PreFlow dans le volet Réponse en bas à droite de l'éditeur visuel :

   

3. Dans la boîte de dialogue Add policy step (Ajouter une étape de règle), sélectionnez la règle GraphQL.
4. Cliquez sur Add (Ajouter) pour associer la règle.
5. Cliquez sur Save (Enregistrer) pour enregistrer vos modifications dans la révision actuelle.
6. 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.

Éditeur de proxy classique

1. Connectez-vous à l'UI Apigee.
2. Dans la barre de navigation, sélectionnez Développer > Proxys d'API.
3. Dans la liste des proxys, sélectionnez le proxy d'API pour lequel vous souhaitez utiliser la règle GraphQL.
4. Cliquez sur l'onglet DÉVELOPPER.

5. Dans le volet Flow: PreFlow (Flux : PreFlow), cliquez sur le bouton + Step (Ajouter une étape).

   

6. 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 :

   1. 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)

   2. Sélectionnez Importer le schéma GraphQL (.graphql). Les éléments suivants s'affichent :

      

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

      

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

8. 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 :

curl --location --request POST 'https://PROXY_BASEPATH/HOST_NAME' --data-raw 'query query_name {allPersons {name}}' -k

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.

{
  "query query_name {allPersons {name}}": "",
  "id": 101
}

Voici un autre exemple de requête :

curl --location --request POST 'https://PROXY_BASEPATH/HOST_NAME' --data-raw 'query ilovegql {DEADBEEF}' -k

Cette fois, la validation de la requête échoue avec le message d'erreur suivant.

{"fault":{"faultstring":"steps.graphQL.SchemaValidationFailed","detail":{"errorcode":"steps.graphQL.SchemaValidationFailed"}}}

Options GraphQL

GraphPolicy propose les options suivantes :

• 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 requête GraphQL.
  • verify : Apigee vérifie la requête GraphQL.
  • parse_verify : Apigee analyse et vérifie la requête GraphQL.
• ResourceURL : chemin d'accès au fichier de schéma GraphQL utilisé par Apigee pour vérifier la requête GraphQL.

Pour en savoir plus sur ces options, consultez la page de référence des règles GraphQL.