GraphiQL IDE の使用

標準の GraphQL IDE の実装は、Adobe Experience Manager(AEM)as a Cloud Service の GraphQL API で使用できます。

メモ

GraphiQL は AEM のすべての環境に含まれています(ただし、エンドポイントを設定した場合にのみアクセス可能/表示可能になります)。

以前のリリースでは、GraphiQL IDE をインストールするためにパッケージが必要でした。これをインストール済みの場合は、削除できます。

メモ

GraphiQL IDE を使用する前に、設定ブラウザーエンドポイントを設定しておく必要があります。

GraphiQL ツールを使用すると、次のことが可能になるので、GraphQL クエリをテストおよびデバッグできます。

  • クエリに使用する Sites 設定に適した​エンドポイント​を選択する
  • 新しいクエリを直接入力する
  • 永続クエリ​を作成してアクセスする
  • クエリを実行して結果をすぐに確認する
  • クエリ変数​を管理する
  • 永続クエリ​を保存して管理する
  • 永続クエリ​を公開または非公開にする(dev-publish との間など)
  • 以前のクエリの​履歴​を確認する
  • ドキュメントエクスプローラー​を使用してドキュメントにアクセスし、使用可能な方法を学び理解するのに役立てる

クエリエディターには、次のいずれかの方法でアクセスできます。

  • ツール一般GraphQL クエリエディター
  • 直接アクセス(例:http://localhost:4502/aem/graphiql.html
GraphiQL インターフェイス

システムで GraphiQL を使用すると、GET リクエストを使用してクライアントアプリケーションからクエリをリクエストしたり、クエリを公開したりできます。実稼動環境で使用する場合は、その後クエリを実稼動環境に移動できます。最初は実稼動オーサーに移行して、新しくオーサリングしたコンテンツをクエリで検証し、最終的には実稼動パブリッシュに移行してライブで利用できるようにします。

エンドポイントの選択

まず、クエリに使用する​エンドポイント​を選択する必要があります。クエリに使用する Sites 設定に適したエンドポイントです。

これは、右上のドロップダウンリストから選択できます。

新しいクエリの作成と永続化

エディターに新しいクエリを入力できます(エディターは左中央パネルの GraphiQL ロゴのすぐ下にあります)。

メモ

永続クエリが既に選択されていて、エディターパネルに表示されている場合は、(永続クエリ​の横にある)「+」を選択してエディターを空にし、新しいクエリを作成できるようにします。

入力を開始します。エディターには次の機能があります。

  • マウスオーバーを使用して、要素に関する追加情報を表示します
  • 構文のハイライト表示、オートコンプリート、自動候補表示などの機能が用意されています
メモ

GraphQL クエリは通常、{ 文字で始まります。

# で始まる行は無視されます。

名前を付けて保存」を使用して、新しいクエリを永続化します。

永続クエリの更新

更新するクエリを(左端の)永続クエリ​パネルのリストから選択します。

クエリがエディターパネルに表示されます。必要な変更を加えたあと、「保存」を使用して、更新内容を永続クエリにコミットします。

クエリの実行

新しいクエリをすぐに実行することもできますし、永続クエリを読み込んで実行することもできます。永続クエリを読み込むには、該当するクエリをリストから選択します。そのクエリがエディターパネルに表示されます。

どちらの場合も、エディターパネルに表示されるクエリは、次のいずれかの場合に実行されるクエリです。

  • クエリを実行」アイコンをクリックまたはタップする
  • キーボードショートカット Control-Enter を使用する

クエリ変数

また、GraphiQL IDE では、クエリ変数を管理することもできます。

次に例を示します。

GraphQL 変数

永続クエリのキャッシュの管理

永続クエリは、Dispatcher と CDN レイヤーでキャッシュできるので推奨されます。これにより、最終的に要求元のクライアントアプリケーションのパフォーマンスが向上します。デフォルトでは、AEM はデフォルトの有効期間(TTL)に基づいてコンテンツ配信ネットワーク(CDN)のキャッシュを無効にします。

メモ

Dispatcher 上のカスタム書き換えルールが、AEM publish のデフォルトを上書きする場合があります。

TTL ベースのキャッシュ制御ヘッダーを Dispatcher から送信する場合、場所の一致パターンに基づいて、必要に応じて除外することができます /graphql/execute.json/* マッチから

GraphQL を使用すると、HTTP キャッシュヘッダーを設定することにより、個々の永続クエリ用にこれらのパラメーターを制御できます。

  1. ヘッダー」オプションには、永続クエリ名(左端のパネル)の右側にある 3 つの縦並びのドットからアクセスできます。

    永続クエリ HTTP キャッシュヘッダー
  2. これを選択すると、キャッシュ設定​ダイアログが開きます。

    永続クエリ HTTP キャッシュヘッダー設定
  3. 適切なパラメーターを選択し、必要に応じて次の値を調整します。

    • cache-control - max-age
      キャッシュは、指定された秒数間、このコンテンツを保存できます。通常、これはブラウザーの TTL(有効期間)です。
    • surrogate-control - s-maxage
      max-age と同じですが、特にプロキシキャッシュに適用されます。
    • surrogate-control - stale-while-revalidate
      キャッシュは、古くなった後も、指定された秒数までキャッシュされた応答を引き続き提供します。
    • surrogate-control - stale-if-error
      キャッシュは、オリジンエラーが発生した場合、指定された秒数までキャッシュされた応答を引き続き提供します。
  4. 保存」を選択して、変更内容を保持します。

永続クエリの公開

リスト(左パネル)から永続クエリを選択したら、「公開」アクションと「非公開」アクションを使用できます。これにより、パブリッシュ環境(dev-publish など)に対してアクティブ化され、テスト時にアプリケーションから簡単にアクセスできるようになります。

メモ

永続クエリのキャッシュ Time To Live {"cache-control":"parameter":value} の定義では、デフォルト値は 2 時間(7200 秒)になっています。

URL をコピーしてクエリに直接アクセスする

URL をコピー」オプションを使用すると、永続クエリに直接アクセスする URL をコピーしてクエリをシミュレートし、結果を確認することができます。これは、ブラウザーでアクセスするなどしてテストに使用できます。

次に例を示します。

http://localhost:4502/graphql/execute.json/global/article-list-01

この URL をブラウザーで使用すると、結果を確認できます。

GraphiQL - 「URL をコピー」

URL をコピー」オプションには、永続クエリ名(左端のパネル)の右側にある 3 ドットアイコンを使用してアクセスできます。

GraphiQL - 「URL をコピー」

永続クエリの削除

永続クエリ名(左端のパネル)の右側にある 3 ドットアイコンを使用すると、「削除」オプションにもアクセスできます。

実稼動環境への永続クエリのインストール

GraphiQL を使用して永続クエリを作成およびテストした後は、その永続クエリを実稼動環境に転送してアプリケーションで使用できるようにします。

キーボードショートカット

IDE のアクションアイコンに直接アクセスできる一連のキーボードショートカットが用意されています。

  • クエリの修飾:Shift-Control-P
  • クエリの結合:Shift-Control-M
  • クエリの実行:Control-Enter
  • オートコンプリート:Control-Space
メモ

一部のキーボードでは、Control キーには Ctrl のラベルが付いています。

このページ