永続的な GraphQL クエリ persisted-graphql-queries

永続的なクエリは、Adobe Experience Manager（AEM）as a Cloud Service サーバーで作成および保存される GraphQL クエリです。永続的なクエリは、クライアントアプリケーションから GET リクエストでリクエストできます。GET リクエストの応答は、Dispatcher および CDN レイヤーでキャッシュできるので、最終的には、要求元のクライアントアプリケーションのパフォーマンスが向上します。これは、標準の GraphQL クエリとは異なります。標準クエリは、応答を簡単にはキャッシュできない POST リクエストを使用して実行されます。

AEM では GraphiQL IDE を使用して、実稼動環境に移行する前に GraphQL クエリを開発、テストおよび永続化できます。カスタマイズが必要な場合（例えば、キャッシュをカスタマイズする場合）、API を使用できます。GraphQL クエリを永続化する方法で示される cURL の例を参照してください。

永続的なクエリとエンドポイント persisted-queries-and-endpoints

持続的なクエリでは、常に適切な Sites 設定に関連するエンドポイントを使用する必要があるため、次のどちらかまたは両方を使用できます。

例えば、my-query という特定のクエリがあり、このクエリが Sites 設定 my-conf のモデル my-model を使用する場合は、次のようになります。

GraphQL クエリを永続化する方法 how-to-persist-query

最初に AEM オーサー環境でクエリを永続化し、その後、アプリケーションで使用するために、実稼動 AEM パブリッシュ環境にクエリを移行することをお勧めします

クエリを永続化するには、次のような様々な方法があります。

GraphiQL IDE は、クエリを保持するための​ 推奨 ​される方法です。cURL コマンドラインツールを使用して特定のクエリを永続化するには、次の手順に従います。

永続クエリの実行方法 execute-persisted-query

永続クエリを実行するには、クライアントアプリケーションで次の構文を使用して GET リクエストを実行します。

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

PERSISTENT_PATH は、永続クエリが保存される場所への短縮パスです。

クエリ変数の使用 query-variables

クエリ変数は、永続クエリで使用できます。クエリ変数をリクエストに付加するには、先頭にセミコロン（;）を付けた変数名と値を使用します。複数の変数はセミコロンで区切ります。

次のようなパターンになります。

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

例えば、次のクエリには、アクティビティ値に基づいてリストをフィルタリングするための変数 activity が含まれています。

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

このクエリは、パス wknd/adventures-by-activity の下に保持できます。activity=Camping で永続クエリを呼び出すには、リクエストは次のようになります。

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

UTF-8 エンコーディング %3B は ; に使用されます。また、%3D は = のエンコーディングです。永続クエリを実行するには、クエリ変数と特殊文字を適切にエンコードする必要があります。

クエリ変数の使用：ベストプラクティス query-variables-best-practices

クエリで変数を使用する場合、次のベストプラクティスに従う必要があります。

永続クエリのキャッシュ caching-persisted-queries

永続クエリが推奨されるのは、Dispatcher と CDN（コンテンツ配信ネットワーク）レイヤーでキャッシュされ、最終的に要求元のクライアントアプリケーションのパフォーマンスを向上させることができるからです。

デフォルトでは、AEM は有効期間（TTL）の定義に基づいてキャッシュを無効にします。これらの TTL は、次のパラメーターで定義できます。これらのパラメーターには様々な方法でアクセスでき、使用するメカニズムに応じて名前が異なります。

オーサーインスタンス author-instances

オーサーインスタンスの場合、デフォルト値は次のとおりです。

これらは

パブリッシュインスタンス publish-instances

パブリッシュインスタンスの場合、デフォルト値は次のとおりです。

これらは、次のように上書きできます。

GraphiQL IDE の HTTP キャッシュヘッダーの管理 http-cache-headers-graphiql-ide

GraphiQL IDE - 永続クエリの保存を参照してください。

永続クエリレベルでのキャッシュの管理 cache-persisted-query-level

これを行うには、コマンドラインインターフェイスで cURL を使用して AEM にクエリを実行する必要があります。

PUT（作成）メソッドの例を次に示します。

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} }'

POST（更新）メソッドの例を次に示します。

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} }'

cache-control は、作成時に設定することもできますし（PUT リクエストを使用）、後で設定することもできます（例えば、POST リクエストを使用）。AEM ではデフォルト値を提供できるので、永続クエリを作成する際に cache-control はオプションです。cURL を使用してクエリを永続化する例については、GraphQL クエリを永続化する方法を参照してください。

Cloud Manager 変数を使用したキャッシュの管理 cache-cloud-manager-variables

Cloud Manager 環境変数は、Cloud Manager で定義して必要な値を定義できます。

OSGi 設定を使用したキャッシュの管理 cache-osgi-configration

キャッシュをグローバルに管理するには、永続クエリサービス設定 ​の OSGi 設定を行います。

パブリッシュインスタンスのデフォルトの OSGi 設定は次のとおりです。

クエリ応答コードの設定 configuring-query-response-code

デフォルトでは、PersistedQueryServlet はクエリの実行時に、（実際の結果に関係なく）200 応答を返します。

永続クエリサービス設定 ​の OSGi 設定を指定して、永続クエリにエラーがある場合に、/execute.json/persisted-query エンドポイントで詳細なステータスコードが返されるかどうかを制御できます。

フィールド Respond with application/graphql-response+json（responseContentTypeGraphQLResponseJson）は必要に応じて次のように定義できます。

アプリで使用するクエリ URL のエンコード encoding-query-url

アプリケーションで使用するには、クエリ変数の構築時に使用される特殊文字（セミコロン（;）、等号（=）、スラッシュ（/））を、対応する UTF-8 エンコーディングで変換する必要があります。

次に例を示します。

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"

URL は次の部分に分解できます。

プレーンテキストでは、リクエスト URI は次のようになります。

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

クライアントアプリで永続クエリを使用するには、AEM ヘッドレス クライアント SDK を JavaScript、Java または NodeJS に使用する必要があります。ヘッドレスクライアント SDK は、自動的にリクエスト内のクエリ変数を適切にエンコードします。

実稼動環境への永続クエリの移行 transfer-persisted-query-production

永続クエリは、常に、AEM オーサーサービスで作成してから、AEM パブリッシュサービスに公開（レプリケート）する必要があります。多くの場合、永続クエリは、ローカル環境や開発環境などの下位環境で作成およびテストされます。その後、永続クエリを上位レベルの環境に昇格し、最終的に実稼動 AEM パブリッシュ環境で使用できるようにして、クライアントアプリケーションが使用できるようにする必要があります。

永続クエリのパッケージ化

永続クエリは、AEM パッケージに組み込むことができます。その後、AEM パッケージをダウンロードして、様々な環境にインストールできます。AEM パッケージは、AEM オーサー環境から AEM パブリッシュ環境にレプリケートすることもできます。

パッケージを作成するには：

パッケージが構築されたら、次の操作を実行できます。