Erkunden der GraphQL-APIs

Die GraphQL-API von AEM bietet eine leistungsstarke Abfragesprache, mit der Daten von Inhaltsfragmenten für nachgelagerte Anwendungen bereitgestellt werden können. Inhaltsfragmentmodelle definieren das Datenschema, das von Inhaltsfragmenten verwendet wird. Jedes Mal, wenn ein Inhaltsfragmentmodell erstellt oder aktualisiert wird, wird das Schema übersetzt und dem „Graphen“ hinzugefügt, aus dem die GraphQL-API besteht.

In diesem Kapitel werden wir einige gängige GraphQL-Abfragen zum Sammeln von Inhalten mit einer IDE namens GraphiQL untersuchen. Mit der GraphiQL-IDE können Sie die zurückgegebenen Abfragen und Daten schnell testen und verfeinern. GraphiQL bietet auch einen einfachen Zugang zur Dokumentation, sodass man leicht lernen und verstehen kann, welche Methoden verfügbar sind.

Voraussetzungen

Dies ist ein mehrteiliges Tutorial, und es wird davon ausgegangen, dass die unter Erstellen von Inhaltsfragmenten beschriebenen Schritte abgeschlossen sind.

Ziele

  • Erfahren Sie, wie Sie mit dem GraphiQL-Tool eine Abfrage mithilfe der GraphQL-Syntax erstellen können.
  • Erfahren Sie, wie Sie eine Liste von Inhaltsfragmenten und ein einzelnes Inhaltsfragment abfragen.
  • Erfahren Sie, wie Sie bestimmte Datenattribute filtern und anfordern.
  • Erfahren Sie, wie Sie eine Abfrage mehrerer Inhaltsfragmentmodelle verbinden.
  • Erfahren Sie, wie Sie GraphQL-Abfragen persistieren.

Aktivieren eines GraphQL-Endpunkts

Es muss ein GraphQL-Endpunkt konfiguriert werden, um GraphQL-API-Abfragen für Inhaltsfragmente zu aktivieren.

  1. Navigieren Sie im AEM-Startbildschirm zu Tools > Allgemein > GraphQL.

    Navigieren zum GraphQL-Endpunkt

  2. Tippen Sie auf Erstellen in der oberen rechten Ecke und geben Sie im daraufhin angezeigten Dialogfeld die folgenden Werte ein:

    • Name*: Mein Projekt-Endpunkt.
    • Verwenden Sie ein GraphQL-Schema, das von … *: Mein Projekt bereitgestellt wird

    Erstellen eines GraphQL-Endpunkts

    Tippen Sie auf Erstellen, um den Endpunkt zu speichern.

    Die auf der Grundlage einer Projektkonfiguration erstellten GraphQL-Endpunkte ermöglichen nur Abfragen für Modelle, die zu diesem Projekt gehören. In diesem Fall können nur die Abfragen für die Modelle Person und Team verwendet werden.

    HINWEIS

    Es kann auch ein globaler Endpunkt erstellt werden, um Abfragen für Modelle über mehrere Konfigurationen hinweg zu aktivieren. Dies sollte mit Vorsicht verwendet werden, da es die Umgebung für zusätzliche Sicherheitslücken öffnen und die Verwaltung von AEM insgesamt komplexer machen kann.

  3. Es sollte nun ein GraphQL-Endpunkt in Ihrer Umgebung aktiviert sein.

    Aktivierte GraphQL-Endpunkte

Verwenden der GraphiQL-IDE

Das GraphiQL-Tool ermöglicht es Entwicklerinnen und Entwicklern, Abfragen für Inhalte in der aktuellen AEM-Umgebung zu erstellen und zu testen. Das GraphiQL-Tool ermöglicht es den Benutzenden auch, Abfragen zu persistieren oder zu speichern, die von Client-Anwendungen in einer Produktionsumgebung verwendet werden können.

Als Nächstes erkunden Sie die Leistungsfähigkeit der GraphQL-API von AEM mithilfe der integrierten GraphiQL-IDE.

  1. Navigieren Sie im AEM-Startbildschirm zu Tools > Allgemein > GraphQL-Abfrage-Editor.

    Navigieren zur GraphiQL-IDE

    HINWEIS

    In den älteren Versionen von AEM ist die GraphiQL-IDE möglicherweise nicht integriert. Sie kann manuell installiert werden, indem Sie den folgenden Anweisungen folgen.

  2. Vergewissern Sie sich in der oberen rechten Ecke, dass der Endpunkt auf Mein Projekt-Endpunkt eingestellt ist.

    GraphQL-Endpunkt festlegen

Dadurch werden alle Abfragen auf Modelle beschränkt, die im Projekt Mein Projekt erstellt wurden.

Abfragen einer Liste von Inhaltsfragmenten

Eine gängige Anforderung besteht darin, mehrere Inhaltsfragmente abzufragen.

  1. Fügen Sie die folgende Abfrage in das Hauptbedienfeld ein (und ersetzen Sie damit die Liste der Kommentare):

    query allTeams {
  teamList {
    items {
      _path
      title
    }
  }
}

  2. Drücken Sie die Wiedergabeschaltfläche im oberen Menü, um die Abfrage auszuführen. Sie sollten die Ergebnisse der Inhaltsfragmente aus dem vorherigen Kapitel sehen:

    Ergebnisse der Personenliste

  3. Positionieren Sie den Cursor unter dem Text title und drücken Sie STRG+Leertaste, um die Anzeige von Code-Hinweisen auszulösen. Fügen Sie shortname und description zur Abfrage hinzu.

    Aktualisieren der Abfrage mit Code-Hinweisen

  4. Führen Sie die Abfrage erneut aus, indem Sie die Wiedergabeschaltfläche auswählen. Daraufhin sollte zu sehen sein, dass die Ergebnisse die zusätzlichen Eigenschaften von shortname und description umfassen.

    Ergebnisse für „shortname“ und „description“

    Der shortname ist eine einfache Eigenschaft und description ein mehrzeiliges Textfeld. Über die GraphQL-API können verschiedene Formate für die Ergebnisse ausgewählt werden, z. B. html, markdown, json oder plaintext.

Abfrage für verschachtelte Fragmente

Als Nächstes experimentieren Sie mit Abfragen, indem Sie verschachtelte Fragmente abrufen. Denken Sie daran, dass das Team-Modell auf das Personenmodell verweist.

  1. Erweitern Sie die Abfrage um die Eigenschaft teamMembers. Denken Sie daran, dass es sich dabei um ein Feld mit einem Fragmentverweis für das Personenmodell handelt. Eigenschaften des Personenmodells können zurückgegeben werden:

    query allTeams {
    teamList {
        items {
            _path
            title
            shortName
            description {
                plaintext
            }
            teamMembers {
                fullName
                occupation
            }
        }
    }
}

    JSON-Antwort:

    {
    "data": {
        "teamList": {
        "items": [
            {
            "_path": "/content/dam/my-project/en/team-alpha",
            "title": "Team Alpha",
            "shortName": "team-alpha",
            "description": {
                "plaintext": "This is a description of Team Alpha!"
            },
            "teamMembers": [
                {
                "fullName": "John Doe",
                "occupation": [
                    "Artist",
                    "Influencer"
                ]
                },
                {
                "fullName": "Alison Smith",
                "occupation": [
                    "Photographer"
                ]
                }
              ]
        }
        ]
        }
    }
}

    Die Möglichkeit, Abfragen für verschachtelte Fragmente durchzuführen, ist eine leistungsstarke Funktion der AEM GraphQL-API. In diesem einfachen Beispiel ist die Verschachtelung nur zwei Ebenen tief. Es ist jedoch möglich, Fragmente noch weiter zu verschachteln. Bei einem Adressmodell, das mit einem Personenmodell verknüpft ist, ist es beispielsweise möglich, Daten aus allen drei Modellen im Rahmen einer einzigen Abfrage zurückzugeben.

Filtern einer Liste von Inhaltsfragmenten

Als Nächstes erfahren Sie, wie es möglich ist, Ergebnisse basierend auf einem Eigenschaftswert nach einer Teilmenge von Inhaltsfragmenten zu filtern.

  1. Geben Sie die folgende Abfrage in die GraphiQL-Benutzeroberfläche ein:

    query personByName($name:String!){
  personList(
    filter:{
      fullName:{
        _expressions:[{
          value:$name
          _operator:EQUALS
        }]
      }
    }
  ){
    items{
      _path
      fullName
      occupation
    }
  }
}

    Mit der obigen Abfrage wird eine Suche nach allen Personenfragmenten im System durchgeführt. Der am Anfang der Abfrage hinzugefügte Filter führt einen Vergleich des Felds name und der Variablenzeichenfolge $name durch.

  2. Geben Sie im Bedienfeld Abfragevariablen Folgendes ein:

    {"name": "John Doe"}

  3. Führen Sie die Abfrage aus. Es sollte nur das Inhaltsfragment für Personen mit dem Wert John Doe zurückgegeben werden.

    Filtern mit Abfragevariablen

    Es gibt viele weitere Optionen zum Filtern und Erstellen komplexer Abfragen. Siehe Verwenden von GraphQL mit AEM – Beispielinhalt und Beispielabfragen.

  4. Erweitern Sie die obige Abfrage zum Abrufen des Profilbilds.

    query personByName($name:String!){
  personList(
    filter:{
      fullName:{
        _expressions:[{
          value:$name
          _operator:EQUALS
        }]
      }
    }
  ){
    items{
      _path
      fullName
      occupation
      profilePicture{
        ... on ImageRef{
          _path
          _authorUrl
          _publishUrl
          height
          width

        }
      }
    }
  }
}

    profilePicture ist ein Inhaltsverweis, wofür ein Bild erwartet wird. Daher wird das integrierte Objekt ImageRef verwendet. Dadurch können zusätzliche Daten zum Bild angefordert werden, auf das verwiesen wird, z. B. width und height.

Abfragen eines einzelnen Inhaltsfragments

Es ist auch möglich, ein einzelnes Inhaltsfragment direkt abzufragen. Inhalte in AEM werden hierarchisch gespeichert, wobei die eindeutige Kennung für ein Fragment auf dem Pfad des Fragments basiert.

  1. Geben Sie die folgende Abfrage im GraphiQL-Editor ein:

    query personByPath($path: String!) {
    personByPath(_path: $path) {
        item {
        fullName
        occupation
        }
    }
}

  2. Geben Sie Folgendes für die Abfragevariablen ein:

    {"path": "/content/dam/my-project/en/alison-smith"}

  3. Führen Sie die Abfrage aus und beachten Sie, dass das einzelne Ergebnis zurückgegeben wird.

Persistieren von Abfragen

Sobald Entwicklerinnen und Entwickler mit der Abfrage und den von der Abfrage zurückgegebenen Ergebnisdaten zufrieden sind, besteht der nächste Schritt darin, die Abfrage zu speichern oder in AEM als persistierte Abfrage beizubehalten. Persistierte Abfragen sind der bevorzugte Mechanismus zur Bereitstellung der GraphQL-API für Client-Anwendungen. Nachdem eine Abfrage persistent geworden ist, kann sie mithilfe einer GET-Anfrage angefordert und auf Dispatcher- und CDN-Ebenen zwischengespeichert werden. Persistierte Abfragen sind deutlich leistungsstärker. Zusätzlich zu den Leistungsvorteilen stellen persistierte Abfragen sicher, dass zusätzliche Daten nicht versehentlich Client-Anwendungen zur Verfügung gestellt werden. Weitere Informationen über persistierte Abfragen finden Sie hier.

Als Nächstes legen Sie zwei einfache Abfragen als persistent fest, die im nächsten Kapitel verwendet werden.

  1. Geben Sie die folgende Abfrage in die GraphiQL-IDE ein:

    query allTeams {
    teamList {
        items {
            _path
            title
            shortName
            description {
                plaintext
            }
            teamMembers {
                fullName
                occupation
            }
        }
    }
}

    Überprüfen Sie, ob die Abfrage funktioniert.

  2. Tippen Sie als Nächstes auf Speichern unter und geben Sie all-teams als Abfragenamen ein.

    Die Abfrage sollte in der linken Leiste unter Persistierte Abfragen angezeigt werden.

    Alle Teams – persistierte Abfrage

  3. Tippen Sie als Nächstes auf die Auslassungspunkte … neben der persistenten Abfrage und dann auf URL kopieren, um den Pfad in die Zwischenablage zu kopieren.

    Kopieren der URL für die persistente Abfrage

  4. Öffnen Sie eine neue Registerkarte und fügen Sie den kopierten Pfad in Ihren Browser ein:

    https://$YOUR-AEMasCS-INSTANCEID$.adobeaemcloud.com/graphql/execute.json/my-project/all-teams

    Es sollte ähnlich wie der obige Pfad aussehen. Sie sollten sehen, dass die JSON-Ergebnisse der Abfrage zurückgegeben wurden.

    Aufschlüsseln der oben genannten URL:

    Name Beschreibung
    /graphql/execute.json Persistenter Abfrageendpunkt
    /my-project Projektkonfiguration für /conf/my-project
    /all-teams Name der persistierten Abfrage

  5. Kehren Sie zur GraphiQL-IDE zurück und benutzen Sie die Plustaste +, um die NEUE Abfrage beizubehalten

    query personByName($name: String!) {
  personList(
    filter: {
      fullName:{
        _expressions: [{
          value: $name
          _operator:EQUALS
        }]
      }
    }){
    items {
      _path
      fullName
      occupation
      biographyText {
        json
      }
      profilePicture {
        ... on ImageRef {
          _path
          _authorUrl
          _publishUrl
          width
          height
        }
      }
    }
  }
}

  6. Speichern Sie die Abfrage als person-by-name.

  7. Es sollten zwei persistierte Abfragen gespeichert worden sein:

    Abgeschlossene persistierte Abfragen

Veröffentlichen von GraphQL-Endpunkt und persistierten Abfragen

Nach Überprüfung und Verifizierung veröffentlichen Sie GraphQL Endpoint und Persisted Queries

  1. Navigieren Sie im AEM-Startbildschirm zu Tools > Allgemein > GraphQL.

  2. Tippen Sie auf das Kontrollkästchen neben Mein Projekt-Endpunkt und dann auf Veröffentlichen

    Veröffentlichen des GraphQL-Endpunkts

  3. Navigieren Sie im AEM-Startbildschirm zu Tools > Allgemein > GraphQL-Abfrage-Editor

  4. Tippen Sie auf die Abfrage Alle Teams im Bedienfeld „Persistierte Abfragen“ und dann auf Veröffentlichen

    Veröffentlichen der persistierten Abfragen

  5. Wiederholen Sie den obigen Schritt für die Abfrage person-by-name

Lösungsdateien

Laden Sie die in den letzten drei Kapiteln erstellten Inhalte, Modelle und gespeicherten Abfragen herunter: basic-tutorial-solution.content.zip

Zusätzliche Ressourcen

Weitere Informationen zu GraphQL-Abfragen finden Sie unter Verwendung von GraphQL mit AEM – Beispielinhalt und Beispielabfragen.

Herzlichen Glückwunsch!

Herzlichen Glückwunsch! Sie haben mehrere GraphQL-Abfragen erstellt und ausgeführt!

Nächste Schritte

Im nächsten Kapitel Erstellen einer React-App erfahren Sie, wie eine externe Anwendung die GraphQL-Endpunkte von AEM abfragen und diese beiden persistierten Abfragen verwenden kann. Außerdem werden Sie mit der grundlegenden Fehlerbehandlung während der Ausführung von GraphQL-Abfragen vertraut gemacht.

Installieren des GraphiQL-Tools (optional)

In einigen Versionen von AEM (6.x.x) muss das GraphiQL IDE-Tool manuell installiert werden. Verwenden Sie hierzu diese Anweisungen.

Auf dieser Seite