Een persistente query aanmaken
Een persistente query is een combinatie van GraphQL- en REST-API's: het is een gewone GraphQL-query, gepubliceerd op de site en toegankelijk via een eigen URL, vergelijkbaar met een REST-endpoint.
We kunnen bijvoorbeeld gegevens voor een website beschikbaar stellen via de volgende persistente queries:
/graphql-query/homepage-posts/graphql-query/user-widget/graphql-query/post-contenten deze uitvoeren door het ID van het bericht mee te geven:?post=1/graphql-query/post-content/esom de inhoud van het bericht naar het Spaans te vertalen- Andere
De persistente query uitvoeren
Zodra de persistente query is gepubliceerd, kunnen we deze uitvoeren via de permalink.
De persistente query kan rechtstreeks in de browser worden uitgevoerd, omdat deze via GET toegankelijk is, en we ontvangen de gevraagde gegevens in JSON-formaat:
De persistente query uitvoeren in een applicatie
Volg de instructies in de gids Verbinding maken met de GraphQL-server vanuit een client.
Alle persistente queries bekijken
Door op "Persisted Queries" in het menu van de plugin te klikken, wordt de lijst van alle aangemaakte persistente queries weergegeven:
Een nieuwe persistente query aanmaken
Klik op de knop "Add New GraphQL persisted query" om de WordPress-editor te openen:
Geef het een titel en zorg ervoor dat de permalink de verwachte is, voer de GraphQL-query in, selecteer de schemaconfiguratie en pas de opties aan. Wanneer het klaar is, klik je op de knop Publiceren, en de permalink wordt het endpoint van de persistente query.
De link naar het endpoint (en naar de bron) wordt getoond in het zijpaneel "Persisted Query Endpoint Overview":
Standaard heeft het endpoint van de persistente query het pad /graphql-query/, en deze waarde is configureerbaar via de Instellingen:
Query-editor
De GraphiQL-client in de editor is de plek om de GraphQL-persistente query in te voeren:
De editor wordt geleverd met de Explorer-add-on, waarmee je de query kunt samenstellen door op de velden in het linkerzijpaneel te klikken. Door op de knop "Run" te klikken wordt de query uitgevoerd om een ​​voorbeeld van de respons te bekijken:
Schemaconfiguratie
Wie toegang heeft tot de velden die in de persistente query worden opgevraagd, wordt bepaald in de schemaconfiguratie.
We moeten dus een schemaconfiguratie aanmaken, en deze vervolgens selecteren uit de vervolgkeuzelijst (of geen gebruiken, of de standaard):
Privé persistente queries
Door de status van de persistente query in te stellen op privé, is het endpoint alleen toegankelijk voor de beheerder. Dit voorkomt dat onze gegevens onbedoeld worden gedeeld met gebruikers die geen toegang zouden mogen hebben.
We kunnen bijvoorbeeld privé persistente queries aanmaken die helpen bij het beheren van de applicatie, zoals het ophalen van gegevens om rapporten met onze statistieken te maken.
Met wachtwoord beveiligde persistente queries
Als we een persistente query aanmaken voor een specifieke klant, kunnen we er een wachtwoord aan toewijzen om een ​​extra beveiligingsniveau te bieden, zodat alleen die klant toegang heeft tot het endpoint.
Bij de eerste toegang tot een met wachtwoord beveiligde persistente query verschijnt er een scherm dat om het wachtwoord vraagt:
Pas nadat het wachtwoord is ingevoerd en gevalideerd, krijgt de gebruiker toegang tot het beoogde endpoint.
De persistente query dynamisch maken via URL-parameters
De waarde voor elke variabele kan worden ingesteld via een URL-parameter (met de naam van de variabele) bij het uitvoeren van de persistente query. Als de optie "Do URL params override variables?" is ingeschakeld, heeft de URL-parameter prioriteit. Anders heeft de waarde die is gedefinieerd in het variabelenwoordenboek prioriteit (indien aanwezig).
In deze query wordt het aantal resultaten bijvoorbeeld bepaald door de variabele $limit, met een standaardwaarde van 3:
Bij het uitvoeren van deze persistente query zal het meegeven van ?limit=5 de query uitvoeren en 5 resultaten teruggeven:
Een hiërarchie van persistente queries aanmaken
Lees de instructies over een API-hiërarchie aanmaken.
De persistente query uitschakelen
Stel in de opties "Enabled" in op false om de persistente query uit te schakelen.
Deze functie kan nuttig zijn wanneer de persistente query deel uitmaakt van een API-hiërarchie, om een gemeenschappelijk gedrag te bieden aan zijn onderliggende persistente queries, maar zonder dat deze zelf uitgevoerd hoeft te worden.
De persistente query beschrijven
Gebruik het veld "Excerpt" in het paneel Documentinstellingen om een beschrijving aan de persistente query te geven.
Meer informatie vind je in de gids Een beschrijving toevoegen aan de API.
De persistente query testen voor publicatie
Een persistente query met de status concept of in afwachting is alleen beschikbaar voor gebruikers die het schema bewerken.
We kunnen dus een persistente query aanmaken, een Schemaconfiguratie toewijzen, deze publiceren als concept of in afwachting, en deze testen (bijv.: controleren of de Toegangscontroleregelsg geschikt zijn).
Pas na goedkeuring stellen we de status in als gepubliceerd, waardoor de persistente query voor iedereen beschikbaar wordt.
De bron bekijken
Door ?view=source aan het endpoint toe te voegen, wordt de configuratie van de persistente query weergegeven (zolang de gebruiker is ingelogd en de gebruikersrol daar toegang toe heeft):
Configuratie in de WordPress-editor
Dit zijn de invoervelden in de hoofdtekst van de editor:
| Invoer | Beschrijving |
|---|---|
| Titel | Titel van de persistente query |
| GraphiQL-client | Editor om de GraphQL-query te schrijven en uit te voeren:
GraphiQL Explorer is ingeschakeld) maakt het mogelijk om op velden te klikken, die automatisch aan de query worden toegevoegd |
| Schemaconfiguratie | Selecteer uit de vervolgkeuzelijst de schemaconfiguratie die van toepassing is op de persistente query, of een van de volgende opties:
|
| Opties | Pas het gedrag van de persistente query aan:
|
Dit zijn de invoervelden in de Documentinstellingen:
| Invoer | Beschrijving |
|---|---|
| Permalink | Het endpoint waaronder de persistente query beschikbaar is |
| Categorieën | Maakt het mogelijk de persistente query te categoriseren. Bijv.: mobile, app, enz. |
| Excerpt | Geef een beschrijving voor de persistente query. Dit invoerveld is beschikbaar wanneer de module Excerpt as Description is ingeschakeld |
| Paginakenmerken | Selecteer een bovenliggende persistente query. Dit invoerveld is beschikbaar wanneer de module API Hierarchy is ingeschakeld |