Erfahren Sie, wie Sie Inhaltsfragmente in Adobe Experience Manager (AEM) mit der AEM GraphQL-API für die Bereitstellung Headless Content verwenden.
Die mit Inhaltsfragmenten verwendete GraphQL-API von AEM basiert stark 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:
GraphQL wird derzeit in zwei (separaten) Szenarien in Adobe Experience Manager (AEM) verwendet:
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, gibt Kunden die Möglichkeit, genau das abzufragen, was sie benötigen, und nicht mehr, macht es einfacher, APIs im Laufe der Zeit weiterzuentwickeln, und ermöglicht leistungsstarke Entwicklerwerkzeuge.“
Weitere Informationen finden Sie unter GraphQL.org
„…eine offene Spezifikation für eine flexible API-Schicht. Legen Sie GraphQL über Ihre bestehenden Backends, 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):
Unter graphql.org:
Unter graphql.com:
Die Implementierung von GraphQL für AEM basiert auf der standardmäßigen GraphQL-Java-Bibliothek. Siehe:
GraphQL verwendet Folgendes:
Der Pfad in AEM, der auf GraphQL-Abfragen antwortet und Zugriff auf die GraphQL-Schemas 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.
Mit GraphQL können Sie Abfragen für Folgendes durchführen:
Einen einzelnen Eintrag
Eine Liste von Einträgen
Sie können auch Folgendes ausführen:
Zusätzlich können Sie GraphQL-Abfragen mit der GraphiQL-IDE testen und debuggen.
Der Endpunkt ist der Pfad, der für den Zugriff auf GraphQL für AEM verwendet wird. Mit diesem Pfad können Sie (oder Ihr Programm):
Es gibt zwei Arten von Endpunkten in AEMٔ:
Der Inhaltsfragment-Editor kann zulassen, dass ein Inhaltsfragment einer Sites-Konfiguration (über Richtlinien) auf ein Inhaltsfragment einer anderen Sites-Konfiguration verweist.
In diesem Fall können nicht alle Inhalte mithilfe eines für eine Sites-Konfiguration spezifischen Endpunkts abgerufen werden.
Der Inhaltsautor sollte dieses Szenario steuern. Beispielsweise kann es nützlich sein, freigegebene Inhaltsfragmentmodelle unter die globale Sites-Konfiguration zu stellen.
Der Repository-Pfad des GraphQL für den globalen Endpunkt in AEM lautet:
/content/cq:graphql/global/endpoint
Ihr Programm kann den folgenden Pfad in der Anfrage-URL verwenden:
/content/_cq_graphql/global/endpoint.json
Um den GraphQL-Endpunkt für AEM zu aktivieren, gehen Sie folgendermaßen vor:
Um einen GraphQL-Endpunkt zu aktivieren, benötigen Sie zunächst eine entsprechende Konfiguration. Siehe Inhaltsfragmente – Konfigurations-Browser.
Wenn die Verwendung von Inhaltsfragmentmodellen nicht aktiviert wurde, ist die Option Erstellen nicht verfügbar.
So aktivieren Sie den entsprechenden Endpunkt:
Gehen Sie zu Tools, Assets und wählen Sie GraphQL aus.
Wählen Sie Erstellen.
Das Dialogfeld Neuen GraphQL-Endpunkt erstellen wird geöffnet. Hier können Sie Folgendes angeben:
Die folgende Warnung wird im Dialogfeld angezeigt:
Bestätigen Sie mit Erstellen.
Das Dialogfeld Nächste Schritte stellt einen direkten Link zur Sicherheitskonsole bereit, sodass Sie sicherstellen können, dass der neu erstellte Endpunkt über geeignete Berechtigungen verfügt.
Der Endpunkt ist für jeden zugänglich. Dies kann – insbesondere bei Veröffentlichungsinstanzen – Sicherheitsbedenken aufwerfen, da GraphQL-Abfragen eine hohe Server-Belastung verursachen können.
Sie können am Endpunkt geeignete ACLs für Ihr Programm einrichten.
Wählen Sie den neuen Endpunkt und Veröffentlichen aus, um ihn in allen Umgebungen vollständig verfügbar zu machen.
Der Endpunkt ist für jeden zugänglich.
Dies kann – insbesondere bei Veröffentlichungsinstanzen – Sicherheitsbedenken aufwerfen, da GraphQL-Abfragen eine hohe Server-Belastung verursachen können.
Sie müssen am Endpunkt geeignete ACLs für Ihren Anwendungsfall einrichten.
Eine Implementierung der GraphiQL-Standardschnittstelle steht zur Verwendung mit AEM-GraphQL zur Verfügung. Sie kann mit AEM installiert werden.
GraphiQL ist an den globalen Endpunkt gebunden (und funktioniert bei bestimmten Sites-Konfigurationen nicht mit anderen Endpunkten).
Ü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:
Die GraphiQL-Schnittstelle kann mit einem dedizierten Paket auf AEM installiert werden: dem Paket GraphiQL Content Package v0.0.6 (2021.3).
Das verfügbare Paket ist vollständig mit AEM 6.5.10.0 und AEM as a Cloud Service.
Die Anwendungsfälle können vom Typ AEM Umgebung abhängen:
Veröffentlichungsumgebung; wird verwendet, um:
Autorenumgebung; wird verwendet, um:
Die Berechtigungen sind diejenigen, die für den Zugriff auf Assets erforderlich sind.
GraphQL ist eine stark 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. Dazu muss ein Client das Schema abrufen, das alle für eine Abfrage erforderlichen Typen enthält.
Bei Inhaltsfragmenten basieren die GraphQL-Schemas (Struktur und Typen) auf aktivierten Inhaltsfragmentmodellen und deren Datentypen.
Alle GraphQL-Schemas (abgeleitet von Inhaltsfragmentmodellen, die aktiviert wurden) können über den GraphQL-Endpunkt gelesen werden.
Das bedeutet, dass Sie sicherstellen müssen, dass keine vertraulichen Daten verfügbar sind, da sie auf diese Weise an die Öffentlichkeit gelangen könnten. Dazu gehören beispielsweise Informationen, die als Feldnamen in der Modelldefinition vorhanden sein könnten.
Wenn ein Benutzer beispielsweise ein Inhaltsfragmentmodell mit dem Namen Article
erstellt hat, generiert AEM das Objekt article
, das dem Typ ArticleModel
entspricht. Die Felder dieses Typs entsprechen den im Modell definierten Feldern und Datentypen.
Ein Inhaltsfragmentmodell:
Das entsprechende GraphQL-Schema (Ausgabe aus der automatischen GraphiQL-Dokumentation):
Dies zeigt, dass der generierte Typ ArticleModel
mehrere Felder enthält.
Drei davon wurden vom Benutzer kontrolliert: author
, main
und referencearticle
.
Die anderen Felder wurden automatisch von AEM hinzugefügt und stellen hilfreiche Methoden dar, um Informationen zu einem bestimmten Inhaltsfragment bereitzustellen. In diesem Beispiel _path
, _metadata
und _variations
. Diese Hilfsfelder sind mit einem vorangestellten _
gekennzeichnet, um zu unterscheiden, was vom Benutzer definiert und was automatisch generiert wurde.
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. Dies bedeutet, dass es jedes Mal automatisch generiert wird, wenn ein Inhaltsfragmentmodell erstellt, aktualisiert oder gelöscht 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
und Content-Fragment-Model-2
enthält:
Model-1
und Model-2
generiert.anschließend Content-Fragment-Model-2
ändern:
Nur der GraphQL-Typ Model-2
wird aktualisiert.
Model-1
bleibt unverändert.
Dies ist wichtig, wenn Sie Massenaktualisierungen von Inhaltsfragmentmodellen über die REST-API oder auf andere Weise durchführen möchten.
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. Wenn Sie beispielsweise eine einfache GET
-Anfrage an /content/cq:graphql/global/endpoint.GQLschema
ausführen, wird das Schema mit dem Inhaltstyp ausgegeben: text/x-graphql-schema;charset=iso-8859-1
.
Wenn Inhaltsfragmente verschachtelt sind, kann es vorkommen, dass ein übergeordnetes Inhaltsfragmentmodell veröffentlicht wird, ein referenziertes Modell jedoch nicht.
Die AEM-Benutzeroberfläche verhindert dies, aber wenn die Veröffentlichung programmgesteuert oder mit Inhaltspaketen erfolgt, kann es vorkommen.
In diesem Fall generiert AEM ein unvollständiges Schema für das übergeordnete Inhaltsfragmentmodell. Das bedeutet, dass die Fragmentreferenz, die vom nicht veröffentlichten Modell abhängt, aus dem Schema entfernt wird.
Innerhalb des Schemas gibt es einzelne Felder, die zwei grundlegenden Kategorien angehören:
Von Ihnen generierte Felder.
Eine Auswahl von Feldtypen wird verwendet, um Felder basierend auf der Konfiguration des Inhaltsfragmentmodells zu erstellen. Die Feldnamen werden aus dem Feld Eigenschaftsname des Datentyps entnommen.
GraphQL für AEM generiert auch eine Reihe von Hilfsfeldern.
Diese werden verwendet, um ein Inhaltsfragment zu identifizieren oder um weitere Informationen zu einem Inhaltsfragment abzurufen.
GraphQL für AEM unterstützt eine Liste von Typen. Alle unterstützten Datentypen für Inhaltsfragmentmodelle und die entsprechenden GraphQL-Typen werden dargestellt:
Datentyp für Inhaltsfragmentmodelle | GraphQL-Typ | Beschreibung |
---|---|---|
Einzeilentext | Zeichenfolge, [Zeichenfolge] | Wird für einfache Zeichenfolgen wie Autorennamen, Ortsnamen usw. verwendet. |
Mehrzeilentext | Zeichenfolge | Wird für die Ausgabe von Text verwendet, z. B. für den Textkörper eines Artikels |
Zahl | Gleitkommazahl, [Gleitkommazahl] | Wird für die Anzeige von Gleitkommazahlen und regulären Zahlen verwendet |
Boolesch | Boolesch | Wird für die Anzeige von Kontrollkästchen → einfachen Wahr/Falsch-Aussagen verwendet |
Datum und Uhrzeit | Kalender | Wird verwendet, um Datum und Uhrzeit in einem ISO 8086-Format anzuzeigen. Je nach ausgewähltem Typ gibt es drei Varianten, die in AEM-GraphQL verwendet werden können: onlyDate , onlyTime , dateTime |
Aufzählung | Zeichenfolge | Wird verwendet, um eine Option aus einer Liste von Optionen anzuzeigen, die bei der Modellerstellung definiert wurde |
Tags | [Zeichenfolge] | Wird verwendet, um eine Liste von Zeichenfolgen anzuzeigen, die in AEM verwendete Tags darstellen |
Inhaltsreferenz | Zeichenfolge | Wird verwendet, um den Pfad zu einem anderen Asset in AEM anzuzeigen |
Fragmentreferenz | Ein Modelltyp | Wird verwendet, um auf ein anderes Inhaltsfragment eines bestimmten Modelltyps zu verweisen, das beim Erstellen des Modells definiert wurde |
Zusätzlich zu den Datentypen für benutzergenerierte Felder generiert GraphQL für AEM eine Reihe von Hilfsfeldern, um ein Inhaltsfragment zu identifizieren oder zusätzliche Informationen zu einem Inhaltsfragment bereitzustellen.
Das Feld „path“ (Pfad) wird in GraphQL als Bezeichner verwendet. Es stellt den Pfad des Inhaltsfragment-Assets im AEM Repository dar. Wir haben es als Bezeichner für ein Inhaltsfragment ausgewählt, da es:
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 auch zuerst dessen Pfad bestimmen. Beispiel:
{
personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
item {
_path
firstName
name
}
}
}
Siehe Beispielabfrage – ein Einzelstadtfragment.
Mit GraphQL stellt AEM auch die Metadaten eines Inhaltsfragments zur Verfügung. Metadaten sind die Informationen, die ein Inhaltsfragment beschreiben, z. B. der Titel eines Inhaltsfragments, der Pfad der Miniatur, die Beschreibung eines Inhaltsfragments, das Erstellungsdatum usw.
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. TypedMetaData
stellt die Informationen gruppiert nach den folgenden Skalartypen bereit:
Feld |
---|
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 beispielsweise den Titel eines Inhaltsfragments abrufen möchten, wissen wir, dass diese Eigenschaft eine Zeichenfolgeneigenschaft ist. Daher würden wir eine Abfrage für alle Zeichenfolgenmetadaten durchführen:
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
.
Unterschied zwischen normalen und Array-Metadaten
Beachten Sie, dass sich StringMetadata
und StringArrayMetadata
beide auf das beziehen, was im Repository gespeichert ist, und nicht darauf, wie Sie sie abrufen.
Wenn Sie beispielsweise das Feld stringMetadata
aufrufen, erhalten Sie ein Array aller im Repository gespeicherten Metadaten als String
und wenn Sie stringArrayMetadata
aufrufen, erhalten Sie ein Array aller Metadaten, die im Repository als String[]
gespeichert wurden.
Weitere Informationen finden Sie unter Beispielabfrage für Metadaten – Liste der Metadaten für Auszeichnungen mit dem Titel „GB“.
Das Feld _variations
wurde implementiert, um die Abfrage der Varianten eines Inhaltsfragments zu vereinfachen. Beispiel:
{
personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
item {
_variations
}
}
}
Weitere Informationen finden Sie unter Beispielabfrage – Alle Städte mit einer gegebenen Variante.
Mit GraphQL können Variablen in die Abfrage eingefügt werden. Weitere Informationen finden Sie in der GraphQL-Dokumentation zu 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
}
}
}
### in query variables
{
"variation": "uk"
}
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
}
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.
Beispielsweise werden mit der folgenden (einfachen) Abfrage alle Personen mit dem Namen Jobs
oder Smith
gefiltert:
query {
personList(filter: {
name: {
_logOp: OR
_expressions: [
{
value: "Jobs"
},
{
value: "Smith"
}
]
}
}) {
items {
name
firstName
}
}
}
Weitere Beispiele finden Sie unter:
Details zu den Erweiterungen von GraphQL für AEM
Beispielabfragen unter Verwendung dieses Beispielinhalts und dieser Beispielstruktur
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:
Wenn Sie eine Ergebnisliste erwarten:
List
zum Modellnamen hinzu, z. B. cityList
Wenn Sie ein logisches ODER verwenden möchten:
_logOp: OR
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 Inhaltsfragment
Und Operationen:
_operator
: bestimmte Operatoren anwenden; EQUALS
, EQUALS_NOT
, GREATER_EQUAL
, LOWER
, CONTAINS
, STARTS_WITH
_apply
: bestimmte Bedingungen anwenden; zum Beispiel AT_LEAST_ONCE
_ignoreCase
: Groß-/Kleinschreibung bei der Abfrage ignorieren
GraphQL-Vereinigungstypen werden unterstützt:
... on
Fallback bei der Abfrage verschachtelter Fragmente:
Nachdem eine Abfrage mit einer POST-Anfrage vorbereitet wurde, kann sie mit einer GET-Anfrage ausgeführt werden, die von HTTP-Caches oder einem CDN zwischengespeichert werden kann.
Dies ist erforderlich, da POST-Abfragen normalerweise nicht zwischengespeichert werden. Wenn Sie GET mit der Abfrage als Parameter verwenden, besteht ein erhebliches Risiko, dass der Parameter für HTTP-Services und Vermittler zu groß wird.
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:
Weitere Informationen finden Sie unter Aktivieren der Inhaltsfragmentfunktionen im Konfigurations-Browser.
Die GraphQL-Persistenzabfragen für die entsprechende Sites-Konfiguration müssen aktiviert werden.
Wenn es beispielsweise eine bestimmte Abfrage namens my-query
gibt, die ein my-model
-Modell aus der Sites-Konfiguration my-conf
verwendet:
my-conf
-spezifischen Endpunkt erstellen und die Abfrage wird dann wie folgt gespeichert:/conf/my-conf/settings/graphql/persistentQueries/my-query
global
-Endpunkt erstellen, die Abfrage wird dann jedoch wie folgt gespeichert:/conf/global/settings/graphql/persistentQueries/my-query
Hierbei handelt es sich um zwei verschiedene Abfragen, die unter verschiedenen Pfaden gespeichert werden.
Sie verwenden zufällig dasselbe Modell – aber über verschiedene Endpunkte.
Die folgenden Schritte sind erforderlich, um eine bestimmte Abfrage beizubehalten:
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 erneut 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.
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.
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:
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 Abfrage mit Parametern.
Beispiel:
$ curl -X POST \
-H 'authorization: Basic YWRtaW46YWRtaW4=' \
-H "Content-Type: application/json" \
"http://localhost:4502/graphql/execute.json/wknd/plain-article-query-parameters;apath=%2fcontent2fdam2fwknd2fen2fmagazine2falaska-adventure2falaskan-adventures;withReference=false"
$ curl -X GET \
"http://localhost:4502/graphql/execute.json/wknd/plain-article-query-parameters;apath=%2fcontent2fdam2fwknd2fen2fmagazine2falaska-adventure2falaskan-adventures;withReference=false"
Um die Abfrage bei der Veröffentlichung auszuführen, muss der zugehörige Persistenzbaum repliziert werden
Verwenden einer POST-Anfrage für die Replikation:
$curl -X POST http://localhost:4502/bin/replicate.json \
-H 'authorization: Basic YWRtaW46YWRtaW4=' \
-F path=/conf/wknd/settings/graphql/persistentQueries/plain-article-query \
-F cmd=activate
Verwenden eines Pakets:
/conf/wknd/settings/graphql/persistentQueries
).Verwenden eines Replikations-/Verteilungs-Tools:
/conf/wknd/settings/graphql/persistentQueries
) aus.Verwenden eines Workflows (über die Workflow-Starter-Konfiguration):
Sobald die Abfragekonfiguration veröffentlicht wurde, gelten dieselben Prinzipien, nur unter Verwendung des Veröffentlichungsendpunkts.
Für den anonymen Zugriff geht das System davon aus, dass „jeder“ über die ACL Zugriff auf die Abfragekonfiguration hat.
Ist dies nicht der Fall, kann sie nicht ausgeführt werden.
Alle Semikolons („;“) in den URLs müssen kodiert werden.
Beispiel: Wie in der Anfrage zum Ausführen einer persistenten Abfrage:
curl -X GET \ "http://localhost:4502/graphql/execute.json/wknd/plain-article-query-parameters%3bapath=%2fcontent2fdam2fwknd2fen2fmagazine2falaska-adventure2falaskan-adventures;withReference=false"
Für den Zugriff auf den GraphQL-Endpunkt über eine externe Website müssen Sie Folgendes konfigurieren:
Einen detaillierten Überblick über die CORS-Richtlinie zur gemeinsamen Nutzung von Ressourcen in AEM finden Sie unter Grundlegendes zur gemeinsamen Nutzung gemeinsamer Ressourcen (Cross-Origin Resource Sharing – CORS).
Um auf den GraphQL-Endpunkt zugreifen zu können, muss eine CORS-Richtlinie im Git-Repository des Kunden konfiguriert werden. Dazu wird eine entsprechende OSGi-CORS-Konfigurationsdatei für den/die gewünschten Endpunkt(e) hinzugefügt.
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.
Zusätzlich zur CORS-Konfiguration muss ein Referrer-Filter konfiguriert werden, um den Zugriff von Drittanbieter-Hosts zu ermöglichen.
Dazu fügen Sie eine entsprechende OSGi-Referrer-Filter-Konfigurationsdatei hinzu, die:
allow.hosts
oder allow.hosts.regexp
),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":[
""
]
}
Der Kunde ist für Folgendes verantwortlich:
Alle GraphQL-Schemas (abgeleitet von Inhaltsfragmentmodellen, die aktiviert wurden) können über den GraphQL-Endpunkt gelesen werden.
Das bedeutet, dass Sie sicherstellen müssen, dass keine vertraulichen Daten verfügbar sind, da sie auf diese Weise an die Öffentlichkeit gelangen könnten. Dazu gehören beispielsweise Informationen, die als Feldnamen in der Modelldefinition vorhanden sein könnten.
Siehe Authentifizierung für AEM-GraphQL-Remote-Abfragen in Inhaltsfragmenten.
Es wurden folgende Fragen aufgeworfen:
F: „Wie unterscheidet sich die GraphQL-API für AEM von der Query Builder-API?“
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 einem externen Programm in einem Headless CMS-Szenario verwendet werden.