Sitecore GraphQLのベスト プラクティス
このページの翻訳はAIによって自動的に行われました。可能な限り正確な翻訳を心掛けていますが、原文と異なる表現や解釈が含まれる場合があります。正確で公式な情報については、必ず英語の原文をご参照ください。
Sitecore GraphQL APIを使用する際は、次のベスト プラクティスに従うことをお勧めします。
コンテキストアウェアエンドポイントを使用する
公開サイトの場合は、データベース コンテキスト対応エンドポイントを使用して、正しいコンテンツ データベース (master/web/etc) を尊重します。これにより、APIは認証モード (プレビュー、エクスペリエンス エディター) で適切なアイテム データを返すようになります。
エンドポイントをコンテキスト対応にするには、次のようにします。
-
エンドポイントがtypeとして定義されていることを確認します Sitecore.Services.GraphQL.Hosting.DatabaseAwareGraphQLEndpoint, Sitecore.Services.GraphQL.NetFxHost
-
ContentSchemaProviderのデータベース設定を構成するときは、実際のデータベース名ではなくcontextに設定します。これにより、Sitecore.Context.Databaseに従うようになります。
-
コンテキスト対応エンドポイントはデータベースごとに異なるスキーマを提供するため、masterに対して検証するクエリは、その背後にあるテンプレートが公開されていない場合、webに対して検証されない可能性があることに注意してください。
-
エンドポイントがデータベース固有のコンテンツを提供していない場合は、コンテキスト対応エンドポイントにしないでください。これは、たとえば、CRMに接続したり、分析データをプッシュしたりするためにのみ指定するエンドポイントです。
公開Webサイトでサブスクリプションを使用しない
公開WebサイトでGraphQLサブスクリプションを使用しないでください。
サブスクリプションは、作成者が使用するコンテンツ管理サーバーのカスタマイズに使用することを目的としています。Sitecoreは、スケーリングされたパブリック環境でのサブスクリプションの使用をサポートしていません。
独自のグラフタイプを実装する
独自のグラフタイプを実装する
独自のIGraphType実装でフィールドを定義する方法には、多くのオプションがあります。
一般に、最もパフォーマンスが高く、最も柔軟性の高いオプションは、Fieldメソッドを使用し、グラフの種類を明示的に指定し、名前付きリゾルバー関数を使用することです。これにより、エラーが発生したときに適切なスタックトレースを取得できます。次に例を示します。
任意の階層の処理
データの種類によっては、GraphQLで使いにくいもの、特に任意にネストされた階層があります。
たとえば、アイテムのすべての子孫を取得する必要があり、子のレベル数が不明な場合、GraphQLでは、必要なグラフの部分を指定する必要があるため、これをサポートしていません。
別のケースとして、フィールドのセットを常に一緒にしたい場合、またはまったく組み合わせない場合があります (たとえば、レンダリングツールキットで使用される任意のJSONのブロックで、ユーザーにGraphQLフラグメントを記憶させたくない場合など)。この場合、JsonGraphTypeを使用できます。このタイプを使用すると、任意のJSONをGraphQLフィールドとして返すことができます。これは、グラフがデータを適切に表現できない場合の最後の手段です。JsonGraphTypeのリゾルバーは、任意のオブジェクト (シリアル化) またはJToken (そのまま使用) を返すことができます。
JsonGraphTypeは入力グラフタイプとしても使用でき、その場合は値をエスケープされた文字列として渡す必要があります。これは、実際のJSONがエスケープされずに返される出力タイプとは異なります。
フロントエンドからGraphQL APIを使用する
フロントエンドからGraphQL APIを使用する
フロントエンドからGraphQL APIを使用する場合は、次のことをお勧めします。
-
フロントエンドサイトまたはアプリケーションにGraphQL APIを使用する場合は、常にそのサイトに対して独自のエンドポイントを定義してください。これにより、APIの攻撃対象領域、認証、URLをきめ細かく制御できます。公開するAPIはできるだけ小さくします。
-
スキーマ プロバイダー ( ContentSchemaProviderなど) を再利用します (既に存在する場合)。
-
クエリを .graphqlファイルに分割します。それらをコードと混同しないでください。
-
これにより、懸念事項が適切に分離され、次のようなツールを使用するとgraphql-tag/loader、JavaScriptファイルと同じ方法でファイルをインポートできます。
-
静的に分析可能なクエリを使用すると、ビルド時にすべてのクエリを検証したり、セキュリティ ホワイトリストを実行したり、その他の一般的な操作を実行したりすることが容易になります。
-
これが不可能な場合 (たとえば、現在Angularでは、ビルドをカスタマイズしてGraphQLローダーを追加することはできません)、クエリを .jsファイルまたはAngularコンポーネントのmycomponent.graphql.tsなど、クエリのみを含む.tsファイルに分割します。
-
-
動的な文字列連結クエリ (クエリ テキストにGraphQL以外の変数を使用) は使用しないでください。クエリ変数は、常にGraphQLクエリ変数である必要があります。
-
これは、ホワイトリスト、静的分析、パフォーマンス分析を打ち負かし、一般的には悪い考えです。
-
-
クエリのバッチ処理を利用します。
-
RESTに対するGraphQLの主な利点の1つは、GraphQLがプロトコルであるため、RESTではできないことの一部を実行できることです。
-
クエリのバッチ処理により、複数のクエリ (短時間内に行われた) を1つのHTTP要求に自動的に結合できます。
-
-
ツールを使用して、GraphQLクエリがGraphQLスキーマに対して有効であることを確認します ( eslint-plugin-graphqlなど)。
-
これにより、ビルド時の安全性が確保され、クエリ式が有効であり、実行時に中断されません。
-
Sitecore GraphQLとGraphQLツールを併用する
Sitecore GraphQLとGraphQLツールを併用する
多くの種類のGraphQLツール (ビルド時にクエリを検証するeslint-plugin-graphql 、切断されたモックGraphQL APIを作成するgraphql-tools 、TypeScriptでGraphQLのコード補完を提供するts-graphql-pluginなど) は、正しく実行するにはGraphQLスキーマのコピーが必要です。場合によっては、これをSitecoreインスタンスから直接ダウンロードして、ライブ スキーマを持つことができます。ただし、それ以外の場合はライブSitecoreインスタンスがないため、スキーマの静的コピーが必要です。
スキーマ入力には、主に2つのタイプがあります。
-
JSON形式のスキーマ。これは、GraphQL APIに対するイントロスペクションクエリの結果です。これは、GraphiQLがブラウザにドキュメントを提供するなどに使用するものです。
-
スキーマ定義言語スキーマ。これは、スキーマを読み取り可能な形式で定義するテキスト形式です。これをダウンロードするには、$endpointUrl/schemaにアクセスしてコンテンツを取得し、.graphqlファイルとして保存します。
Sitecore設定の変更 (テンプレートの変更や追加など) により、GraphQLスキーマが変更されます。静的スキーマファイルを使用する場合は、誤った検証を避けるために、常に最新の状態に保たれるようにする必要があります。