Persistierte GraphQL-Abfragen persisted-graphql-queries

Persistente Abfragen sind GraphQL-Abfragen, die auf dem Server mit Adobe Experience Manager (AEM) as a Cloud Service erstellt und gespeichert werden. Sie können von Client-Programmen mit einer GET-Anfrage angefragt werden. Die Antwort einer GET-Anfrage kann auf den Dispatcher- und CDN-Ebenen zwischengespeichert werden, was letztendlich die Leistung des anfragenden Client-Programms verbessert. Dies unterscheidet sich von standardmäßigen GraphQL-Abfragen, die mit POST-Anfragen ausgeführt werden, bei denen die Antwort nicht einfach zwischengespeichert werden kann.

Die GraphiQL-IDE ist in AEM verfügbar, damit Sie GraphQL-Abfragen entwickeln, testen und persistieren können, bevor Sie sie in Ihre Produktionsumgebung übertragen. Für Fälle, in denen eine Anpassung erforderlich ist (z. B. beim Anpassen des Caches), können Sie die API verwenden. Sehen Sie sich dazu das cURL-Beispiel in Persistieren einer GraphQL-Abfrage an.

Persistente Abfragen und Endpunkte persisted-queries-and-endpoints

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:

Wenn es beispielsweise eine bestimmte Abfrage namens my-query gibt, die ein my-model-Modell aus der Sites-Konfiguration my-conf verwendet:

Beibehalten einer GraphQL-Abfrage how-to-persist-query

Es wird empfohlen, Abfragen zunächst in einer AEM-Autorenumgebung beizubehalten und dann die Abfrage in Ihre AEM-Veröffentlichungsumgebung der Produktion für die Verwendung durch Programme zu übertragen.

Es gibt verschiedene Methoden zum Beibehalten von Abfragen:

Die GraphiQL-IDE ist die bevorzugte Methode zum Erstellen persistenter Abfragen. So persistieren Sie eine Abfrage mithilfe des Befehlszeilen-Tools cURL:

Ausführen einer persistenten Abfrage execute-persisted-query

Um eine persistente Abfrage auszuführen, sendet ein Client-Programm eine GET-Anfrage mit der folgenden Syntax:

GET <AEM_HOST>/graphql/execute.json/<PERSISTENT_PATH>

Dabei ist PERSISTENT_PATH ein gekürzter Pfad zum Speicherort der persistenten Abfrage.

Verwenden von Abfragevariablen query-variables

Abfragevariablen können mit persistenten Abfragen verwendet werden. Die Abfragevariablen werden an die Anfrage mit einem Semikolon (;) unter Verwendung des Variablennamens und -werts angehängt. Mehrere Variablen werden durch Semikolons getrennt.

Die Struktur sieht wie folgt aus:

<AEM_HOST>/graphql/execute.json/<PERSISTENT_QUERY_PATH>;variable1=value1;variable2=value2

Die folgende Abfrage enthält beispielsweise die Variable activity, um eine Liste nach einem Aktivitätswert zu filtern:

query getAdventuresByActivity($activity: String!) {
      adventureList (filter: {
        adventureActivity: {
          _expressions: [
            {
              value: $activity
            }
          ]
        }
      }){
        items {
          _path
        adventureTitle
        adventurePrice
        adventureTripLength
      }
    }
  }

Aus dieser Abfrage kann unter einem Pfad wknd/adventures-by-activity eine persistente Abfrage erstellt werden. Um die persistente Abfrage für activity=Camping aufzurufen, müsste die Anfrage wie folgt aussehen:

<AEM_HOST>/graphql/execute.json/wknd/adventures-by-activity%3Bactivity%3DCamping

Die UTF-8-Kodierung %3B ist für ;, und %3D ist die Kodierung für =. Die Abfragevariablen und alle Sonderzeichen müssen ordnungsgemäß kodiert sein, damit die persistierte Abfrage ausgeführt wird.

Verwenden von Abfragevariablen – Best Practices query-variables-best-practices

Bei der Verwendung von Variablen in Abfragen sollten einige Best Practices befolgt werden:

Caching persistierter Abfragen caching-persisted-queries

Persistierte Abfragen werden empfohlen, da sie auf der Dispatcher- und CDN-Ebene zwischengespeichert werden können, was letztendlich die Leistung der anfragenden Client-Anwendung verbessert.

Standardmäßig macht AEM zwischengespeicherte Inhalte, die auf einer TTL (Time To Live)-Definition basieren, ungültig. Diese TTLs können durch die folgenden Parameter definiert werden. Auf diese Parameter kann auf verschiedene Weise zugegriffen werden, wobei die Namen je nach verwendetem Mechanismus variieren:

Authoring-Instanzen author-instances

Für Authoring-Instanzen sind die Standardwerte:

Diese:

Veröffentlichungsinstanzen publish-instances

Für Publishing-Instanzen sind die Standardwerte:

Diese können auf folgende Art überschrieben werden:

Verwalten von HTTP-Cache-Kopfzeilen in der GraphiQL-IDE http-cache-headers-graphiql-ide

Die GraphiQL-IDE – Siehe Speichern persistierter Abfragen

Verwalten des Caches auf der Ebene der persistierten Abfrage cache-persisted-query-level

Dazu müssen Sie die Abfrage mithilfe von cURL in Ihrer Befehlszeilenschnittstelle an AEM senden.

Ein Beispiel für die PUT-Methode (erstellen):

curl -u admin:admin -X PUT \
--url "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-max-age" \
--header "Content-Type: application/json" \
--data '{ "query": "{articleList { items { _path author } } }", "cache-control": { "max-age": 300 }, "surrogate-control": {"max-age":600, "stale-while-revalidate":1000, "stale-if-error":1000} }'

Ein Beispiel für die POST-Methode (aktualisieren):

curl -u admin:admin -X POST \
--url "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-max-age" \
--header "Content-Type: application/json" \
--data '{ "query": "{articleList { items { _path author } } }", "cache-control": { "max-age": 300 }, "surrogate-control": {"max-age":600, "stale-while-revalidate":1000, "stale-if-error":1000} }'

Die cache-control kann zum Zeitpunkt der Erstellung (PUT) oder später (z. B. über eine POST-Anfrage) festgelegt werden. Die Cache-Steuerung ist beim Erstellen der persistenten Abfrage optional, da AEM den Standardwert bereitstellen kann. Siehe Persistieren einer GraphQL-Abfrage, für ein Beispiel der Persistierung einer Abfrage mit cURL.

Verwalten des Caches mit Cloud Manager-Variablen cache-cloud-manager-variables

Cloud Manager-Umgebungsvariablen können mit Cloud Manager definiert werden, um die erforderlichen Werte zu definieren:

Verwalten des Caches mit einer OSGi-Konfiguration cache-osgi-configration

Um den Cache global zu verwalten, können Sie die OSGi-Einstellungen für die Konfiguration des persistierten Abfrage-Service konfigurieren.

Die standardmäßige OSGi-Konfiguration für Veröffentlichungsinstanzen:

Konfiguration des Abfrageantwort-Codes configuring-query-response-code

Standardmäßig sendet der PersistedQueryServlet eine 200-Antwort, wenn er eine Abfrage ausführt, unabhängig vom tatsächlichen Ergebnis.

Sie können die OSGi-Einstellungen für die Konfiguration des Dienstes für persistierte Abfragen konfigurieren, um zu steuern, ob detailliertere Status-Codes vom Endpunkt /execute.json/persisted-query zurückgegeben werden, wenn ein Fehler in der persistierten Abfrage auftritt.

Das Feld Respond with application/graphql-response+json (responseContentTypeGraphQLResponseJson) kann nach Bedarf definiert werden:

Codieren der Abfrage-URL zur Verwendung in einer Mobile-App encoding-query-url

Damit die Abfrage-URL von einer Applikation verwendet werden kann, müssen alle Sonderzeichen, die beim Erstellen von Abfragevariablen verwendet werden – d. h. Semikolons (;), Gleichheitszeichen (=), Schrägstriche (/) – konvertiert werden, sodass die entsprechende UTF-8-Codierung verwendet wird.

Zum Beispiel:

curl -X GET \ "https://publish-p123-e456.adobeaemcloud.com/graphql/execute.json/wknd/adventure-by-path%3BadventurePath%3D%2Fcontent%2Fdam%2Fwknd%2Fen%2Fadventures%2Fbali-surf-camp%2Fbali-surf-camp"

Die URL kann in die folgenden Teile unterteilt werden:

Im Klartext sieht der Anfrage-URI wie folgt aus:

/graphql/execute.json/wknd/adventure-by-path;adventurePath=/content/dam/wknd/en/adventures/bali-surf-camp/bali-surf-camp

Um eine persistente Abfrage in einer Client-Anwendung zu verwenden, sollte für JavaScript, Java oder NodeJS das AEM-Headless-Client-SDK verwendet werden. Das Headless-Client-SDK codiert in der Anfrage automatisch alle Abfragevariablen entsprechend.

Übertragen einer persistenten Abfrage in die Produktionsumgebung transfer-persisted-query-production

Persistente Abfragen sollten immer in einem AEM-Autoren-Service erstellt und dann in einem AEM-Veröffentlichungs-Service veröffentlicht (repliziert) werden. Häufig werden persistente Abfragen in niedrigeren Umgebungen wie lokalen Umgebungen oder Entwicklungsumgebungen erstellt und getestet. Anschließend müssen persistente Abfragen in Umgebungen höherer Ebene übertragen werden, um sie letztendlich in einer AEM-Publishing-Produktionsumgebung verfügbar zu machen, auf die Client-Anwendungen zugreifen können.

Verpacken von persistenten Abfragen

Persistente Abfragen können in AEM-Pakete integriert werden. AEM-Pakete können dann heruntergeladen und in verschiedenen Umgebungen installiert werden. AEM-Pakete können auch von einer AEM-Autorenumgebung in AEM-Veröffentlichungsumgebungen repliziert werden.

So erstellen Sie ein Paket:

Nachdem das Paket erstellt wurde, können Sie Folgendes tun: