Eine persistierte Query erstellen
Eine persistierte Query ist eine Kombination aus GraphQL- und REST-APIs: Sie ist eine normale GraphQL-Query, die auf der Website veröffentlicht wird und unter ihrer eigenen URL erreichbar ist, ähnlich einem REST-Endpoint.
So können wir beispielsweise Daten für eine Website über folgende persistierte queries bereitstellen:
/graphql-query/homepage-posts/graphql-query/user-widget/graphql-query/post-contentund sie ausführen, indem wir die ID des Beitrags übergeben:?post=1/graphql-query/post-content/esum den Inhalt des Beitrags ins Spanische zu übersetzen- Weitere
Die persistierte Query ausführen
Sobald die persistierte Query veröffentlicht ist, können wir sie über ihren Permalink ausführen.
Die persistierte Query kann direkt im Browser ausgeführt werden, da sie über GET abgerufen wird, und wir erhalten die angeforderten Daten im JSON-Format:
Die persistierte Query in einer Anwendung ausführen
Bitte folge den Anweisungen in der Anleitung Vom Client aus mit dem GraphQL-Server verbinden.
Alle persistierten queries abrufen
Wenn du im Menü des Plugins auf "Persisted Queries" klickst, wird die Liste aller erstellten persistierten queries angezeigt:
Eine neue persistierte Query erstellen
Klicke auf die Schaltfläche "Add New GraphQL persisted query", um den WordPress-Editor zu öffnen:
Vergib einen Titel und stelle sicher, dass der Permalink der erwartete ist, gib die GraphQL-Query ein, wähle die Schema-Konfiguration aus und passe die Optionen an. Wenn du fertig bist, klicke auf die Schaltfläche Veröffentlichen, und der Permalink wird zum Endpoint der persistierten Query.
Der Link zum Endpoint (und zur Quelle) wird im Seitenpanel "Persisted Query Endpoint Overview" angezeigt:
Standardmäßig hat der Endpoint der persistierten Query den Pfad /graphql-query/, und dieser Wert ist über die Einstellungen konfigurierbar:
Query-Editor
Der GraphiQL-Client im Editor ist der Ort, an dem du die persistierte GraphQL-Query eingibst:
Der Editor wird mit dem Explorer-Add-on geliefert, mit dem du die Query zusammenstellen kannst, indem du auf die Felder im linken Seitenpanel klickst. Ein Klick auf die Schaltfläche "Run" führt die Query aus, um die Antwort in der Vorschau anzuzeigen:
Schema-Konfiguration
Wer auf die in der persistierten Query angeforderten Felder zugreifen darf, wird in der Schema-Konfiguration festgelegt.
Wir müssen daher eine Schema-Konfiguration erstellen und sie dann aus dem Dropdown-Menü auswählen (oder keine verwenden oder die Standardkonfiguration):
Private persistierte queries
Wenn du den Status der persistierten Query auf privat setzt, ist der Endpoint nur für den Administrator zugänglich. Damit wird verhindert, dass unsere Daten unbeabsichtigt mit Benutzern geteilt werden, die keinen Zugriff darauf haben sollten.
So können wir beispielsweise private persistierte queries erstellen, die bei der Verwaltung der Anwendung helfen, etwa beim Abrufen von Daten zur Erstellung von Berichten mit unseren Metriken.
Passwortgeschützte persistierte queries
Wenn wir eine persistierte Query für einen bestimmten Kunden erstellen, können wir ihr ein Passwort zuweisen, um eine zusätzliche Sicherheitsebene bereitzustellen, die sicherstellt, dass nur dieser Kunde auf den Endpoint zugreifen kann.
Wenn du zum ersten Mal auf eine passwortgeschützte persistierte Query zugreifst, erscheint ein Bildschirm, der nach dem Passwort fragt:
Erst wenn das Passwort eingegeben und validiert wurde, erhält der Benutzer Zugang zum gewünschten Endpoint.
Die persistierte Query über URL-Parameter dynamisch machen
Der Wert jeder Variable kann beim Ausführen der persistierten Query über einen URL-Parameter (mit dem Variablennamen) gesetzt werden. Wenn die Option "Do URL params override variables?" aktiviert ist, hat der URL-Parameter Vorrang. Andernfalls hat der im Variablen-Dictionary definierte Wert Vorrang (sofern vorhanden).
In dieser Query wird beispielsweise die Anzahl der Ergebnisse über die Variable $limit mit einem Standardwert von 3 gesteuert:
Wenn diese persistierte Query ausgeführt wird und ?limit=5 übergeben wird, liefert die Query stattdessen 5 Ergebnisse zurück:
Eine Hierarchie für persistierte queries erstellen
Bitte lies die Anweisungen unter Eine API-Hierarchie erstellen.
Die persistierte Query deaktivieren
Setze in den Optionen "Enabled" auf false, um die persistierte Query zu deaktivieren.
Diese Funktion kann nützlich sein, wenn die persistierte Query Teil einer API-Hierarchie ist, um ihren untergeordneten persistierten queries ein gemeinsames Verhalten bereitzustellen, ohne selbst ausgeführt werden zu müssen.
Die persistierte Query beschreiben
Verwende das Feld "Auszug" im Panel der Dokumenteinstellungen, um der persistierten Query eine Beschreibung zu geben.
Weitere Informationen findest du in der Anleitung Eine Beschreibung zur API hinzufügen.
Die persistierte Query vor der Online-Veröffentlichung testen
Eine persistierte Query mit dem Status Entwurf oder Ausstehend steht nur den Schema-Editor-Benutzern zur Verfügung.
Wir können also eine persistierte Query erstellen, ihr eine Schema-Konfiguration zuweisen, sie als Entwurf oder Ausstehend veröffentlichen und sie testen (z. B. prüfen, ob ihre Zugangskontrollregeln geeignet sind).
Nach der Genehmigung setzen wir ihren Status auf Veröffentlicht, wodurch die persistierte Query für alle verfügbar wird.
Die Quelle anzeigen
Wenn du ?view=source an den Endpoint anhängst, wird die Konfiguration der persistierten Query angezeigt (sofern der Benutzer angemeldet ist und seine Rolle darauf Zugriff hat):
Konfiguration im WordPress-Editor
Dies sind die Eingabefelder im Hauptbereich des Editors:
| Feld | Beschreibung |
|---|---|
| Titel | Titel der persistierten Query |
| GraphiQL-Client | Editor zum Schreiben und Ausführen der GraphQL-Query:
GraphiQL Explorer aktiviert ist) erlaubt es, auf Felder zu klicken, die automatisch zur Query hinzugefügt werden |
| Schema-Konfiguration | Wähle aus dem Dropdown-Menü die Schema-Konfiguration aus, die auf die persistierte Query angewendet werden soll, oder eine dieser Optionen:
|
| Optionen | Passe das Verhalten der persistierten Query an:
|
Dies sind die Eingabefelder in den Dokumenteinstellungen:
| Feld | Beschreibung |
|---|---|
| Permalink | Der Endpoint, unter dem die persistierte Query verfügbar sein wird |
| Kategorien | Ermöglicht die Kategorisierung der persistierten Query. Z. B.: mobile, app, usw. |
| Auszug | Stellt eine Beschreibung für die persistierte Query bereit. Dieses Feld ist verfügbar, wenn das Modul Excerpt as Description aktiviert ist |
| Seitenattribute | Wähle eine übergeordnete persistierte Query aus. Dieses Feld ist verfügbar, wenn das Modul API Hierarchy aktiviert ist |