GraphQL-APIs

Die GraphQL-API von AEM bietet eine leistungsstarke Abfragesprache, um Daten von Inhaltsfragmenten für nachgelagerte Anwendungen verfügbar zu machen. Inhaltsfragmentmodelle definieren das Datenschema, das von Inhaltsfragmenten verwendet wird. Jedes Mal, wenn ein Inhaltsfragmentmodell erstellt oder aktualisiert wird, wird das Schema übersetzt und zum "Diagramm"hinzugefügt, aus dem die GraphQL-API besteht.

In diesem Kapitel werden einige gängige GraphQL-Abfragen untersucht, um Inhalte mithilfe einer IDE namens zu erfassen. GraphiQL. Mit der GraphiQL IDE können Sie die zurückgegebenen Abfragen und Daten schnell testen und verfeinern. Darüber hinaus erhalten Sie einen einfachen Zugriff auf die Dokumentation, sodass Sie leicht wissen können, welche Methoden verfügbar sind.

Voraussetzungen

Dies ist ein mehrteiliges Tutorial, und es wird davon ausgegangen, dass die im Erstellen von Inhaltsfragmenten wurden abgeschlossen.

Ziele

• Erfahren Sie, wie Sie mit dem GraphQL-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 die GraphQL-Abfrage beibehalten.

Aktivieren eines GraphQL-Endpunkts

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

1. Navigieren Sie im Bildschirm AEM Start zu Instrumente > Allgemein > GraphQL.

   

2. Tippen Erstellen Geben Sie in der oberen rechten Ecke des angezeigten Dialogfelds die folgenden Werte ein:

   • Name*: Mein Projektendpunkt.
   • GraphQL-Schema verwenden, das von … * bereitgestellt wird: Mein Projekt

   

   Tippen Erstellen , um den Endpunkt zu speichern.

   Die GraphQL-Endpunkte, die basierend auf einer Projektkonfiguration erstellt wurden, ermöglichen nur Abfragen für Modelle, die zu diesem Projekt gehören. In diesem Fall fragt die einzige Instanz die Person und Team -Modelle 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.

   

Verwenden der GraphiQL-IDE

Die GraphiQL ermöglicht es Entwicklern, Abfragen für Inhalte in der aktuellen AEM-Umgebung zu erstellen und zu testen. Mit dem GraphQL-Tool können Benutzer auch beibehalten oder speichern -Abfragen, die von Clientanwendungen in einer Produktionseinstellung verwendet werden sollen.

Erkunden Sie als Nächstes die Leistungsfähigkeit AEM GraphQL-API mit der integrierten GraphiQL-IDE.

1. Navigieren Sie im Bildschirm AEM Start zu Instrumente > Allgemein > GraphQL-Abfrage-Editor.

   

   HINWEIS

   In sind die älteren Versionen AEM GraphiQL IDE möglicherweise nicht integriert. Sie kann manuell installiert werden, indem Sie den folgenden Schritten folgen: instructions.

2. Stellen Sie oben rechts sicher, dass der Endpunkt auf Mein Projektendpunkt.

   

Dadurch werden alle Abfragen auf Modelle angewendet, die in der Mein Projekt Projekt.

Liste von Inhaltsfragmenten abfragen

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

1. Fügen Sie die folgende Abfrage in den Hauptbereich ein (ersetzen Sie die Liste der Kommentare):

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

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

   

3. Positionieren Sie den Cursor unter dem title Text und Eingabe STRG+Leertaste Trigger-Code-Hinweise. Hinzufügen shortname und description zur Abfrage hinzufügen.

   

4. Führen Sie die Abfrage erneut aus, indem Sie die Play und Sie sollten sehen, dass die Ergebnisse die zusätzlichen Eigenschaften von shortname und description.

   

   Die shortname ist eine einfache Eigenschaft und description ist ein mehrzeiliges Textfeld und die GraphQL-API ermöglicht es uns, verschiedene Formate für die Ergebnisse auszuwählen, wie html, markdown, jsonoder plaintext.

Abfrage für verschachtelte Fragmente

Als Nächstes experimentieren Sie mit der Abfrage, indem Sie verschachtelte Fragmente abrufen. Denken Sie daran, dass die Team -Modell referenziert die Person -Modell.

1. Aktualisieren Sie die Abfrage, um die teamMembers -Eigenschaft. Erinnern Sie sich daran, dass dies eine Fragmentverweis zum Personenmodell. Eigenschaften des Personen-Modells 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, mit verschachtelten Fragmenten abzufragen, 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. Wenn beispielsweise eine Adresse mit einem Person Es wäre möglich, Daten aus allen drei Modellen in einer einzigen Abfrage zurückzugeben.

Filtern einer Liste von Inhaltsfragmenten

Als Nächstes sehen wir uns an, wie es möglich ist, die Ergebnisse basierend auf einem Eigenschaftswert nach einer Untergruppe 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
       }
     }
   }
   

   Die obige Abfrage führt eine Suche nach allen Personen-Fragmenten im System durch. Der am Anfang der Abfrage hinzugefügte Filter führt einen Vergleich der name -Feld und der Variablenzeichenfolge $name.

2. Im Abfragevariablen -Bereich geben Sie Folgendes ein:

   {"name": "John Doe"}
   

3. Führen Sie die Abfrage aus. Es wird erwartet, dass nur Personen Inhaltsfragment wird mit dem Wert John Doe.

   

   Es gibt viele weitere Optionen zum Filtern und Erstellen komplexer Abfragen, siehe Verwendung von GraphQL mit AEM - Beispielinhalt und Abfragen.

4. Erweiterung der obigen 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
   
           }
         }
       }
     }
   }
   

   Die profilePicture ist eine Inhaltsreferenz, und es wird erwartet, dass es sich um ein Bild handelt. Daher ist es integriert ImageRef -Objekt verwendet wird. Dadurch können wir zusätzliche Daten zum Bild anfordern, auf das verwiesen wird, z. B. die width und height.

Einzelnes Inhaltsfragment abfragen

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

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

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

2. Geben Sie Folgendes für die Abfragevariablen:

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

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

Dauerhafte Abfragen

Sobald ein Entwickler mit der von der Abfrage zurückgegebenen Abfrage und Ergebnisdaten zufrieden ist, besteht der nächste Schritt darin, die Abfrage zu speichern oder zu AEM. Die Beständige Abfragen sind der bevorzugte Mechanismus zum Freigeben der GraphQL-API für Clientanwendungen. Nachdem eine Abfrage persistiert wurde, kann sie mithilfe einer GET-Anfrage angefordert und in den Dispatcher- und CDN-Ebenen zwischengespeichert werden. Die Leistung der persistenten Abfragen ist viel besser. Zusätzlich zu den Leistungsvorteilen stellen persistente Abfragen sicher, dass zusätzliche Daten nicht versehentlich Client-Anwendungen zur Verfügung gestellt werden. Weitere Informationen Persistente Abfragen finden Sie hier ..

Beibehalten von zwei einfachen Abfragen, 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. Nächstes Tippen Speichern unter und eingeben all-teams als Abfragename.

   Die Abfrage sollte unter Beständige Abfragen in der linken Leiste.

   

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

   

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
   

   Sie sollte dem obigen Pfad ähnlich aussehen. Sie sollten sehen, dass die JSON-Ergebnisse der zurückgegebenen Abfrage vorliegen.

   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 gespeicherten Abfrage

5. Kehren Sie zur GraphiQL-IDE zurück und verwenden Sie die Plusschaltfläche . + , um die NEU-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. Zwei persistente Abfragen sollten gespeichert werden:

   

Veröffentlichen von GraphQL-Endpunkten und persistenten Abfragen

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

1. Navigieren Sie im Bildschirm AEM Start zu Instrumente > Allgemein > GraphQL.

2. Tippen Sie auf das Kontrollkästchen neben Mein Projektendpunkt und tippen Veröffentlichen

   

3. Navigieren Sie im Bildschirm AEM Start zu Instrumente > Allgemein > GraphQL-Abfrage-Editor

4. Tippen Sie auf All-Teams Abfrage im Bedienfeld "Persistente Abfragen"und tippen Sie auf Veröffentlichen

   

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

Lösungsdateien

Laden Sie den Inhalt, die Modelle und die persistenten Abfragen herunter, die in den letzten drei Kapiteln erstellt wurden: tutorial-solution-content.zip

Zusätzliche Ressourcen

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

Herzlichen Glückwunsch!

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

Nächste Schritte

Im nächsten Kapitel React-App erstellenErfahren Sie, wie eine externe Anwendung GraphQL-Endpunkte abfragen AEM und diese beiden beibehaltenen Abfragen verwenden kann. Außerdem wurden Sie mit der grundlegenden Fehlerbehandlung während der GraphQL-Abfrageausführung vertraut gemacht.

Installieren des GraphiQL-Tools (optional)

Verwenden Sie in einigen Versionen von AEM (6.X.X) das GraphiQL IDE-Tool manuell installiert werden muss die folgenden Anweisungen:

1. Gehen Sie zum Software-Verteilungsportal > AEM as a Cloud Service.

2. Suchen Sie nach „GraphiQL“ (stellen Sie sicher, dass Sie das i in GraphiQL einschließen.

3. Laden Sie die neueste Version GraphiQL Content Package v.x.x.x herunter.

   

   Die ZIP-Datei ist ein AEM Paket, das direkt installiert werden kann.

4. Navigieren Sie im AEM Startmenü zu Instrumente > Implementierung > Pakete.

5. Klicken Sie auf Paket hochladen und wählen Sie das im vorherigen Schritt heruntergeladene Paket aus. Klicken Sie auf Installieren, um das Paket zu installieren.

   

Ressourcen für Business.Adobe.com