Persistierte GraphQL-Abfragen
- Gilt für:
- Experience Manager as a Cloud Service
- Themen:
- Headless
Erstellt für:
- Admin
- Entwickler
Persistente Abfragen sind GraphQL-Abfragen, die auf dem Server mit Adobe Experience Manager (AEM) as a Cloud Service erstellt und gespeichert werden. Sie können von Client-Programmen mit einer GET-Anfrage angefragt werden. Die Antwort einer GET-Anfrage kann auf den Dispatcher- und CDN-Ebenen zwischengespeichert werden, was letztendlich die Leistung des anfragenden Client-Programms verbessert. Dies unterscheidet sich von standardmäßigen GraphQL-Abfragen, die mit POST-Anfragen ausgeführt werden, bei denen die Antwort nicht einfach zwischengespeichert werden kann.
NOTEDie GraphiQL-IDE ist in AEM verfügbar, damit Sie GraphQL-Abfragen entwickeln, testen und persistieren können, bevor Sie sie in Ihre Produktionsumgebung übertragen. Für Fälle, in denen eine Anpassung erforderlich ist (z. B. beim Anpassen des Caches), können Sie die API verwenden. Sehen Sie sich dazu das cURL-Beispiel in Persistieren einer GraphQL-Abfrage an.
Persistente Abfragen und Endpunkte
Persistente Abfragen müssen immer den Endpunkt verwenden, der mit der entsprechenden Sites-Konfiguration verknüpft ist. Sie können also entweder eine oder beide dieser Optionen verwenden:
- Globale Konfiguration und Endpunkt
Die Abfrage hat Zugriff auf alle Inhaltsfragmentmodelle. - Spezifische Sites-Konfigurationen und -Endpunkte
Das Erstellen einer persistenten Abfrage für eine bestimmte Sites-Konfiguration erfordert einen entsprechenden Sites-konfigurationsspezifischen Endpunkt (um Zugriff auf die zugehörigen Inhaltsfragmentmodelle zu gewähren).
Um beispielsweise eine persistente Abfrage speziell für die WKND-Website-Konfiguration zu erstellen, müssen eine entsprechende WKND-spezifische Sites-Konfiguration und ein WKND-spezifischer Endpunkt im Voraus erstellt werden.
NOTEWenn es beispielsweise eine bestimmte Abfrage namens my-query gibt, die ein my-model-Modell aus der Sites-Konfiguration my-conf verwendet:
- Sie können eine Abfrage unter Verwendung des spezifischen Endpunkts
my-conferstellen, und die Abfrage wird wie folgt gespeichert:/conf/my-conf/settings/graphql/persistentQueries/my-query - Sie können die gleiche Abfrage mit dem Endpunkt
globalerstellen, aber dann wird die Abfrage wie folgt gespeichert:/conf/global/settings/graphql/persistentQueries/my-query
NOTEBeibehalten einer GraphQL-Abfrage
Es wird empfohlen, Abfragen zunächst in einer AEM-Autorenumgebung beizubehalten und dann die Abfrage in Ihre AEM-Veröffentlichungsumgebung der Produktion für die Verwendung durch Programme zu übertragen.
Es gibt verschiedene Methoden zum Beibehalten von Abfragen:
- GraphiQL-IDE – siehe Speichern persistenter Abfragen (bevorzugte Methode)
- cURL: siehe folgendes Beispiel
- Andere Tools, einschließlich Postman
Die GraphiQL-IDE ist die bevorzugte Methode zum Erstellen persistenter Abfragen. So persistieren Sie eine Abfrage mithilfe des Befehlszeilen-Tools cURL:
-
Bereiten Sie die Abfrage mittels einer PUT-Anfrage an die neue Endpunkt-URL
/graphql/persist.json/<config>/<persisted-label>vor.Erstellen Sie beispielsweise eine persistente Abfrage:
$ curl -X PUT \ -H 'authorization: Basic YWRtaW46YWRtaW4=' \ -H "Content-Type: application/json" \ "http://localhost:4502/graphql/persist.json/wknd/plain-article-query" \ -d \ '{ articleList { items{ _path author main { json } } } }' -
Überprüfen Sie an dieser Stelle die Antwort.
Prüfen Sie zum Beispiel auf Erfolg:
{ "action": "create", "configurationName": "wknd", "name": "plain-article-query", "shortPath": "/wknd/plain-article-query", "path": "/conf/wknd/settings/graphql/persistentQueries/plain-article-query" } -
Sie können die persistente Abfrage dann ausführen, indem Sie die URL
/graphql/execute.json/<shortPath>per GET-Anfrage abrufen.Verwenden Sie zum Beispiel die persistente Abfrage:
$ curl -X GET \ http://localhost:4502/graphql/execute.json/wknd/plain-article-query -
Aktualisieren Sie eine persistente Abfrage mittels POST-Anfrage an einen bereits vorhandenen Abfragepfad.
Verwenden Sie zum Beispiel die persistente Abfrage:
$ curl -X POST \ -H 'authorization: Basic YWRtaW46YWRtaW4=' \ -H "Content-Type: application/json" \ "http://localhost:4502/graphql/persist.json/wknd/plain-article-query" \ -d \ '{ articleList { items{ _path author main { json } referencearticle { _path } } } }' -
Erstellen Sie eine umschlossene einfache Abfrage.
Zum Beispiel:
$ curl -X PUT \ -H 'authorization: Basic YWRtaW46YWRtaW4=' \ -H "Content-Type: application/json" \ "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-wrapped" \ -d \ '{ "query": "{articleList { items { _path author main { json } referencearticle { _path } } } }"}' -
Erstellen Sie eine umschlossene Abfrage mit Cache-Steuerung.
Zum Beispiel:
$ curl -X PUT \ -H 'authorization: Basic YWRtaW46YWRtaW4=' \ -H "Content-Type: application/json" \ "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-max-age" \ -d \ '{ "query": "{articleList { items { _path author main { json } referencearticle { _path } } } }", "cache-control": { "max-age": 300 }}' -
Erstellen Sie eine persistente Abfrage mit Parametern:
Zum Beispiel:
$ curl -X PUT \ -H 'authorization: Basic YWRtaW46YWRtaW4=' \ -H "Content-Type: application/json" \ "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-parameters" \ -d \ 'query GetAsGraphqlModelTestByPath($apath: String!, $withReference: Boolean = true) { articleByPath(_path: $apath) { item { _path author main { plaintext } referencearticle @include(if: $withReference) { _path } } } }'
Ausführen einer persistenten Abfrage
Um eine persistente Abfrage auszuführen, sendet ein Client-Programm eine GET-Anfrage mit der folgenden Syntax:
GET <AEM_HOST>/graphql/execute.json/<PERSISTENT_PATH>
Dabei ist PERSISTENT_PATH ein gekürzter Pfad zum Speicherort der persistenten Abfrage.
-
Zum Beispiel ist
wkndder Konfigurationsname undplain-article-queryder Name der persistierten Abfrage. So führen Sie die Abfrage aus:$ curl -X GET \ https://publish-p123-e456.adobeaemcloud.com/graphql/execute.json/wknd/plain-article-query -
Ausführen einer Abfrage mit Parametern.
NOTEDie Abfragevariablen und -werte müssen beim Ausführen einer persistenten Abfrage ordnungsgemäß codiert sein.Zum Beispiel:
$ curl -X GET \ "https://publish-p123-e456.adobeaemcloud.com/graphql/execute.json/wknd/plain-article-query-parameters%3Bapath%3D%2Fcontent%2Fdam%2Fwknd%2Fen%2Fmagazine%2Falaska-adventure%2Falaskan-adventures%3BwithReference%3DfalseSiehe Verwenden von Abfragevariablen für weitere Details.
Verwenden von Abfragevariablen
Abfragevariablen können mit persistenten Abfragen verwendet werden. Die Abfragevariablen werden an die Anfrage mit einem Semikolon (;) unter Verwendung des Variablennamens und -werts angehängt. Mehrere Variablen werden durch Semikolons getrennt.
Die Struktur sieht wie folgt aus:
<AEM_HOST>/graphql/execute.json/<PERSISTENT_QUERY_PATH>;variable1=value1;variable2=value2
Die folgende Abfrage enthält beispielsweise die Variable activity, um eine Liste nach einem Aktivitätswert zu filtern:
query getAdventuresByActivity($activity: String!) {
adventureList (filter: {
adventureActivity: {
_expressions: [
{
value: $activity
}
]
}
}){
items {
_path
adventureTitle
adventurePrice
adventureTripLength
}
}
}
Aus dieser Abfrage kann unter einem Pfad wknd/adventures-by-activity eine persistente Abfrage erstellt werden. Um die persistente Abfrage für activity=Camping aufzurufen, müsste die Anfrage wie folgt aussehen:
<AEM_HOST>/graphql/execute.json/wknd/adventures-by-activity%3Bactivity%3DCamping
Die UTF-8-Kodierung %3B ist für ;, und %3D ist die Kodierung für =. Die Abfragevariablen und alle Sonderzeichen müssen ordnungsgemäß kodiert sein, damit die persistierte Abfrage ausgeführt wird.
Verwenden von Abfragevariablen – Best Practices
Bei der Verwendung von Variablen in Abfragen sollten einige Best Practices befolgt werden:
-
Kodierung
Als allgemeine Vorgehensweise wird immer empfohlen, alle Sonderzeichen zu kodieren, z. B.;,=,?,&und weitere. -
Semikolon
Persistierte Abfragen, die mehrere Variablen verwenden (die durch Semikolons getrennt sind), müssen Folgendes aufweisen:- die kodierten Semikolons (
%3B); durch die Kodierung der URL wird dies auch erreicht, - oder ein Semikolon, das am Ende der Abfrage hinzugefügt wird.
- die kodierten Semikolons (
-
CACHE_GRAPHQL_PERSISTED_QUERIES
WennCACHE_GRAPHQL_PERSISTED_QUERIESfür den Dispatcher aktiviert ist, werden Parameter, die die Zeichen/oder\in ihrem Wert enthalten, auf Dispatcher-Ebene zweimal kodiert.
So vermeiden Sie diese Situation:-
Aktivieren Sie
DispatcherNoCanonURLauf dem Dispatcher.
Dadurch wird der Dispatcher angewiesen, die ursprüngliche URL an AEM weiterzuleiten, sodass doppelte Kodierungen vermieden werden.
Diese Einstellung funktioniert derzeit nur für dievhost-Ebene. Wenn Sie also bereits über Dispatcher-Konfigurationen zum Umschreiben von URLs verfügen (z. B. bei Verwendung gekürzter URLs), benötigen Sie möglicherweise einen separatenvhostfür persistierte Abfrage-URLs. -
Senden Sie die Zeichen
/oder\nicht kodiert.
Stellen Sie beim Aufrufen der persistierten Abfrage-URL sicher, dass alle/- oder\-Zeichen im Wert persistierter Abfragevariablen unkodiert bleiben.NOTEDiese Option wird nur empfohlen, wenn dieDispatcherNoCanonURL-Lösung aus irgendeinem Grund nicht implementiert werden kann.
-
-
CACHE_GRAPHQL_PERSISTED_QUERIESWenn
CACHE_GRAPHQL_PERSISTED_QUERIESfür den Dispatcher aktiviert ist, kann das;-Zeichen nicht im Wert einer Variable verwendet werden.
Caching persistierter Abfragen
Persistierte Abfragen werden empfohlen, da sie auf der Dispatcher- und CDN-Ebene zwischengespeichert werden können, was letztendlich die Leistung der anfragenden Client-Anwendung verbessert.
Standardmäßig macht AEM zwischengespeicherte Inhalte, die auf einer TTL (Time To Live)-Definition basieren, ungültig. Diese TTLs können durch die folgenden Parameter definiert werden. Auf diese Parameter kann auf verschiedene Weise zugegriffen werden, wobei die Namen je nach verwendetem Mechanismus variieren:
max-agecache-control : max-agecacheControlMaxAgegraphqlCacheControls-maxagesurrogate-control : max-agesurrogateControlMaxAgegraphqlSurrogateControlstale-while-revalidatesurrogate-control : stale-while-revalidatesurrogateControlStaleWhileRevalidategraphqlStaleWhileRevalidatestale-if-errorsurrogate-control : stale-if-errorsurrogateControlStaleIfErrorgraphqlStaleIfErrorAuthoring-Instanzen
Für Authoring-Instanzen sind die Standardwerte:
max-age: 60s-maxage: 60stale-while-revalidate: 86400stale-if-error: 86400
Diese:
-
kann nicht mit Folgendem überschrieben werden:
- OSGi-Konfiguration
-
kann mit Folgendem überschrieben werden:
- eine Anfrage, die HTTP-Kopfzeilen-Einstellungen mithilfe von cURL definiert; sie sollte geeignete Einstellungen für
cache-controlund/odersurrogate-controlenthalten; Beispiele finden Sie unter Verwaltung des Cache auf der Ebene der persistierten Abfrage - wenn Sie Werte im Kopfzeilen-Dialog der GraphiQL-IDE angeben
- eine Anfrage, die HTTP-Kopfzeilen-Einstellungen mithilfe von cURL definiert; sie sollte geeignete Einstellungen für
Veröffentlichungsinstanzen
Für Publishing-Instanzen sind die Standardwerte:
max-age: 60s-maxage: 7200stale-while-revalidate: 86400stale-if-error: 86400
Diese können auf folgende Art überschrieben werden:
-
auf der Ebene der persistierten Abfrage; hierzu gehört das Senden der Abfrage an AEM mithilfe von cURL in Ihrer Befehlszeilenschnittstelle und das Veröffentlichen der persistierten Abfrage.
Verwalten von HTTP-Cache-Kopfzeilen in der GraphiQL-IDE
Die GraphiQL-IDE – Siehe Speichern persistierter Abfragen
Verwalten des Caches auf der Ebene der persistierten Abfrage
Dazu müssen Sie die Abfrage mithilfe von cURL in Ihrer Befehlszeilenschnittstelle an AEM senden.
Ein Beispiel für die PUT-Methode (erstellen):
curl -u admin:admin -X PUT \
--url "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-max-age" \
--header "Content-Type: application/json" \
--data '{ "query": "{articleList { items { _path author } } }", "cache-control": { "max-age": 300 }, "surrogate-control": {"max-age":600, "stale-while-revalidate":1000, "stale-if-error":1000} }'
Ein Beispiel für die POST-Methode (aktualisieren):
curl -u admin:admin -X POST \
--url "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-max-age" \
--header "Content-Type: application/json" \
--data '{ "query": "{articleList { items { _path author } } }", "cache-control": { "max-age": 300 }, "surrogate-control": {"max-age":600, "stale-while-revalidate":1000, "stale-if-error":1000} }'
Die cache-control kann zum Zeitpunkt der Erstellung (PUT) oder später (z. B. über eine POST-Anfrage) festgelegt werden. Die Cache-Steuerung ist beim Erstellen der persistenten Abfrage optional, da AEM den Standardwert bereitstellen kann. Siehe Persistieren einer GraphQL-Abfrage, für ein Beispiel der Persistierung einer Abfrage mit cURL.
Verwalten des Caches mit Cloud Manager-Variablen
Cloud Manager-Umgebungsvariablen können mit Cloud Manager definiert werden, um die erforderlichen Werte zu definieren:
graphqlStaleIfErrorgraphqlSurrogateControlVerwalten des Caches mit einer OSGi-Konfiguration
Um den Cache global zu verwalten, können Sie die OSGi-Einstellungen für die Konfiguration des persistierten Abfrage-Service konfigurieren.
NOTENOTEDie standardmäßige OSGi-Konfiguration für Veröffentlichungsinstanzen:
-
liest die Cloud Manager-Variablen, falls verfügbar:
OSGi-Konfigurationseigenschaftliest dieCloud Manager-VariablecacheControlMaxAgeliestgraphqlCacheControlsurrogateControlMaxAgeliestgraphqlSurrogateControlsurrogateControlStaleWhileRevalidateliestgraphqlStaleWhileRevalidatesurrogateControlStaleIfErrorliestgraphqlStaleIfError -
und falls nicht verfügbar, verwendet die OSGi-Konfiguration die Standardwerte für Veröffentlichungsinstanzen.
Konfiguration des Abfrageantwort-Codes
Standardmäßig sendet der PersistedQueryServlet eine 200-Antwort, wenn er eine Abfrage ausführt, unabhängig vom tatsächlichen Ergebnis.
Sie können die OSGi-Einstellungen für die Konfiguration des Dienstes für persistierte Abfragen konfigurieren, um zu steuern, ob detailliertere Status-Codes vom Endpunkt /execute.json/persisted-query zurückgegeben werden, wenn ein Fehler in der persistierten Abfrage auftritt.
NOTEDas Feld Respond with application/graphql-response+json (responseContentTypeGraphQLResponseJson) kann nach Bedarf definiert werden:
-
false(Standardwert):
Es spielt keine Rolle, ob die persistierte Abfrage erfolgreich ist oder nicht. Der zurückgegebeneContent-Type-Header istapplication/jsonund die/execute.json/persisted-querygibt immer den Status-Code200zurück. -
true:
Der zurückgegebeneContent-Typeistapplication/graphql-response+jsonund der Endpunkt gibt den entsprechenden Antwort-Code zurück, wenn bei Ausführung der persistierten Abfrage irgendeine Art von Fehler auftritt:CodeBeschreibung200Erfolgreiche Antwort400Gibt an, dass Header fehlen oder dass ein Problem mit dem Pfad der persistierten Abfrage vorliegt. Beispiele: Konfigurationsname nicht angegeben, Suffix nicht angegeben und andere.
Siehe Fehlerbehebung – GraphQL-Endpunkt nicht konfiguriert.404Die angeforderte Ressource kann nicht gefunden werden. Beispiel: Der GraphQL-Endpunkt ist nicht auf dem Server verfügbar.
Siehe Fehlerbehebung – Fehlender Pfad in der von GraphQL persistierten Abfrage-URL.500Interner Server-Fehler. Beispiele: Validierungsfehler, Persistenzfehler und andere.NOTESiehe auch https://graphql.github.io/graphql-over-http/draft/#sec-Status-Codes
Codieren der Abfrage-URL zur Verwendung in einer Mobile-App
Damit die Abfrage-URL von einer Applikation verwendet werden kann, müssen alle Sonderzeichen, die beim Erstellen von Abfragevariablen verwendet werden – d. h. Semikolons (;), Gleichheitszeichen (=), Schrägstriche (/) – konvertiert werden, sodass die entsprechende UTF-8-Codierung verwendet wird.
Zum Beispiel:
curl -X GET \ "https://publish-p123-e456.adobeaemcloud.com/graphql/execute.json/wknd/adventure-by-path%3BadventurePath%3D%2Fcontent%2Fdam%2Fwknd%2Fen%2Fadventures%2Fbali-surf-camp%2Fbali-surf-camp"
Die URL kann in die folgenden Teile unterteilt werden:
/graphql/execute.json/wknd/adventure-by-path%3B;adventurePath%3D=%2F/%2Fcontent%2Fdam...Im Klartext sieht der Anfrage-URI wie folgt aus:
/graphql/execute.json/wknd/adventure-by-path;adventurePath=/content/dam/wknd/en/adventures/bali-surf-camp/bali-surf-camp
Um eine persistente Abfrage in einer Client-Anwendung zu verwenden, sollte für JavaScript, Java oder NodeJS das AEM-Headless-Client-SDK verwendet werden. Das Headless-Client-SDK codiert in der Anfrage automatisch alle Abfragevariablen entsprechend.
Übertragen einer persistenten Abfrage in die Produktionsumgebung
Persistente Abfragen sollten immer in einem AEM-Autoren-Service erstellt und dann in einem AEM-Veröffentlichungs-Service veröffentlicht (repliziert) werden. Häufig werden persistente Abfragen in niedrigeren Umgebungen wie lokalen Umgebungen oder Entwicklungsumgebungen erstellt und getestet. Anschließend müssen persistente Abfragen in Umgebungen höherer Ebene übertragen werden, um sie letztendlich in einer AEM-Publishing-Produktionsumgebung verfügbar zu machen, auf die Client-Anwendungen zugreifen können.
Verpacken von persistenten Abfragen
Persistente Abfragen können in AEM-Pakete integriert werden. AEM-Pakete können dann heruntergeladen und in verschiedenen Umgebungen installiert werden. AEM-Pakete können auch von einer AEM-Autorenumgebung in AEM-Veröffentlichungsumgebungen repliziert werden.
So erstellen Sie ein Paket:
- Navigieren Sie zu Tools > Bereitstellung > Pakete.
- Erstellen Sie ein neues Paket durch Tippen auf Paket erstellen. Dadurch wird ein Dialogfeld zum Definieren des Pakets geöffnet.
- Geben Sie im Dialogfeld zur Paketdefinition unter Allgemein einen Namen wie „wknd-persistent-queries“ ein.
- Geben Sie eine Versionsnummer wie „1.0“ ein.
- Fügen Sie unter Filter einen neuen Filter hinzu. Wählen Sie über die Pfadsuche den Ordner
persistentQueriesunterhalb der Konfiguration aus. Für die Konfiguration vonwkndlautet der vollständige Pfad beispielsweise/conf/wknd/settings/graphql/persistentQueries. - Wählen Sie Speichern aus, um die neue Paketdefinition zu speichern und das Dialogfeld zu schließen.
- Wählen Sie in der erstellten Paketdefinition die Schaltfläche Aufbauen.
Nachdem das Paket erstellt wurde, können Sie Folgendes tun:
- Das Paket herunterladen und in eine andere Umgebung hochladen.
- Das Paket replizieren, indem Sie auf Mehr > Replizieren tippen. Dadurch wird das Paket in der verbundenen AEM-Publishing-Umgebung repliziert.