AEM GraphQL-API zur Verwendung mit Inhaltsfragmenten 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:

Voraussetzungen 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 graphql-api

GraphQL ist:

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 graphql-terminology

GraphQL verwendet Folgendes:

In der (GraphQL.org) Einführung in GraphQL finden Sie ausführliche Informationen, einschließlich der Best Practices.

GraphQL-Abfragetypen graphql-query-types

Mit GraphQL können Sie Abfragen für Folgendes durchführen:

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) graphql-query-best-practices

Persistierte Abfragen sind die empfohlene Methode für Veröffentlichungsinstanzen, da:

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 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:

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 use-cases-author-publish-environments

Die Anwendungsfälle können vom Typ der AEM-Umgebung abhängen:

Berechtigungen 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 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.

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:

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 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 fields

Innerhalb des Schemas gibt es einzelne Felder, die zwei grundlegenden Kategorien angehören:

Datentypen 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:

Hilfsfelder 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 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:

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 metadata

Mit GraphQL stellt AEM auch die Metadaten eines Inhaltsfragments zur Verfügung. Metadaten sind Informationen, die ein Inhaltsfragment beschreiben, z. B.:

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:

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.

Weitere Informationen finden Sie unter Beispielabfrage für Metadaten – Liste der Metadaten für Auszeichnungen mit dem Titel „GB“.

Varianten 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
    }
  }
}

Weitere Informationen finden Sie unter Beispielabfrage – Alle Städte mit einer gegebenen Variante.

GraphQL-Variablen 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 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 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:

Bei einigen Typen können Sie auch zusätzliche Optionen angeben, mithilfe derer die Auswertung eines Ausdrucks geändert werden kann:

Ausdrücke können mithilfe eines logischen Operators (_logOp) zu einer Gruppe kombiniert werden:

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:

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.

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:

Sortieren sorting

Mit dieser Funktion können Sie die Abfrageergebnisse entsprechend einem bestimmten Feld sortieren.

Die Sortierkriterien:

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 paging

Mit dieser Funktion können Sie Paging für Abfragetypen durchführen, was eine Liste zurückgibt. Es werden zwei Methoden bereitgestellt:

Listenabfrage – Versatz und Limit list-offset-limit

In einer ...List-Abfrage können Sie offset und limit verwenden, um eine bestimmte Teilmenge der Ergebnisse zurückzugeben:

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
      }
    }
  }
}

Paginiete Abfrage – „first“ und „after“ 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.

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
        }
    }
}

Persistierte GraphQL-Abfragen – Aktivieren der Caching-Funktion im Dispatcher 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.

Aktivieren der Caching-Funktion für persistierte Abfragen enable-caching-persisted-queries

Um das Caching persistierter Abfragen zu aktivieren, sind folgende Aktualisierungen an den Dispatcher-Konfigurationsdateien erforderlich:

CORS-Konfiguration im Dispatcher cors-configuration-in-dispatcher

Kundinnen und Kunden, die CORS-Anfragen verwenden, müssen möglicherweise ihre CORS-Konfiguration im Dispatcher überprüfen und aktualisieren.

GraphQL für AEM – Zusammenfassung der Erweiterungen 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:

CORS-Filter 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 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:

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":[
      ""
    ]
}

Einschränkungen limitations

Zum Schutz vor potenziellen Problemen gibt es Standardbeschränkungen für Abfragen:

Außerdem müssen Sie Folgendes beachten:

Authentifizierung authentication

Siehe Authentifizierung für AEM-GraphQL-Remote-Abfragen in Inhaltsfragmenten.

Häufig gestellte Fragen faqs

Es wurden folgende Fragen aufgeworfen:

Tutorial – Erste Schritte mit AEM Headless und GraphQL 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.