Persistierte GraphQL-Abfragen persisted-queries-caching

Persistierte Abfragen sind GraphQL-Abfragen, die auf dem Server mit Adobe Experience Manager (AEM) erstellt und gespeichert werden. Sie können von Client-Programmen mit einer GET-Anfrage angefragt werden. Die Antwort auf eine GET-Anfrage kann auf der Ebene des Dispatchers und des Content Delivery Network (CDN) zwischengespeichert werden, was letztendlich die Leistung der anfragenden Client-Anwendung verbessert. Dies unterscheidet sich von standardmäßigen GraphQL-Abfragen, die mithilfe von 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

Beachten Sie Folgendes: %3B ist die UTF-8-Codierung für ;, und %3D ist die Codierung für =. Die Abfragevariablen und alle Sonderzeichen müssen ordnungsgemäß codiert sein, damit die persistente Abfrage ausgeführt wird.

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

Publishing-Instanzen publish-instances

Für Publishing-Instanzen sind die Standardwerte:

Diese können überschrieben werden:

Verwalten des Caches auf der Ebene der persistenten 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. Lesen Sie Persistieren einer GraphQL-Abfrage, um ein Beispiel für die Persistierung einer Abfrage mithilfe von cURL zu sehen.

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. Andernfalls verwendet diese OSGi-Konfiguration die Standardwerte für Publishing-Instanzen.

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

Damit die Abfrage-URL von einer Anwendung 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.

Beispiel:

curl -X GET \ "https://localhost:4502/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: