AEM mit GraphQL

Die Zukunft für AEM Headless?

Rest - GraphQL: A burger comparison

Was ist GraphQL?

Das beliebteste Bild, um GraphQL zu beschreiben, ist wahrscheinlich das des Burgers. Normalerweise zeigt das Bild einen kleineren Burger, denn GraphQL ist am besten geeignet, um genau das anzufordern, was man braucht und nicht mehr. Aber wir sind hungrig, also fordern wir einen dreifachen Burger an - einfach weil wir die Freiheit haben, es zu tun.

 

Und das ist das Schöne an GraphQL im Vergleich zur REST API: Wir sind nicht mehr allein davon abhängig, was die API uns vorgibt - wir können unsere eigene API erstellen (natürlich mit Einschränkungen). Schauen wir uns also an, wie GraphQL in AEM verwendet werden kann und welche Vorteile es gegenüber der Assets-API oder dem Sling Model Exporter mit Komponenten hat.

 

In AEM arbeitet GraphQL derzeit nur mit Content Fragments (dt. Inhaltsfragmente), deren Struktur durch die Content Fragment Models definiert ist.

Quick Setup in AEM

Beginnen wir mit der Grundeinstellung, um zu sehen, wie einfach die Konfiguration ist.

 

Voraussetzungen

  • Sie benötigen AEM as a Cloud Service oder mindestens AEM Version 6.5.10 oder höher
  • Ein Projekt unter Tools > General > Configuration Browser ist erstellt (in unserem Fall heißt es "my-project")
  • Ein Content Fragment Model und ein Content Fragment sind unter diesem Projekt verfügbar

 

1) Definieren Sie einen GraphQL-Endpunkt unter Tools > Assets > GraphQL

Tools - Assets - GraphQL
create endpoint for graphql

2) Definieren Sie die GraphQL-Eigenschaften für Ihr Content Fragment Model unter Tools > Assets > Content Fragment Models

graphql content fragment properties

3) Das war's im Grunde. Jetzt können Sie bereits ein Content Fragment dieses Models öffnen und sollten die GraphQL JSON-Ausgabestruktur sehen. Wenn Sie die Registerkarte "Network" (dt. Netzwerk) in der Entwicklungskonsole Ihres Browsers öffnen, können Sie den GraphQL-Request mit der Query sehen.

graphql json output of content fragment

Erstellen Sie Ihren ersten GraphQL-Request

Zu Testzwecken senden wir unseren ersten Request an den AEM Autor. Sie müssen einen Post Request mit Authentifizierungs-Header an die Endpunktadresse der Autoreninstanz senden. Zum Beispiel "/content/_cq_graphql/my-project/endpoint.json" für den Endpunkt "my-project".

 

Der Hauptteil des Requests enthält die Query. Zum Beispiel eine Query, um einen einzelnen Artikel mit Überschrift und Text anzufordern.

{
  articleByPath(_path: "/content/dam/my-project/articles/our-test-article") {
    item {
      headline
      content {
          plaintext
      }
    }
  }
}

Das Ergebnis sieht wie folgt aus

{
    "data": {
        "articleByPath": {
            "item": {
                "headline": "Our Test Article",
                "content": {
                    "plaintext": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum."
                }
            }
        }
    }
}

Wenn wir nun auch die Bilder des Artikels abfragen wollen, senden wir diesen Request

{
  articleByPath(_path: "/content/dam/my-project/articles/our-test-article") {
    item {
      headline
      content {
          plaintext
      }
      images {
        ... on ImageRef{
            type 
            _path 
            _authorUrl 
            _publishUrl 
            width 
            height 
            mimeType
        }
      }
    }
  }
}

Und erhalten dieses Ergebnis

{
    "data": {
        "articleByPath": {
            "item": {
                "headline": "Test Headline",
                "content": {
                    "plaintext": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum."
                },
                "images": [
                    {
                        "type": "image",
                        "_path": "/content/dam/my-project/articles/our-test-article/image1.jpg",
                        "_authorUrl": "http://localhost:4502/content/dam/my-project/articles/our-test-article/image1.jpg",
                        "_publishUrl": "http://localhost:4503/content/dam/my-project/articles/our-test-article/image1.jpg",
                        "width": 1284,
                        "height": 1605,
                        "mimeType": "image/jpeg"
                    },
                    {
                        "type": "image",
                        "_path": "/content/dam/my-project/articles/our-test-article/image2.jpg",
                        "_authorUrl": "http://localhost:4502/content/dam/my-project/articles/our-test-article/image2.jpg",
                        "_publishUrl": "http://localhost:4503/content/dam/my-project/articles/our-test-article/image2.jpg",
                        "width": 1284,
                        "height": 1605,
                        "mimeType": "image/jpeg"
                    }
                ]
            }
        }
    }
}

Sicherheit und Caching mit "Persistent Queries"

Wir haben nun untersucht, wie wir einen POST-Request mit einer GraphQL-Query an den AEM-Autor senden können, aber wie können wir diese Abfrage so absichern, dass nicht mehr Informationen als erlaubt an die Öffentlichkeit gelangen und das Ergebnis zwischengespeichert wird?

 

Um dies zu erreichen, müssen wir die so genannten Persistent Queries verwenden.

Nachdem eine Query mit einem POST-Request vorbereitet wurde, kann sie persistent gemacht werden, so dass sie mit einem GET-Request angefordert werden kann, die von HTTP-Caches oder einem Content Delivery Network (CDN) zwischengespeichert werden kann. Dies ist erforderlich, da POST-Requests in der Regel nicht zwischengespeichert werden und es nicht empfehlenswert ist, alle Schemainformationen öffentlich zu machen. 

 

Persistent Queries erstellen

1) Aktivieren Sie "GraphQL Persistent Queries" für Ihr Projekt/Konfiguration unter General > Configuration Browser > "my-project" > Properties

graphql persistent queries property in configuration

2) Machen Sie die Query persistent, indem Sie einen PUT-Request an den gewünschten Endpunkt mit dieser URL senden:

  • /graphql/persist.json/my-project/get-simple-article

 

("get-simple-article" kann ein beliebiger Name für Ihre Query sein)

 

Beispiel Query mit einem Parameter

 

query GetSimpleArticleByPath($apath: String!) {
  articleByPath(_path: $apath) {
    item {
      headline
      content {
          plaintext
      }
    }
  }
}

Zum Aktualisieren der Query senden Sie einen POST-Request. Mehr dazu finden Sie in der Adobe Dokumentation.

 

Jetzt wird die Query unter /conf/my-project gespeichert und kann auch in einem Package oder ein Backup aufgenommen werden.

 

graphql persistent query in crx

Die Query kann nun per GET-Request erfolgen und das Ergebnis wird je nach Dispatcher-Einstellungen zwischengespeichert.

 

Verwenden Sie diese URL für den GET-Request

  • /graphql/execute.json/my-project/get-simple-article;apath=%2Fcontent%2Fdam%2Fmy-project%2Ftest-article

 

Vergessen Sie nicht, die Query unter /conf/my-project/settings/graphql/persistentQueries zu replizieren, damit die persistente Query auf der Publisherinstanz verfügbar ist.

Wann GraphQL verwendet werden sollte

 

Wir haben nun ein grundlegendes Verständnis davon, wie GraphQL aussieht und wie es in AEM verwendet werden kann. Aber wie bei allen Technologien braucht es den richtigen Anwendungsfall.

 

GraphQL bietet viele Möglichkeiten, und gerade bei Apps oder Single Page Applications (SPA) kann es die Flexibilität bringen, die sich die meisten Entwickler wünschen.

 

Einige andere Szenarien sind

  • Dynamische Webkomponenten
  • Schnelles Prototyping 
  • Mehrere Ausgabekanäle mit unterschiedlichen Frontend-Technologien
  • Content-Management-Zwecke in Kombination mit Assets HTTP API

 

Beispiel für SPA mit GraphQL in AEM

https://github.com/adobe/aem-guides-wknd-graphql

 

Grenzen

 

Im Backend wandelt AEM die GraphQL Queries in SQL2 Queries um. Wenn wir komplexe GraphQL Queries haben, sind wir vollständig davon abhängig, dass AEM performante SQL2 Queries für uns erstellt. Dies kann zu einer langsamen Abfrage führen, wenn nicht sorgfältig darauf geachtet wird.

 

GraphQL in AEM ist recht neu und bietet viele neue Möglichkeiten, insbesondere für schnelles Prototyping. Bei großen Datenstrukturen kann es an Grenzen stoßen, wenn es darum geht, wie Daten angefordert werden können.

 

Die Alternativen für Headless Inhalte in AEM

Assets HTTP API

 

Die Assets API von AEM ist eine gut etablierte und leistungsfähige API zum Abrufen von Content Fragments und anderen Assets als JSON-Daten. Die Stärke der Assets-API ist jedoch die Möglichkeit, Daten hinzuzufügen, zu bearbeiten und zu löschen. Bei der Abfrage von Daten ist sie auf die einfache Auflistung von Ordnerinhalten beschränkt und bei der Abfrage von Content Fragments kann nur das gesamte Content Fragment und nicht Teile davon abgefragt werden.

 

Kurz gesagt, verwenden Sie die Assets HTTP API, wenn

 

  • Sie damit einverstanden sind, alle Daten zu bekommen, auch die, die Sie nicht brauchen
  • Caching kein großes Thema für Sie ist
  • Sie eine API brauchen, um Daten zu speichern, zu aktualisieren und zu löschen und nicht nur um sie abzufragen

 

Sling Model Exporter (Components/Experience Fragments)

 

Dies ist die "normale" AEM-Methode. Sie erstellen Pages mit Komponenten und schreiben dann Ihren Sling Model Exporter-Javacode, um die benötigten Daten zu exportieren. Sie können auch die  Adobe Core Components verwenden und ganz einfach Content Fragments in Ihre Pages einfügen.

 

Kurz gesagt, verwenden Sie Sling Model Exporter, wenn Sie

 

  • mit der Verwendung von "Export-Pages" einverstanden sind, die separat von den Content Fragments erstellt und veröffentlicht werden müssen, um den Cache zu aktualisieren usw.
  • Code für benutzerdefinierte/spezielle Anfragen schreiben und bereitstellen möchten

 

Was die Zukunft verspricht

 

Adobe treibt AEM mit GraphQL voran und in der Dokumentation können wir lesen 

 

The AEM GraphQL API offers total control on the JSON output, and is an industry standard for querying content.
Moving forward, AEM is planning to invest in the AEM GraphQL API.

Quelle

 

Dies ist ein sehr gutes Zeichen und wir sind gespannt, was die Zukunft für AEM Headless mit GraphQL bringen wird.

 

Weiterführende Informationen

Weitere Informationen zu GraphQL mit AEM

 

https://experienceleague.adobe.com/docs/experience-manager-65/assets/extending/graphql-api-content-fragments.html?lang=en

 

Beispiel Queries

https://experienceleague.adobe.com/docs/experience-manager-cloud-service/content/headless/graphql-api/sample-queries.html?lang=en