Persisted Queries
GraphQLクエリを使用してRESTのような定義済みエンドポイントを作成し、両方のAPIのメリットを得ましょう。
説明
RESTでは、複数のエンドポイントを作成し、それぞれが事前に定義されたデータセットを返します。
| メリット | デメリット |
|---|---|
| ✅ シンプルです | ❌ すべてのエンドポイントを作成するのが面倒です |
✅ GETまたはPOSTでアクセスできます | ❌ エンドポイントの準備ができるまでプロジェクトがボトルネックになる可能性があります |
| ✅ サーバーまたはCDNでキャッシュできます | ❌ ドキュメントの作成が必須です |
| ✅ 安全です：意図したデータのみが公開されます | ❌ アプリケーションがすべてのデータを取得するために複数のリクエストが必要になる場合があり（主にモバイルアプリで）、遅くなる可能性があります |
GraphQLでは、単一のエンドポイントに任意のクエリを送信でき、要求されたデータのみが返されます。
| メリット | デメリット |
|---|---|
| ✅ データのアンダー/オーバーフェッチがありません | ❌ POSTのみでアクセスできます |
| ✅ すべてのデータを1回のリクエストで取得できるため、高速です | ❌ サーバーまたはCDNでキャッシュできないため、本来より遅く、コストがかかります |
| ✅ プロジェクトの迅速な反復が可能です | ❌ ファイルのアップロードやキャッシュなど、車輪の再発明が必要な場合があります |
| ✅ 自己ドキュメント化できます | ❌ N+1問題など、追加の複雑さに対処する必要があります |
| ✅ クエリ用エディター（GraphiQL）を提供しており、作業を簡素化します |
Persisted queriesはこれら2つのアプローチを組み合わせます：
- GraphQLを使用してクエリを作成・解決します
- ただし、単一のエンドポイントを公開する代わりに、各事前定義クエリをそれぞれ独自のエンドポイントで公開します
そのため、RESTのように事前定義されたデータを持つ複数のエンドポイントを得られますが、GraphQLを使用して作成されるため、それぞれのメリットを得ながらデメリットを回避できます：
| メリット | デメリット |
|---|---|
✅ GETまたはPOSTでアクセスできます | |
| ✅ サーバーまたはCDNでキャッシュできます | |
| ✅ 安全です：意図したデータのみが公開されます | |
| ✅ データのアンダー/オーバーフェッチがありません | |
| ✅ すべてのデータを1回のリクエストで取得できるため、高速です | POSTのみでアクセスできます |
| ✅ プロジェクトの迅速な反復が可能です | |
| ✅ 自己ドキュメント化できます | |
| ✅ クエリ用エディター（GraphiQL）を提供しており、作業を簡素化します |
Persisted Queryの実行
persisted queryが公開されると、そのパーマリンクを通じて実行できます。
persisted queryはGETでアクセスするため、ブラウザから直接実行でき、要求したデータをJSON形式で取得できます：
Persisted Queryの作成
メニューのPersisted Queriesリンクをクリックすると、作成済みのすべてのpersisted queryの一覧が表示されます：
persisted queryはカスタム投稿タイプ（CPT）です。新しいpersisted queryを作成するには、「新しいGraphQL persisted queryを追加」ボタンをクリックしてWordPressエディターを開きます：
メインの入力欄はGraphiQLクライアントで、デフォルトでExplorerが付属しています。左サイドパネルのフィールドをクリックするとクエリに追加され、「Run」ボタンをクリックするとクエリが実行されます：
クエリの準備ができたら公開すると、そのパーマリンクがエンドポイントになります。エンドポイント（およびソース）へのリンクは「Persisted Query Endpoint Overview」サイドバーパネルに表示されます：
パーマリンクに?view=sourceを追加すると、persisted queryとその設定が表示されます（ユーザーがログイン済みで、そのユーザーロールがアクセス権を持っている場合）：
デフォルトでは、persisted queryのエンドポイントのパスは/graphql-query/であり、この値はSettingsから設定できます：
スキーマ設定
スキーマに含まれる要素と、ユーザーのアクセス権は、スキーマ設定で定義します。
そのため、スキーマ設定を作成し、ドロップダウンから選択する必要があります：
カテゴリーによるPersisted Queriesの整理
サイドバーパネル「Endpoint categories」では、Persisted Queryの管理に役立つカテゴリーを追加できます：
たとえば、クライアント、アプリケーション、またはその他の必要な情報でエンドポイントを管理するカテゴリーを作成できます：
Persisted Queriesの一覧では、それぞれのカテゴリーを確認できます。カテゴリーリンクをクリックするか、上部のフィルターを使用すると、そのカテゴリーのエントリーのみが表示されます：
プライベートなpersisted queries
Persisted Queryのステータスをprivateに設定すると、そのエンドポイントには管理者ユーザーのみがアクセスできます。これにより、アクセスすべきでないユーザーにデータが意図せず共有されることを防ぎます。
たとえば、メトリクスのレポートを作成するためのデータ取得など、アプリケーション管理に役立つプライベートなPersisted Queriesを作成できます。
パスワード保護されたpersisted queries
特定のクライアント向けにPersisted Queryを作成する場合、パスワードを設定して、そのクライアントのみがエンドポイントにアクセスできるよう、追加のセキュリティレベルを提供できます。
パスワード保護されたpersisted queryに初めてアクセスすると、パスワードを要求する画面が表示されます：
パスワードが入力・検証されて初めて、ユーザーは意図したエンドポイントにアクセスできます。
URLパラメーターによるpersisted queryの動的化
各変数の値は、persisted queryの実行時にURLパラメーター（変数名を使用）で設定できます。「URLパラメーターは変数を上書きしますか？」オプションが有効な場合、URLパラメーターが優先されます。それ以外の場合、変数ディクショナリで定義された値が優先されます（存在する場合）。
たとえば、このクエリでは結果の件数が変数$limitで制御されており、デフォルト値は3です：
このpersisted queryを実行する際に?limit=5を渡すと、5件の結果を返すクエリが実行されます：
