AEM GraphQL-API zur Verwendung mit Inhaltsfragmenten :headding-anchor:graphql-api-for-use-with-content-fragments
Erfahren Sie, wie Sie Inhaltsfragmente in Adobe Experience Manager (AEM) mit der AEM GraphQL-API für die Headless-Bereitstellung von Inhalten verwenden.
Die mit Inhaltsfragmenten verwendete GraphQL-API von AEM basiert weitgehend auf der standardmäßigen Open-Source-GraphQL-API.
Die Verwendung der GraphQL-API in AEM ermöglicht die effiziente Bereitstellung von Inhaltsfragmenten an JavaScript-Clients in Headless CMS-Implementierungen:
- Vermeiden von iterativen API-Anfragen wie bei REST,
- Sicherstellen, dass die Bereitstellung auf die spezifischen Anforderungen beschränkt ist,
- Ermöglichen der Massenbereitstellung von genau dem, was zum Rendern als Antwort auf eine einzelne API-Anfrage benötigt wird.
- AEM Commerce nutzt Daten von einer Commerce-Plattform über GraphQL.
- AEM-Inhaltsfragmente stellen in Kombination mit der AEM-GraphQL-API (einer auf GraphQL basierenden benutzerdefinierten Implementierung) strukturierte Inhalte für die Verwendung in Ihren Programmen bereit.
Voraussetzungen :headding-anchor:prerequisites
Kunden und Kundinnen, die GraphQL verwenden, sollten das AEM-Inhaltsfragment mit GraphQL Index Package 1.0.5 installieren. Siehe Versionshinweise für weitere Informationen.
Die GraphQL-API :headding-anchor:graphql-api
GraphQL ist:
-
„…eine Abfragesprache für APIs und eine Laufzeitumgebung zur Erfüllung dieser Abfragen mit Ihren vorhandenen Daten. GraphQL bietet eine vollständige und verständliche Beschreibung der Daten in Ihrer API. Es gibt den Kundinnen und Kunden die Möglichkeit, genau das anzufordern, was sie brauchen, und nicht mehr, es erleichtert die Weiterentwicklung von APIs im Laufe der Zeit und ermöglicht leistungsstarke Entwickler-Tools.“.
Weitere Informationen finden Sie unter GraphQL.org
-
„…eine offene Spezifikation für eine flexible API-Schicht. Legen Sie GraphQL über Ihre bestehenden Back-Ends, um Produkte schneller als je zuvor zu erstellen…“.
Weitere Informationen finden Sie unter GraphQL entdecken.
-
„… eine Datenabfragesprache und -spezifikation, die 2012 intern von Facebook entwickelt wurde, bevor sie 2015 öffentlich als Open Source zur Verfügung gestellt wurde. Sie bietet eine Alternative zu REST-basierten Architekturen mit dem Ziel, die Produktivität von Entwicklern zu erhöhen und die Menge der übertragenen Daten zu minimieren. GraphQL wird von Hunderten von Unternehmen aller Größenordnungen in der Produktion eingesetzt …“
Siehe GraphQL Foundation.
Weitere Informationen zur GraphQL-API finden Sie in den folgenden Abschnitten (neben vielen anderen Ressourcen):
Die Implementierung von GraphQL für AEM basiert auf der standardmäßigen GraphQL-Java™-Bibliothek. Siehe:
GraphQL-Terminologie :headding-anchor:graphql-terminology
GraphQL verwendet Folgendes:
-
- Schemata werden von AEM basierend auf den Inhaltsfragmentmodellen generiert.
- GraphQL stellt mithilfe Ihrer Schemata die Typen und Vorgänge dar, die für die GraphQL-Implementierung für AEM zulässig sind.
-
-
Der Pfad in AEM, der auf GraphQL-Abfragen antwortet und Zugriff auf die GraphQL-Schemata bietet.
-
Weitere Informationen finden Sie unter Aktivieren des GraphQL-Endpunkts.
-
In der (GraphQL.org) Einführung in GraphQL finden Sie ausführliche Informationen, einschließlich der Best Practices.
GraphQL-Abfragetypen :headding-anchor:graphql-query-types
Mit GraphQL können Sie Abfragen für Folgendes durchführen:
-
Einen einzelnen Eintrag
-
Eine Liste von Einträgen
AEM bietet Funktionen zum Konvertieren von Abfragen (beide Typen) in persistierte Abfragen, die vom Dispatcher und CDN zwischengespeichert werden.
Best Practices für GraphQL-Abfragen (Dispatcher und CDN) :headding-anchor:graphql-query-best-practices
Persistierte Abfragen sind die empfohlene Methode für Veröffentlichungsinstanzen, da:
- sie zwischengespeichert werden
- sie zentral von AEM verwaltet werden
GraphQL-Abfragen über POST werden nicht empfohlen, da sie nicht zwischengespeichert werden. Daher ist der Dispatcher auf einer Standardinstanz so konfiguriert, dass er solche Abfragen blockiert.
GraphQL unterstützt zwar auch GET-Anfragen, diese Anfragen können jedoch Einschränkungen unterliegen (z. B. in Bezug auf die URL-Länge), die durch persistierte Abfragen vermieden werden können.
Weitere Informationen finden Sie unter Aktivieren der Caching-Funktion für persistierte Abfragen.
GraphiQL-Schnittstelle :headding-anchor:graphiql-interface
Eine Implementierung der GraphiQL-Standardschnittstelle steht zur Verwendung mit AEM-GraphQL zur Verfügung.
Über diese Schnittstelle können Sie Abfragen direkt eingeben und testen.
Beispiel:
http://localhost:4502/content/graphiql.html
Dies bietet Funktionen wie Syntaxhervorhebung, automatische Vervollständigung, automatische Vorschläge sowie einen Verlauf und eine Online-Dokumentation:
Anwendungsfälle für Autoren- und Veröffentlichungsumgebungen :headding-anchor:use-cases-author-publish-environments
Die Anwendungsfälle können vom Typ der AEM-Umgebung abhängen:
-
Veröffentlichungsumgebung; wird verwendet, um:
- Daten für das JS-Programm (Standardanwendungsfall) abzufragen
-
Autorenumgebung; wird verwendet, um:
-
Daten für „Content-Management-Zwecke“ abzufragen:
- GraphQL in AEM ist eine schreibgeschützte API.
- Die REST-API kann für CR(u)D-Vorgänge verwendet werden.
-
Berechtigungen :headding-anchor:permission
Die Berechtigungen sind für den Zugriff auf Assets erforderlich.
GraphQL-Abfragen werden mit der Berechtigung der AEM-Benutzenden der zugrunde liegenden Anfrage ausgeführt. Wenn die Benutzenden auf einige (als Assets gespeicherte) Fragmente keinen Lesezugriff haben, werden diese nicht Teil der Ergebnismenge.
Außerdem benötigen die Benutzenden Zugriff auf einen GraphQL-Endpunkt, um GraphQL-Abfragen ausführen zu können.
Schema-Generierung :headding-anchor:schema-generation
GraphQL ist eine typisierte API, was bedeutet, dass die Daten klar strukturiert und nach Typ geordnet sein müssen.
Die GraphQL-Spezifikation enthält eine Reihe von Richtlinien zum Erstellen einer robusten API zum Abfragen von Daten in einer bestimmten Instanz. Um diese Richtlinien zu vervollständigen, muss ein Client das Schema abrufen, das alle für eine Abfrage erforderlichen Typen enthält.
Bei Inhaltsfragmenten basieren die GraphQL-Schemata (Struktur und Typen) auf aktivierten Inhaltsfragmentmodellen und deren Datentypen.
Wenn Benutzende beispielsweise ein Inhaltsfragmentmodell mit dem Namen Article
erstellen, generiert AEM den GraphQL-Typ ArticleModel
. Die Felder dieses Typs entsprechen den im Modell definierten Feldern und Datentypen. Außerdem werden einige Einstiegspunkte für Abfragen erstellt, die für diesen Typ gelten, z. B. articleByPath
oder articleList
.
-
Ein Inhaltsfragmentmodell:
-
Das entsprechende GraphQL-Schema (Ausgabe aus der automatischen GraphiQL-Dokumentation):
Dieses Bild zeigt, dass der generierte Typ
ArticleModel
mehrere Felder enthält.-
Drei von ihnen wurden auf Benutzerseite kontrolliert:
author
,main
, undreferencearticle
. -
Die anderen Felder wurden automatisch von AEM hinzugefügt und stellen hilfreiche Methoden dar, um Informationen zu einem bestimmten Inhaltsfragment bereitzustellen. In diesem Beispiel sind dies
(die Helferfelder)_path
,_metadata
,_variations
.
-
-
Nachdem ein Benutzer ein Inhaltsfragment basierend auf dem Modell „Article“ erstellt hat, kann es über GraphQL abgefragt werden. Beispiele finden Sie in den Beispielabfragen (basierend auf einer Beispielstruktur für Inhaltsfragmente zur Verwendung mit GraphQL).
In GraphQL für AEM ist das Schema flexibel. Diese Flexibilität bedeutet, dass es jedes Mal, wenn ein Inhaltsfragmentmodell erstellt, aktualisiert oder gelöscht wird, automatisch generiert wird. Die Datenschema-Caches werden auch aktualisiert, wenn Sie ein Inhaltsfragmentmodell aktualisieren.
Der Sites GraphQL-Service überwacht (im Hintergrund) alle Änderungen, die an einem Inhaltsfragmentmodell vorgenommen werden. Wenn Aktualisierungen erkannt werden, wird nur dieser Teil des Schemas neu generiert. Diese Optimierung spart Zeit und sorgt für Stabilität.
Wenn Sie zum Beispiel:
-
ein Paket installieren, das
Content-Fragment-Model-1
undContent-Fragment-Model-2
enthält:- GraphQL-Typen werden für
Model-1
undModel-2
generiert.
- GraphQL-Typen werden für
-
Ändern Sie anschließend
Content-Fragment-Model-2
:-
Nur der GraphQL-Typ
Model-2
wird aktualisiert. -
Model-1
hingegen bleibt unverändert.
-
Das Schema wird über denselben Endpunkt wie die GraphQL-Abfragen bereitgestellt, wobei der Client die Tatsache behandelt, dass das Schema mit der GQLschema
-Erweiterung aufgerufen wird. Die Durchführung einer einfachen GET
-Anfrage auf /content/cq:graphql/global/endpoint.GQLschema
führt beispielsweise zur Ausgabe des Schemas mit dem Inhaltstyp: text/x-graphql-schema;charset=iso-8859-1
.
Schemagenerierung – Nicht veröffentlichte Modelle :headding-anchor:schema-generation-unpublished-models
Wenn Inhaltsfragmente verschachtelt sind, kann es vorkommen, dass ein übergeordnetes Inhaltsfragmentmodell veröffentlicht wird, ein referenziertes Modell jedoch nicht.
Wenn dies geschieht, generiert AEM ein unvollständiges Schema für das übergeordnete Inhaltsfragmentmodell. Das bedeutet, dass die Fragmentreferenz, die von dem unveröffentlichten Modell abhängt, aus dem Schema entfernt wird.
Felder :headding-anchor:fields
Innerhalb des Schemas gibt es einzelne Felder, die zwei grundlegenden Kategorien angehören:
-
Von Ihnen generierte Felder.
Eine Auswahl von Datentypen wird verwendet, um Felder basierend auf der Konfiguration Ihres Inhaltsfragmentmodells zu erstellen. Die Feldnamen werden aus dem Feld Eigenschaftsname des Datentyps entnommen.
- Auch die Einstellung Rendern als ist zu beachten, da Benutzende bestimmte Datentypen konfigurieren können. Beispielsweise kann ein einzeiliges Textfeld so konfiguriert werden, dass es mehrere einzeilige Texte enthält, indem
multifield
aus dem Dropdown-Menü ausgewählt wird.
- Auch die Einstellung Rendern als ist zu beachten, da Benutzende bestimmte Datentypen konfigurieren können. Beispielsweise kann ein einzeiliges Textfeld so konfiguriert werden, dass es mehrere einzeilige Texte enthält, indem
-
GraphQL für AEM generiert auch eine Reihe von Hilfsfeldern.
Diese Felder werden verwendet, um ein Inhaltsfragment zu identifizieren oder um weitere Informationen zu einem Inhaltsfragment abzurufen.
Datentypen :headding-anchor:data-types
GraphQL für AEM unterstützt eine Liste von Typen. Alle unterstützten Datentypen für Inhaltsfragmentmodelle und die entsprechenden GraphQL-Typen werden dargestellt:
String
, [String]
String
Float
, [Float]
Boolean
Calendar
onlyDate
, onlyTime
, dateTime
String
[String]
String
Einzelnes Feld:
Model
– Modelltyp, direkt referenziertMultifeld, mit einem referenzierten Typ:
[Model]
: Array vom Typ Model
, direkt referenziert von ArrayMultifeld, mit mehreren referenzierten Typen:
[AllFragmentModels]
: Array aller Modelltypen, referenziert von Array mit VereinigungstypHilfsfelder :headding-anchor:helper-fields
Zusätzlich zu den Datentypen für benutzergenerierte Felder generiert GraphQL für AEM auch mehrere Hilfsfelder, um ein Inhaltsfragment zu identifizieren oder zusätzliche Informationen über ein Inhaltsfragment bereitzustellen.
Diese Hilfsfelder sind durch ein vorangestelltes _
gekennzeichnet, um zu unterscheiden, was vom Benutzer bzw. von der Benutzerin definiert und was automatisch generiert wurde.
Pfad :headding-anchor:path
Das Pfadfeld wird in AEM GraphQL als Kennung verwendet. Es stellt den Pfad des Inhaltsfragment-Assets im AEM Repository dar. Dieser Pfad wird als Kennung eines Inhaltsfragments gewählt, da er:
- innerhalb von AEM eindeutig ist,
- leicht abgerufen werden kann.
Der folgende Code zeigt die Pfade aller Inhaltsfragmente an, die auf der Grundlage des Inhaltsfragmentmodells Person
erstellt wurden.
{
personList {
items {
_path
}
}
}
Um ein einzelnes Inhaltsfragment eines bestimmten Typs abzurufen, müssen Sie zunächst auch dessen Pfad bestimmen. Zum Beispiel:
{
authorByPath(_path: "/content/dam/path/to/fragment/john-doe") {
item {
_path
firstName
name
}
}
}
Siehe Beispielabfrage – ein Einzelstadtfragment.
Metadaten :headding-anchor:metadata
Mit GraphQL stellt AEM auch die Metadaten eines Inhaltsfragments zur Verfügung. Metadaten sind Informationen, die ein Inhaltsfragment beschreiben, z. B.:
- der Titel eines Inhaltsfragments
- den Miniaturansichtspfad
- die Beschreibung eines Inhaltsfragments
- und das Erstellungsdatum, unter anderem.
Da Metadaten über den Schema-Editor generiert werden und daher keine bestimmte Struktur haben, wurde der GraphQL-Typ TypedMetaData
implementiert, um die Metadaten eines Inhaltsfragments anzuzeigen. Die TypedMetaData
gibt die nach den folgenden Skalartypen gruppierten Informationen preis:
stringMetadata:[StringMetadata]!
stringArrayMetadata:[StringArrayMetadata]!
intMetadata:[IntMetadata]!
intArrayMetadata:[IntArrayMetadata]!
floatMetadata:[FloatMetadata]!
floatArrayMetadata:[FloatArrayMetadata]!
booleanMetadata:[BooleanMetadata]!
booleanArrayMetadata:[booleanArrayMetadata]!
calendarMetadata:[CalendarMetadata]!
calendarArrayMetadata:[CalendarArrayMetadata]!
Jeder Skalartyp repräsentiert entweder ein einzelnes Name-Wert-Paar oder ein Array von Name-Wert-Paaren, wobei der Wert dieses Paares dem Typ entspricht, in dem er gruppiert wurde.
Wenn Sie zum Beispiel den Titel eines Inhaltsfragments abrufen möchten, ist diese Eigenschaft eine Zeichenfolgeneigenschaft, sodass Sie alle Zeichenfolgen-Metadaten abfragen würden:
Abfragen von Metadaten:
{
personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
item {
_path
_metadata {
stringMetadata {
name
value
}
}
}
}
}
Sie können alle GraphQL-Typen für Metadaten anzeigen, wenn Sie das generierte GraphQL-Schema anzeigen. Alle Modelltypen haben dieselben TypedMetaData
.
Beachten Sie, dass sich
StringMetadata
und StringArrayMetadata
beide auf das beziehen, was im Repository gespeichert ist, und nicht darauf, wie Sie sie abrufen.stringMetadata
aufrufen, erhalten Sie ein Array mit allen im Repository gespeicherten Metadaten als String
. Und wenn Sie stringArrayMetadata
aufrufen, erhalten Sie ein Array aller im Repository gespeicherten Metadaten als String[]
.Weitere Informationen finden Sie unter Beispielabfrage für Metadaten – Liste der Metadaten für Auszeichnungen mit dem Titel „GB“.
Varianten :headding-anchor:variations
Das Feld _variations
wurde implementiert, um die Abfrage der Varianten eines Inhaltsfragments zu vereinfachen. Zum Beispiel:
{
personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
item {
_variations
}
}
}
_variations
enthält keine master
-Varianten, weil die Originaldaten (in der Benutzeroberfläche als Master referenziert) technisch gesehen nicht als explizite Varianten betrachtet werden.Weitere Informationen finden Sie unter Beispielabfrage – Alle Städte mit einer gegebenen Variante.
GraphQL-Variablen :headding-anchor:graphql-variables
Mit GraphQL können Variablen in die Abfrage eingefügt werden. Weitere Informationen finden Sie in der GraphQL-Dokumentation für Variablen.
Um beispielsweise alle Inhaltsfragmente vom Typ Article
abzurufen, die eine bestimmte Variante aufweisen, können Sie die Variable variation
in GraphiQL angeben.
### query
query GetArticlesByVariation($variation: String!) {
articleList(variation: $variation) {
items {
_path
author
_variations
}
}
}
### in query variables
{
"variation": "uk"
}
GraphQL-Anweisungen :headding-anchor:graphql-directives
In GraphQL besteht die Möglichkeit, die Abfrage basierend auf Variablen zu ändern, die als GraphQL-Anweisungen bezeichnet werden.
Sie können beispielsweise das Feld adventurePrice
basierend auf einer Variablen includePrice
in eine Abfrage für alle AdventureModels
einfügen.
### query
query GetAdventureByType($includePrice: Boolean!) {
adventureList {
items {
adventureTitle
adventurePrice @include(if: $includePrice)
}
}
}
### in query variables
{
"includePrice": true
}
Filtern :headding-anchor:filtering
Sie können auch Filterung in Ihren GraphQL-Abfragen verwenden, um bestimmte Daten zurückzugeben.
Beim Filtern wird eine Syntax verwendet, die auf logischen Operatoren und Ausdrücken basiert.
Der kleinste Teil ist ein einzelner Ausdruck, der auf den Inhalt eines bestimmten Felds angewendet werden kann. Er vergleicht den Inhalt des Felds mit einem gegebenen konstanten Wert.
Der folgende Ausdruck würde zum Beispiel den Inhalt des Feldes mit dem Wert some text
vergleichen und wäre erfolgreich, wenn der Inhalt dem Wert entspricht. Andernfalls schlägt der Ausdruck fehl:
{
value: "some text"
_op: EQUALS
}
Die folgenden Operatoren können verwendet werden, um Felder mit einem bestimmten Wert zu vergleichen:
EQUALS
String
, ID
, Boolean
EQUALS_NOT
String
, ID
CONTAINS
String
{ value: "mas", _op: CONTAINS }
entspricht Christmas
, Xmas
, master
, …)CONTAINS_NOT
String
STARTS_WITH
ID
{ value: "/content/dam/", _op: STARTS_WITH
entspricht /content/dam/path/to/fragment
, aber nicht /namespace/content/dam/something
)EQUAL
Int
, Float
UNEQUAL
Int
, Float
GREATER
Int
, Float
GREATER_EQUAL
Int
, Float
LOWER
Int
, Float
LOWER_EQUAL
Int
, Float
AT
Calendar
, Date
, Time
NOT_AT
Calendar
, Date
, Time
BEFORE
Calendar
, Date
, Time
AT_OR_BEFORE
Calendar
, Date
, Time
AFTER
Calendar
, Date
, Time
AT_OR_AFTER
Calendar
, Date
, Time
Bei einigen Typen können Sie auch zusätzliche Optionen angeben, mithilfe derer die Auswertung eines Ausdrucks geändert werden kann:
_ignoreCase
String
time
entspricht z. B. TIME
, time
, tImE
, …_sensitiveness
Float
float
-Werte, die als identisch betrachtet werden (um technische Einschränkungen aufgrund der internen Darstellung von float
-Werten zu umgehen; sollte vermieden werden, da diese Option negative Auswirkungen auf die Leistung haben kannAusdrücke können mithilfe eines logischen Operators (_logOp
) zu einer Gruppe kombiniert werden:
OR
– die Ausdrucksgruppe ist erfolgreich, wenn mindestens ein Ausdruck erfolgreich istAND
– die Ausdrucksgruppe ist erfolgreich, wenn alle Ausdrücke erfolgreich sind (Standard)
Jedes Feld kann anhand einer eigenen Ausdrucksgruppe gefiltert werden. Die Ausdrucksgruppen aller im Filterargument erwähnten Felder werden schließlich durch einen eigenen logischen Operator kombiniert.
Eine Filterdefinition (als das filter
-Argument an eine Abfrage übergeben) enthält:
- Eine Unterdefinition für jedes Feld (auf das Feld kann über seinen Namen zugegriffen werden, z. B. gibt es ein
lastName
-Feld im Filter für daslastName
-Feld im Daten(feld)typ) - Jede Unterdefinition enthält das
_expressions
-Array, das die Ausdrucksgruppe bereitstellt, und das_logOp
-Feld, das den logischen Operator definiert, mit dem die Ausdrücke kombiniert werden sollten - Jeder Ausdruck wird durch den Wert (
value
-Feld) und den Operator (_operator
-Feld) definiert, mit dem der Inhalt eines Felds verglichen werden soll
Sie können _logOp
weglassen, wenn Sie Elemente mit AND
kombinieren wollen, und _operator
, wenn Sie auf Gleichheit prüfen wollen, da diese Werte Standardwerte sind.
Das folgende Beispiel zeigt eine vollständige Abfrage, die alle Personen filtert, die über eine lastName
von Provo
verfügen oder sjö
enthalten, ohne Beachtung von Groß-/Kleinschreibung:
{
authorList(filter: {
lastname: {
_logOp: OR
_expressions: [
{
value: "sjö",
_operator: CONTAINS,
_ignoreCase: true
},
{
value: "Provo"
}
]
}
}) {
items {
lastName
firstName
}
}
}
Wenn eine GraphQL-Abfrage zum Filtern von Ergebnissen mit optionalen Variablen ausgeführt wird und kein bestimmter Wert für die optionale Variable angegeben ist, wird die Variable bei der Filterbewertung ignoriert. Das bedeutet, dass die Abfrageergebnisse alle Werte (die null
und nicht null
sind) für die mit der Filtervariablen verknüpfte Eigenschaft enthalten.
null
-Wert explizit für eine solche Variable angegeben ist, gleicht der Filter nur die null
-Werte für die entsprechende Eigenschaft ab.In der folgenden Abfrage wird beispielsweise kein Wert für die Eigenschaft lastName
angegeben:
query getAuthorsFilteredByLastName($authorLastName: String) {
authorList(filter:
{
lastName: {_expressions: {value: $authorLastName}
}}) {
items {
lastName
}
}
}
Alle Autorinnen und Autoren werden zurückgegeben:
{
"data": {
"authorList": {
"items": [
{
"lastName": "Hammer"
},
{
"lastName": "Provo"
},
{
"lastName": "Wester"
},
{
"lastName": null
},
...
]
}
}
}
Sie können zwar auch nach verschachtelten Feldern filtern, dies wird jedoch nicht empfohlen, da es zu Leistungsproblemen führen kann.
Weitere Beispiele finden Sie unter:
-
Details zu den Erweiterungen von GraphQL für AEM
-
Beispielabfragen unter Verwendung dieses Beispielinhalts und dieser Beispielstruktur
- Und Beispielinhalt und -struktur speziell für die Verwendung in Beispielabfragen
Sortieren :headding-anchor:sorting
Mit dieser Funktion können Sie die Abfrageergebnisse entsprechend einem bestimmten Feld sortieren.
Die Sortierkriterien:
-
ist eine durch Kommas getrennte Liste von Werten, die den Feldpfad darstellen
-
das erste Feld in der Liste definiert die primäre Sortierreihenfolge
- das zweite Feld wird verwendet, wenn zwei Werte des primären Sortierkriteriums gleich sind
- das dritte Feld wird verwendet, wenn die ersten beiden Kriterien gleich sind, usw.
-
gepunktete Notation, das heißt
field1.subfield.subfield
, usw.
-
-
mit optionaler Sortierrichtung
- ASC (aufsteigend) oder DESC (absteigend); standardmäßig wird ASC angewendet
- die Richtung kann pro Feld angegeben werden. Diese Fähigkeit bedeutet, dass Sie ein Feld in aufsteigender Reihenfolge sortieren können, ein anderes in absteigender Reihenfolge (name, firstName DESC)
Zum Beispiel:
query {
authorList(sort: "lastName, firstName") {
items {
firstName
lastName
}
}
}
Ein weiteres Beispiel:
{
authorList(sort: "lastName DESC, firstName DESC") {
items {
lastName
firstName
}
}
}
Sie können auch ein Feld innerhalb eines verschachtelten Fragments mithilfe des Formats nestedFragmentname.fieldname
sortieren.
Zum Beispiel:
query {
articleList(sort: "authorFragment.lastName") {
items {
title
authorFragment {
firstName
lastName
birthDay
}
slug
}
}
}
Paging :headding-anchor:paging
Mit dieser Funktion können Sie Paging für Abfragetypen durchführen, was eine Liste zurückgibt. Es werden zwei Methoden bereitgestellt:
offset
undlimit
in einerList
-Abfragefirst
undafter
in einerPaginated
-Abfrage
Listenabfrage – Versatz und Limit :headding-anchor:list-offset-limit
In einer ...List
-Abfrage können Sie offset
und limit
verwenden, um eine bestimmte Teilmenge der Ergebnisse zurückzugeben:
offset
: Gibt den ersten zurückzugebenden Datensatz anlimit
: Gibt die maximale Anzahl an zurückzugebenden Datensätzen an
Beispiel für die Ausgabe der Ergebnisseite, die bis zu fünf Artikel enthält, beginnend mit dem fünften Artikel aus der vollständigen Ergebnisliste:
query {
articleList(offset: 5, limit: 5) {
items {
authorFragment {
lastName
firstName
}
}
}
}
-
Für das Paging ist eine stabile Sortierreihenfolge erforderlich, damit es bei mehreren Abfragen, die verschiedene Seiten desselben Ergebnisses anfordern, korrekt funktioniert. Standardmäßig wird der Repository-Pfad jedes Elements des Ergebnissatzes verwendet, um sicherzustellen, dass die Reihenfolge immer gleich ist. Wenn eine andere Sortierreihenfolge verwendet wird und diese Sortierung nicht auf JCR-Abfrageebene durchgeführt werden kann, hat dies negative Auswirkungen auf die Leistung. Der Grund dafür ist, dass der gesamte Ergebnissatz in den Speicher geladen werden muss, bevor die Seiten bestimmt werden.
-
Je höher der Versatz, desto länger dauert es, die Elemente aus der vollständigen JCR-Abfrageergebnismenge zu überspringen. Eine alternative Lösung für große Ergebnissätze ist die Verwendung der paginierten Abfrage mit der
first
- undafter
-Methode.
Paginiete Abfrage – „first“ und „after“ :headding-anchor:paginated-first-after
Der Abfragetyp ...Paginated
verwendet die meisten ...List
-Abfragetypfunktionen (Filtern, Sortieren), verwendet jedoch anstelle von offset
/limit
-Argumenten die first
/after
-Argumente gemäß der Definition in der GraphQL-Cursor-Verbindungsspezifikation. Eine weniger formale Einführung finden Sie in der Einführung in GraphQL.
first
: Dien
ersten zurückzugebenden Elemente.
Der Standardwert lautet50
.
Der Maximalwert ist100
.after
: Der Cursor, der den Anfang der angeforderten Seite bestimmt. Das durch den Cursor dargestellte Element ist nicht in der Ergebnismenge enthalten. Der Cursor einer Position wird durch das Feldcursor
der Strukturedges
bestimmt.
Ein Beispiel für die Ausgabe einer Ergebnisseite mit bis zu fünf Abenteuern, beginnend mit dem angegebenen Cursor-Element in der vollständigen Ergebnisliste:
query {
adventurePaginated(first: 5, after: "ODg1MmMyMmEtZTAzMy00MTNjLThiMzMtZGQyMzY5ZTNjN2M1") {
edges {
cursor
node {
title
}
}
pageInfo {
endCursor
hasNextPage
}
}
}
-
Standardmäßig verwendet Paging die UUID des Repository-Knotens, der das Sortierungsfragment darstellt, um sicherzustellen, dass die Reihenfolge der Ergebnisse immer gleich ist. Wenn
sort
verwendet wird, wird die UUID implizit genutzt, um eine eindeutige Sortierung sicherzustellen, auch für zwei Elemente mit identischen Sortierschlüsseln. -
Aufgrund interner technischer Einschränkungen wird die Leistung beeinträchtigt, wenn die Sortierung und Filterung auf verschachtelte Felder angewendet wird. Verwenden Sie daher Filter-/Sortierfelder, die auf der Stammebene gespeichert sind. Diese Technik ist auch die empfohlene Methode, um große paginierte Ergebnismengen abzufragen.
Persistierte GraphQL-Abfragen – Aktivieren der Caching-Funktion im Dispatcher :headding-anchor:graphql-persisted-queries-enabling-caching-dispatcher
Das Caching persistierter Abfragen ist im Dispatcher standardmäßig nicht aktiviert. Eine Standardaktivierung ist nicht möglich, da Kundinnen und Kunden, die CORS (Cross-Origin Resource Sharing) mit mehreren Ursprüngen verwenden, ihre Dispatcher-Konfiguration überprüfen und möglicherweise aktualisieren müssen.
Vary
-Header nicht zwischen.Aktivieren der Caching-Funktion für persistierte Abfragen :headding-anchor:enable-caching-persisted-queries
Um das Caching persistierter Abfragen zu aktivieren, sind folgende Aktualisierungen an den Dispatcher-Konfigurationsdateien erforderlich:
-
<conf.d/rewrites/base_rewrite.rules>
code language-xml # Allow the dispatcher to be able to cache persisted queries - they need an extension for the cache file RewriteCond %{REQUEST_URI} ^/graphql/execute.json RewriteRule ^/(.*)$ /$1;.json [PT]
note note NOTE Der Dispatcher fügt das Suffix .json
zu allen persistierten Abfrage-URLs hinzu, damit das Ergebnis zwischengespeichert werden kann.Dadurch wird sichergestellt, dass die Abfrage den Anforderungen des Dispatchers für Dokumente entspricht, die zwischengespeichert werden können. Weitere Informationen finden Sie unter Wie gibt der Dispatcher Dokumente zurück? -
<conf.dispatcher.d/filters/ams_publish_filters.any>
code language-xml # Allow GraphQL Persisted Queries & preflight requests /0110 { /type "allow" /method '(GET|POST|OPTIONS)' /url "/graphql/execute.json*" }
CORS-Konfiguration im Dispatcher :headding-anchor:cors-configuration-in-dispatcher
Kundinnen und Kunden, die CORS-Anfragen verwenden, müssen möglicherweise ihre CORS-Konfiguration im Dispatcher überprüfen und aktualisieren.
-
Die
Origin
-Kopfzeile darf nicht über den Dispatcher an AEM Publish weitergeben werden:- Überprüfen Sie die
clientheaders.any
-Datei.
- Überprüfen Sie die
-
Stattdessen müssen CORS-Anfragen auf Dispatcher-Ebene im Hinblick auf zulässige Ursprünge ausgewertet werden. Dieser Ansatz stellt außerdem sicher, dass CORS-bezogene Kopfzeilen in allen Fällen korrekt an einem Ort festgelegt werden.
- Eine solche Konfiguration sollte der
vhost
-Datei hinzugefügt werden. Nachfolgend finden Sie eine Beispielkonfiguration. Zur Vereinfachung ist nur der CORS-bezogene Teil angegeben. Sie können sie an Ihre spezifischen Anwendungsfälle anpassen.
code language-xml <VirtualHost *:80> ServerName "publish" # ... <IfModule mod_headers.c> Header add X-Vhost "publish" ################## Start of the CORS specific configuration ################## SetEnvIfExpr "req_novary('Origin') == ''" CORSType=none CORSProcessing=false SetEnvIfExpr "req_novary('Origin') != ''" CORSType=cors CORSProcessing=true CORSTrusted=false SetEnvIfExpr "req_novary('Access-Control-Request-Method') == '' && %{REQUEST_METHOD} == 'OPTIONS' && req_novary('Origin') != '' " CORSType=invalidpreflight CORSProcessing=false SetEnvIfExpr "req_novary('Access-Control-Request-Method') != '' && %{REQUEST_METHOD} == 'OPTIONS' && req_novary('Origin') != '' " CORSType=preflight CORSProcessing=true CORSTrusted=false SetEnvIfExpr "req_novary('Origin') -strcmatch 'https://%{HTTP_HOST}*'" CORSType=samedomain CORSProcessing=false # For requests that require CORS processing, check if the Origin can be trusted SetEnvIfExpr "%{HTTP_HOST} =~ /(.*)/ " ParsedHost=$1 ################## Adapt the regex to match CORS origin for your environment SetEnvIfExpr "env('CORSProcessing') == 'true' && req_novary('Origin') =~ m#(https://.*.your-domain.tld(:\d+)?$)#" CORSTrusted=true # Extract the Origin header SetEnvIfNoCase ^Origin$ ^https://(.*)$ CORSTrustedOrigin=https://$1 # Flush If already set Header unset Access-Control-Allow-Origin Header unset Access-Control-Allow-Credentials # Trusted Header always set Access-Control-Allow-Credentials "true" "expr=reqenv('CORSTrusted') == 'true'" Header always set Access-Control-Allow-Origin "%{CORSTrustedOrigin}e" "expr=reqenv('CORSTrusted') == 'true'" Header always set Access-Control-Allow-Methods "GET" "expr=reqenv('CORSTrusted') == 'true'" Header always set Access-Control-Max-Age 1800 "expr=reqenv('CORSTrusted') == 'true'" Header always set Access-Control-Allow-Headers "Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers" "expr=reqenv('CORSTrusted') == 'true'" # Non-CORS or Not Trusted Header unset Access-Control-Allow-Credentials "expr=reqenv('CORSProcessing') == 'false' || reqenv('CORSTrusted') == 'false'" Header unset Access-Control-Allow-Origin "expr=reqenv('CORSProcessing') == 'false' || reqenv('CORSTrusted') == 'false'" Header unset Access-Control-Allow-Methods "expr=reqenv('CORSProcessing') == 'false' || reqenv('CORSTrusted') == 'false'" Header unset Access-Control-Max-Age "expr=reqenv('CORSProcessing') == 'false' || reqenv('CORSTrusted') == 'false'" # Always vary on origin, even if its not there. Header merge Vary Origin # CORS - send 204 for CORS requests which are not trusted RewriteCond expr "reqenv('CORSProcessing') == 'true' && reqenv('CORSTrusted') == 'false'" RewriteRule "^(.*)" - [R=204,L] ################## End of the CORS specific configuration ################## </IfModule> <Directory /> # ... </Directory> # ... </VirtualHost>
- Eine solche Konfiguration sollte der
GraphQL für AEM – Zusammenfassung der Erweiterungen :headding-anchor:graphql-extensions
Die grundlegende Funktionsweise von Abfragen mit GraphQL für AEM entspricht der Standard-GraphQL-Spezifikation. Für GraphQL-Abfragen mit AEM gibt es einige Erweiterungen:
-
Wenn Sie ein einzelnes Ergebnis benötigen:
- Verwenden Sie den Modellnamen; z. B. Stadt
-
Wenn Sie eine Ergebnisliste erwarten:
- Fügen Sie
List
zum Modellnamen hinzu, z. B.cityList
- Siehe Beispielabfrage – Alle Informationen zu allen Städten
Sie haben dann folgende Möglichkeiten:
-
ASC
: AufsteigendDESC
: Absteigend
-
Ergebnisseite zurückgeben mit einer der folgenden Möglichkeiten:
- Fügen Sie
-
Der Filter
includeVariations
ist imList
-Abfragetyp enthalten. Um Inhaltsfragmentvarianten in den Abfrageergebnissen abzurufen, muss der FilterincludeVariations
auftrue
gesetzt werden.note caution CAUTION Der Filter includeVariations
kann nicht zusammen mit dem systemgenerierten Feld_variation
verwendet werden. -
Wenn Sie ein logisches ODER verwenden möchten:
- Verwenden Sie
_logOp: OR
- Beispielabfrage – Alle Personen mit dem Namen „Jobs“ oder „Smith“
- Verwenden Sie
-
Es gibt ebenfalls ein logisches UND, es ist aber (oft) implizit.
-
Sie können Feldnamen abfragen, die den Feldern im Inhaltsfragmentmodell entsprechen.
-
Zusätzlich zu den Feldern aus Ihrem Modell gibt es einige vom System generierte Felder (denen ein Unterstrich vorangestellt ist):
-
Für Inhalte:
-
_locale
: Anzeigen der Sprache; basierend auf Language Manager -
_metadata
: Anzeigen von Metadaten für Ihr Fragment -
_model
: Zulassen von Abfragen nach einem Inhaltsfragmentmodell (Pfad und Titel) -
_path
: Der Pfad zu Ihrem Inhaltsfragment im Repository -
_reference
: Anzeigen von Verweisen; einschließlich Inline-Verweisen im Rich-Text-Editor -
_variation
: Anzeige bestimmter Varianten in Ihrem Inhaltsfragmentnote note NOTE Wenn die angegebene Variante für ein Inhaltsfragment nicht vorhanden, wird standardmäßig die primäre Variante (als Ersatz) zurückgegeben. note caution CAUTION Das systemgenerierte Feld _variation
kann nicht zusammen mit dem FilterincludeVariations
verwendet werden.- Weitere Informationen finden Sie unter Beispielabfrage – Alle Städte mit einer gegebenen Variante
-
_tags
: um die IDs von Inhaltsfragmenten oder Varianten anzuzeigen, die Tags enthalten; diese Liste ist ein Array voncq:tags
-Kennungen.- Siehe Beispielabfrage – Namen aller Städte, die als Städtereisen markiert sind
- Siehe Beispielabfrage für Inhaltsfragmentvarianten eines bestimmten Modells, an die ein bestimmtes Tag angehängt ist
note note NOTE Tags können auch durch Auflisten der Metadaten eines Inhaltsfragments abgefragt werden.
-
-
Und Operationen:
-
_operator
: bestimmte Operatoren anwenden:EQUALS
,EQUALS_NOT
,GREATER_EQUAL
,LOWER
,CONTAINS
,STARTS_WITH
-
_apply
: bestimmte Bedingungen anwenden; zum BeispielAT_LEAST_ONCE
-
_ignoreCase
: Groß-/Kleinschreibung bei der Abfrage ignorieren
-
-
-
GraphQL-Vereinigungstypen werden unterstützt:
- Verwenden Sie
... on
- Verwenden Sie
-
Fallback bei der Abfrage verschachtelter Fragmente:
- Wenn die angeforderte Variante nicht in einem verschachtelten Fragment vorhanden ist, wird die primäre Variante ausgegeben.
CORS-Filter :headding-anchor:cors-filter
Um auf den GraphQL-Endpunkt zuzugreifen, konfigurieren Sie eine CORS-Richtlinie im Git-Repository der Kundin bzw. des Kunden. Diese Konfiguration erfolgt durch Hinzufügen einer entsprechenden OSGi-CORS-Konfigurationsdatei für einen oder mehrere gewünschte Endpunkte.
Diese Konfiguration muss eine vertrauenswürdige Website-Herkunft alloworigin
oder alloworiginregexp
angeben, für die der Zugriff gewährt werden muss.
Um beispielsweise den Zugriff auf den GraphQL-Endpunkt und den Persistenzabfrage-Endpunkt für https://my.domain
zu gewähren, können Sie Folgendes verwenden:
{
"supportscredentials":true,
"supportedmethods":[
"GET",
"HEAD",
"POST"
],
"exposedheaders":[
""
],
"alloworigin":[
"https://my.domain"
],
"maxage:Integer":1800,
"alloworiginregexp":[
""
],
"supportedheaders":[
"Origin",
"Accept",
"X-Requested-With",
"Content-Type",
"Access-Control-Request-Method",
"Access-Control-Request-Headers"
],
"allowedpaths":[
"/content/_cq_graphql/global/endpoint.json",
"/graphql/execute.json/.*"
]
}
Wenn Sie einen Vanity-Pfad für den Endpunkt konfiguriert haben, können Sie ihn auch in allowedpaths
verwenden.
Referrer-Filter :headding-anchor:referrer-filter
Zusätzlich zur CORS-Konfiguration muss ein Referrer-Filter konfiguriert werden, um den Zugriff von Drittanbieter-Hosts zu ermöglichen.
Dieser Filter wird durch Hinzufügen einer entsprechenden OSGi Referrer-Filter-Konfigurationsdatei erstellt, die:
- einen vertrauenswürdigen Website-Hostnamen angibt (entweder
allow.hosts
oderallow.hosts.regexp
), - Zugriff auf diesen Hostnamen gewährt.
Um beispielsweise Zugriff auf Anfragen mit dem Referrer my.domain
zu gewähren, können Sie:
{
"allow.empty":false,
"allow.hosts":[
"my.domain"
],
"allow.hosts.regexp":[
""
],
"filter.methods":[
"POST",
"PUT",
"DELETE",
"COPY",
"MOVE"
],
"exclude.agents.regexp":[
""
]
}
- Nur Zugriff auf vertrauenswürdige Domains gewähren
- Sicherstellen, dass keine vertraulichen Informationen offengelegt werden
- Keine Platzhalter-Syntax [*] verwenden; diese Funktionalität deaktiviert den authentifizierten Zugriff auf den GraphQL-Endpunkt und macht ihn außerdem für die ganze Welt zugänglich.
Einschränkungen :headding-anchor:limitations
Zum Schutz vor potenziellen Problemen gibt es Standardbeschränkungen für Abfragen:
- Die Abfrage darf nicht mehr als 1 Million (1024 × 1024) Zeichen enthalten.
- Die Abfrage darf nicht mehr als 15.000 Token enthalten.
- Die Abfrage darf nicht mehr als 200.000 Whitespace-Token enthalten.
Außerdem müssen Sie Folgendes beachten:
-
Es wird ein Feldkonfliktfehler zurückgegeben, wenn Ihre GraphQL-Abfrage Felder mit demselben Namen in zwei (oder mehr) Modellen enthält und die folgenden Bedingungen erfüllt sind:
-
Etwa in folgendem Fall:
- Zwei (oder mehr Modelle) als mögliche Verweise werden verwendet, wenn sie im Inhaltsfragmentverweis als zulässiger Modelltyp definiert sind.
und:
- Diese beiden Modelle haben Felder mit einem gemeinsamen Namen. Das bedeutet, dass in beiden Modellen der gleiche Name vorkommt.
und
- Diese Felder weisen unterschiedliche Datentypen auf.
-
Zum Beispiel:
-
Wenn zwei (oder mehr) Fragmente mit verschiedenen Modellen (z. B.
M1
,M2
) als mögliche Verweise (Inhaltsverweis oder Fragmentverweis) aus einem anderen Fragment verwendet werden, z. B.Fragment1
MultiField/List
, -
und diese beiden Fragmente mit verschiedenen Modellen (
M1
,M2
) Felder mit demselben Namen, aber unterschiedlichen Typen haben.
Beispiel:M1.Title
alsText
M2.Title
alsText/MultiField
-
Dann tritt ein Feldkonfliktfehler auf, wenn die GraphQL-Abfrage das
Title
-Feld enthält.
-
-
Authentifizierung :headding-anchor:authentication
Siehe Authentifizierung für AEM-GraphQL-Remote-Abfragen in Inhaltsfragmenten.
Häufig gestellte Fragen :headding-anchor:faqs
Es wurden folgende Fragen aufgeworfen:
-
F: „Wie unterscheidet sich die GraphQL-API für AEM von der Query Builder-API?“
- A:
„Die AEM-GraphQL-API bietet vollständige Kontrolle über die JSON-Ausgabe und ist ein Industriestandard für die Abfrage von Inhalten.
In Zukunft plant AEM, in die AEM GraphQL-API zu investieren.“
- A:
Tutorial – Erste Schritte mit AEM Headless und GraphQL :headding-anchor:tutorial
Suchen Sie nach einem praktischen Tutorial? Lesen Sie das umfassende Tutorial Erste Schritte mit AEM Headless und GraphQL, in dem veranschaulicht wird, wie Inhalte mithilfe der GraphQL-APIs von AEM erstellt und verfügbar gemacht und von einer externen App in einem Headless CMS-Szenario verwendet werden.