永続的なクエリは、Adobe Experience Manager(AEM)as a Cloud Serviceサーバーで作成および保存される GraphQL クエリです。 クライアントアプリケーションは、GETリクエストを使用してリクエストできます。 GET リクエストの応答は、Dispatcher および CDN レイヤーでキャッシュできるので、最終的には、要求元のクライアントアプリケーションのパフォーマンスが向上します。これは、標準の GraphQL クエリとは異なります。標準クエリは、応答を簡単にキャッシュできないPOSTリクエストを使用して実行されます。
永続化されたクエリをお勧めします。 詳しくは、 GraphQL クエリのベストプラクティス (Dispatcher) を参照してください。
この GraphiQL IDE は、以前にAEMで GraphQL クエリを開発、テスト、永続化できます。 実稼動環境への移行. カスタマイズが必要な場合 ( 例: キャッシュのカスタマイズ) を使用すると、API を使用できます。次に示す curl の例を参照してください: GraphQL クエリを保持する方法.
持続的なクエリでは、常に適切な Sites 設定に関連するエンドポイントを使用する必要があるため、次のどちらかまたは両方を使用できます。
詳しくは、設定ブラウザーでのコンテンツフラグメント機能の有効化を参照してください。
この GraphQL 永続的なクエリ 適切な Sites 設定に対して有効にする必要があります。
例えば、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
は、 ;
および %3D
は =
. クエリ変数と特殊文字は、次の条件を満たす必要があります。 適切にエンコード を実行します。
アプリケーションで使用する場合、クエリ変数を構築する際に使用される特殊文字 ( セミコロン (;
),等号 (=
)、スラッシュ /
) は、対応する 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
.パッケージが構築されたら、次の操作を実行できます。