Créer une requête persistée
Une requête persistée est une combinaison des APIs GraphQL et REST : c'est une requête GraphQL normale, publiée sur le site et accessible via sa propre URL, similaire à un endpoint REST.
Par exemple, nous pouvons exposer des données pour un site web via les requêtes persistées suivantes :
/graphql-query/homepage-posts/graphql-query/user-widget/graphql-query/post-contentet l'exécuter en passant l'ID de l'article :?post=1/graphql-query/post-content/espour traduire le contenu de l'article en espagnol- Autres
Exécuter la requête persistée
Une fois la requête persistée publiée, nous pouvons l'exécuter via son permalink.
La requête persistée peut être exécutée directement dans le navigateur, car elle est accessible via GET, et nous obtiendrons les données demandées, au format JSON :
Exécuter la requête persistée dans une application
Veuillez suivre les instructions du guide Se connecter au serveur GraphQL depuis un client.
Accéder à toutes les requêtes persistées
En cliquant sur "Persisted Queries" dans le menu du plugin, la liste de toutes les requêtes persistées créées s'affiche :
Créer une nouvelle requête persistée
Cliquez sur le bouton "Add New GraphQL persisted query" pour ouvrir l'éditeur WordPress :
Donnez-lui un titre et assurez-vous que le permalink est celui attendu, saisissez la requête GraphQL, sélectionnez la configuration du schéma et ajustez les options. Lorsque c'est prêt, cliquez sur le bouton Publier, et le permalink devient l'endpoint de la requête persistée.
Le lien vers l'endpoint (et vers la source) est affiché dans le panneau latéral "Persisted Query Endpoint Overview" :
Par défaut, l'endpoint de la requête persistée a le chemin /graphql-query/, et cette valeur est configurable via les Paramètres :
Éditeur de requêtes
Le client GraphiQL dans l'éditeur est l'endroit où saisir la requête GraphQL persistée :
L'éditeur est fourni avec le module complémentaire Explorer, qui permet de composer la requête en cliquant sur les champs dans le panneau latéral gauche. Cliquer sur le bouton "Run" exécute la requête, pour prévisualiser la réponse :
Configuration du schéma
La définition de qui peut accéder aux champs demandés dans la requête persistée est définie dans la configuration du schéma.
Nous devons donc créer une configuration du schéma, puis la sélectionner dans le menu déroulant (ou n'en utiliser aucune, ou utiliser celle par défaut) :
Requêtes persistées privées
En définissant le statut de la requête persistée comme privé, l'endpoint n'est accessible que par l'utilisateur administrateur. Cela évite que nos données soient involontairement partagées avec des utilisateurs qui ne devraient pas y avoir accès.
Par exemple, nous pouvons créer des requêtes persistées privées qui aident à gérer l'application, comme la récupération de données pour créer des rapports avec nos métriques.
Requêtes persistées protégées par mot de passe
Si nous créons une requête persistée pour un client spécifique, nous pouvons lui attribuer un mot de passe, afin de fournir un niveau de sécurité supplémentaire garantissant que seul ce client accède à l'endpoint.
Lors du premier accès à une requête persistée protégée par mot de passe, nous rencontrons un écran demandant le mot de passe :
Une fois le mot de passe fourni et validé, l'utilisateur accède alors à l'endpoint souhaité.
Rendre la requête persistée dynamique via des paramètres d'URL
La valeur de chaque variable peut être définie via un paramètre d'URL (avec le nom de la variable) lors de l'exécution de la requête persistée. Si l'option "Do URL params override variables?" est activée, alors le paramètre d'URL aura la priorité. Sinon, la valeur définie dans le dictionnaire de variables aura la priorité (le cas échéant).
Par exemple, dans cette requête, le nombre de résultats est contrôlé via la variable $limit, avec une valeur par défaut de 3 :
Lors de l'exécution de cette requête persistée, passer ?limit=5 exécutera la requête en retournant 5 résultats à la place :
Créer une hiérarchie de requêtes persistées
Veuillez lire les instructions sur la création d'une hiérarchie d'API.
Désactiver la requête persistée
Dans les options, définissez "Enabled" sur false pour désactiver la requête persistée.
Cette fonctionnalité peut être utile lorsque la requête persistée fait partie d'une hiérarchie d'API, afin de fournir un comportement commun à ses requêtes persistées enfants, sans qu'elle doive elle-même être exécutée.
Décrire la requête persistée
Utilisez le champ "Extrait", dans le panneau des paramètres du document, pour donner une description à la requête persistée.
Consultez plus d'informations dans le guide Ajouter une description à l'API.
Tester la requête persistée avant de la publier en ligne
Une requête persistée avec le statut brouillon ou en attente n'est disponible que pour les utilisateurs éditeurs du schéma.
Nous pouvons donc créer une requête persistée, lui attribuer une configuration du schéma, la publier comme brouillon ou en attente, et la tester (par exemple : vérifier que ses règles de contrôle d'accès sont appropriées).
Une fois approuvée, nous définissons alors son statut comme publié, rendant la requête persistée disponible pour tout le monde.
Voir la source
En ajoutant ?view=source à l'endpoint, la configuration de la requête persistée s'affichera (à condition que l'utilisateur soit connecté et que son rôle y ait accès) :
Configuration dans l'éditeur WordPress
Voici les champs dans le corps de l'éditeur :
| Champ | Description |
|---|---|
| Titre | Titre de la requête persistée |
| Client GraphiQL | Éditeur pour écrire et exécuter la requête GraphQL :
GraphiQL Explorer est activé) permet de cliquer sur les champs, qui sont automatiquement ajoutés à la requête |
| Configuration du schéma | Dans le menu déroulant, sélectionnez la configuration du schéma qui s'applique à la requête persistée, ou l'une de ces options :
|
| Options | Personnaliser le comportement de la requête persistée :
|
Voici les champs dans les paramètres du document :
| Champ | Description |
|---|---|
| Permalink | L'endpoint sous lequel la requête persistée sera disponible |
| Catégories | Permet de catégoriser la requête persistée. Ex. : mobile, app, etc. |
| Extrait | Fournit une description pour la requête persistée. Ce champ est disponible lorsque le module Excerpt as Description est activé |
| Attributs de page | Sélectionner une requête persistée parente. Ce champ est disponible lorsque le module API Hierarchy est activé |