永続的なクエリは、Adobe Experience Manager(AEM)as a Cloud Service サーバーで作成および保存される GraphQL クエリです。永続的なクエリは、クライアントアプリケーションから GET リクエストでリクエストできます。GET リクエストの応答は、Dispatcher および CDN レイヤーでキャッシュできるので、最終的には、要求元のクライアントアプリケーションのパフォーマンスが向上します。これは、標準の GraphQL クエリとは異なります。標準クエリは、応答を簡単にはキャッシュできない POST リクエストを使用して実行されます。
永続クエリをお勧めします。詳しくは、GraphQL クエリのベストプラクティス(Dispatcher)と、関連する Dispatcher の設定を参照してください。
AEM では GraphiQL IDE を使用して、実稼動環境に移行する前に GraphQL クエリを開発、テスト、保持できます。カスタマイズが必要な場合(例えば、キャッシュをカスタマイズする場合)、API を使用できます。GraphQL クエリを永続化する方法で示される cURL の例を参照してください。
持続的なクエリでは、常に適切な Sites 設定に関連するエンドポイントを使用する必要があるため、次のどちらかまたは両方を使用できます。
詳しくは、設定ブラウザーでのコンテンツフラグメント機能の有効化を参照してください。
適切な Sites 設定用に、GraphQL 永続クエリを有効にする必要があります。
例えば、my-query
という特定のクエリがあり、このクエリが Sites 設定 my-conf
のモデル my-model
を使用する場合は、次のようになります。
my-conf
を使用してクエリを作成すると、クエリは次のように保存されます。/conf/my-conf/settings/graphql/persistentQueries/my-query
global
エンドポイントを使用して同じクエリを作成できますが、クエリは次のように保存されます。/conf/global/settings/graphql/persistentQueries/my-query
これらは 2 つの異なるクエリで、異なるパスに保存されます。
同じモデルを使用していますが、異なるエンドポイントを介しています。
最初に AEM オーサー環境でクエリを永続化し、その後、アプリケーションで使用するために、実稼動 AEM パブリッシュ環境にクエリを移行することをお勧めします
クエリを永続化するには、次のような様々な方法があります。
GraphiQL IDE は、クエリを保持するための推奨される方法です。cURL コマンドラインツールを使用して特定のクエリを保持する手順は次のとおりです。
新しいエンドポイント URL /graphql/persist.json/<config>/<persisted-label>
に PUT してクエリを準備します。
例えば、次のようにして、永続的クエリを作成します。
$ curl -X PUT \
-H 'authorization: Basic YWRtaW46YWRtaW4=' \
-H "Content-Type: application/json" \
"http://localhost:4502/graphql/persist.json/wknd/plain-article-query" \
-d \
'{
articleList {
items{
_path
author
main {
json
}
}
}
}'
この段階で、応答を確認します。
例えば、以下が成功するかどうかを確認します。
{
"action": "create",
"configurationName": "wknd",
"name": "plain-article-query",
"shortPath": "/wknd/plain-article-query",
"path": "/conf/wknd/settings/graphql/persistentQueries/plain-article-query"
}
その後、URL /graphql/execute.json/<shortPath>
を GET して、永続的クエリをリクエストできます。
例えば、次のような永続的クエリを使用します。
$ curl -X GET \
http://localhost:4502/graphql/execute.json/wknd/plain-article-query
既存のクエリパスに POST して、永続的クエリを更新します。
例えば、次のような永続的クエリを使用します。
$ curl -X POST \
-H 'authorization: Basic YWRtaW46YWRtaW4=' \
-H "Content-Type: application/json" \
"http://localhost:4502/graphql/persist.json/wknd/plain-article-query" \
-d \
'{
articleList {
items{
_path
author
main {
json
}
referencearticle {
_path
}
}
}
}'
ラップされたプレーンクエリを作成します。
次に例を示します。
$ curl -X PUT \
-H 'authorization: Basic YWRtaW46YWRtaW4=' \
-H "Content-Type: application/json" \
"http://localhost:4502/graphql/persist.json/wknd/plain-article-query-wrapped" \
-d \
'{ "query": "{articleList { items { _path author main { json } referencearticle { _path } } } }"}'
キャッシュコントロール付きのラップされたプレーンクエリを作成します。
次に例を示します。
$ curl -X PUT \
-H 'authorization: Basic YWRtaW46YWRtaW4=' \
-H "Content-Type: application/json" \
"http://localhost:4502/graphql/persist.json/wknd/plain-article-query-max-age" \
-d \
'{ "query": "{articleList { items { _path author main { json } referencearticle { _path } } } }", "cache-control": { "max-age": 300 }}'
パラメーター付きの永続的クエリを作成します。
次に例を示します。
$ curl -X PUT \
-H 'authorization: Basic YWRtaW46YWRtaW4=' \
-H "Content-Type: application/json" \
"http://localhost:4502/graphql/persist.json/wknd/plain-article-query-parameters" \
-d \
'query GetAsGraphqlModelTestByPath($apath: String!, $withReference: Boolean = true) {
articleByPath(_path: $apath) {
item {
_path
author
main {
plaintext
}
referencearticle @include(if: $withReference) {
_path
}
}
}
}'
永続クエリを実行するには、クライアントアプリケーションで次の構文を使用して GET リクエストを実行します。
GET <AEM_HOST>/graphql/execute.json/<PERSISTENT_PATH>
PERSISTENT_PATH
は、永続クエリが保存される場所への短縮パスです。
例えば、wknd
は設定名で、plain-article-query
は永続クエリの名前です。クエリを実行するには:
$ curl -X GET \
https://publish-p123-e456.adobeaemcloud.com/graphql/execute.json/wknd/plain-article-query
パラメーター付きのクエリを実行します。
永続クエリを実行する場合は、クエリ変数と値を適切にエンコードする必要があります。
次に例を示します。
$ curl -X GET \
"https://publish-p123-e456.adobeaemcloud.com/graphql/execute.json/wknd/plain-article-query-parameters%3Bapath%3D%2Fcontent%2Fdam%2Fwknd%2Fen%2Fmagazine%2Falaska-adventure%2Falaskan-adventures%3BwithReference%3Dfalse
詳しくは、クエリ変数の使用を参照してください。
クエリ変数は、永続クエリで使用できます。クエリ変数をリクエストに付加するには、先頭にセミコロン(;
)を付けた変数名と値を使用します。複数の変数はセミコロンで区切ります。
次のようなパターンになります。
<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
なお、%3B
は ;
の UTF-8 エンコーディングで、%3D
は =
のエンコーディングです。永続クエリを実行するには、クエリ変数と特殊文字を適切にエンコードする必要があります。
永続クエリが推奨されます。永続クエリは、Dispatcher とコンテンツ配信ネットワーク(CDN)レイヤーでキャッシュされ、最終的に要求元のクライアントアプリケーションのパフォーマンスを向上させることができるためです。
デフォルトでは、AEM は有効期間(TTL)の定義に基づいてキャッシュを無効にします。これらの TTL は、次のパラメーターで定義できます。これらのパラメーターには様々な手段でアクセスでき、使用するメカニズムに応じて異なる名前で呼ばれます。
キャッシュタイプ | HTTP ヘッダー | cURL | OSGi 設定 | Cloud Manager |
---|---|---|---|---|
ブラウザー | max-age |
cache-control : max-age |
cacheControlMaxAge |
graphqlCacheControl |
CDN | s-maxage |
surrogate-control : max-age |
surrogateControlMaxAge |
graphqlSurrogateControl |
CDN | stale-while-revalidate |
surrogate-control : stale-while-revalidate |
surrogateControlStaleWhileRevalidate |
graphqlStaleWhileRevalidate |
CDN | stale-if-error |
surrogate-control : stale-if-error |
surrogateControlStaleIfError |
graphqlStaleIfError |
オーサーインスタンスの場合、デフォルト値は次のとおりです。
max-age
:60s-maxage
:60stale-while-revalidate
:86400stale-if-error
:86400これらは
cache-control
や surrogate-control
に適した設定を含む必要があります。例として、永続クエリレベルでのキャッシュの管理を参照してください。パブリッシュインスタンスの場合、デフォルト値は次のとおりです。
max-age
:60s-maxage
:7200stale-while-revalidate
:86400stale-if-error
:86400これらは、次のように上書きできます。
永続クエリレベルで。これを行うには、コマンドラインインターフェイスで cURL を使用して AEM にクエリを実行し、永続クエリを公開する必要があります。
GraphiQL IDE - 永続クエリの保存を参照してください。
これを行うには、コマンドラインインターフェイスで 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 環境変数は、Cloud Manager で定義して必要な値を定義できます。
名前 | 値 | 適用されるサービス | タイプ |
---|---|---|---|
graphqlStaleIfError |
86400 | 適宜 | 適宜 |
graphqlSurrogateControl |
600 | 適宜 | 適宜 |
キャッシュをグローバルに管理するには、永続クエリサービス設定の OSGi 設定を行います。
OSGi 設定は、パブリッシュインスタンスにのみ適しています。この設定はオーサーインスタンス上に存在しますが、無視されます。
パブリッシュインスタンスのデフォルトの OSGi 設定は次のとおりです。
使用可能な場合、次の Cloud Manager 変数を読み取ります。
OSGi 設定のプロパティ | 読み取り対象 | Cloud Manager 変数 |
---|---|---|
cacheControlMaxAge |
が読み取るのは | graphqlCacheControl |
surrogateControlMaxAge |
が読み取るのは | graphqlSurrogateControl |
surrogateControlStaleWhileRevalidate |
が読み取るのは | graphqlStaleWhileRevalidate |
surrogateControlStaleIfError |
が読み取るのは | graphqlStaleIfError |
使用できない場合、OSGi 設定はパブリッシュインスタンスのデフォルト値を使用します。
アプリケーションで使用するには、クエリ変数の構築時に使用される特殊文字(セミコロン(;
)、等号(=
)、スラッシュ(/
))を、対応する 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 は次の部分に分解できます。
URL の部分 | 説明 |
---|---|
/graphql/execute.json |
永続クエリのエンドポイント |
/wknd/adventure-by-path |
永続クエリのパス |
%3B |
; のエンコーディング |
adventurePath |
クエリ変数 |
%3D |
= のエンコーディング |
%2F |
/ のエンコーディング |
%2Fcontent%2Fdam... |
コンテンツフラグメントへのエンコードされたパス |
プレーンテキストでは、リクエスト 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 は、自動的にリクエスト内のクエリ変数を適切にエンコードします。
永続クエリは、常に、AEM オーサーサービスで作成してから、AEM パブリッシュサービスに公開(レプリケート)する必要があります。多くの場合、永続クエリは、ローカル環境や開発環境などの下位環境で作成およびテストされます。その後、永続クエリを上位レベルの環境に昇格し、最終的に実稼動 AEM パブリッシュ環境で使用できるようにして、クライアントアプリケーションが使用できるようにする必要があります。
永続クエリは、AEM パッケージに組み込むことができます。その後、AEM パッケージをダウンロードして、様々な環境にインストールできます。AEM パッケージは、AEM オーサー環境から AEM パブリッシュ環境にレプリケートすることもできます。
パッケージを作成するには:
persistentQueries
フォルダーを選択します。例えば、wknd
設定の場合、フルパスは /conf/wknd/settings/graphql/persistentQueries
になります。パッケージが構築されたら、次の操作を実行できます。