Experience Edgeスキーマ

Sitecoreのコンセプト

• Items - Sitecoreでは、すべてがアイテムとして扱われます
  、コンポーネントデータソース、メディアファイルなど。アイテムはコンテンツツリーに存在し、グローバルに一意な識別子(GUID)またはパスで識別されます。
• Templates - すべてのアイテムには、アイテムのプロパティやフィールドを定義するデータテンプレートがあります。GraphQLでは、インラインフラグメントを使ってテンプレート型にアイテムをキャストし、テンプレート固有のフィールドにアクセスできます。
• Layout - レイアウトは、ページ上にどのコンポーネントがどこに表示されるかを定義します。レイアウトクエリのrenderedフィールドはこの完全な構造をJSONとして返し、フロントエンドアプリがレイアウトをレンダリングする準備が整います。
• Sites - Sitecoreインスタンスは複数のサイトをホストできます。ほとんどのクエリには site の引数が必要です。

クエリのエントリポイント

GraphQL APIには4つのトップレベルクエリがあります:

1. item - GUIDまたはパスによるコンテンツアイテムのクエリ。ナビゲーションデータや設定など、ページルートに紐づかないコンテンツには使うと良いです。
2. layout - ページレンダリングに一般的に使われます。サイト、ルートパス、言語が与えられると、SitecoreAIページのレイアウトデータを全て返します。renderedフィールドは、コンポーネント、フィールド値、フロントエンドアプリがレンダリングするネストされたプレースホルダー構造を含むすべてのページレイアウトデータを取得するためのものです。
3. search- インデックス付きプロパティで、CONTAINSやEQなどの演算子を用いたwhere条件を用いてアイテムをクエリ。リスティングやフィルター済みの結果、または複数の商品を同時に扱う必要がある時に使ってください。
4. site - サイト自体に関するクエリ(内容ではなく)に関する問い合わせ。例えば、ルートリスト(静的生成に有用)、リダイレクトルール、エラーページ、サイトマップ、辞書エントリ、ロボット設定などです。

これらのエントリーポイントはGraphQL IDE DOCSタブにも掲載されており、GraphQL参照ドキュメントを閲覧・探索できます。

テンプレート投影

Experience Edgeスキーマで利用可能なタイプは、公開されたSitecoreインスタンスのテンプレート定義を反映しています。特定のタイプからフィールドを選択するインラインフラグメントを使用することで、強力型テンプレートフィールドを有効にすることができます。

Sitecoreのバックエンドでは、テンプレートやフィールドに同じ名前を付けることができます。しかし、GraphQLでは型やフィールドの名前は一意でなければなりません。命名衝突が発生すると、最も新しい作成日のアイテムまたはフィールドアイテムが _{guid} 名前に付加されます。作成日が使われるのは、順序が安定していなければならず、グラフ型の名前は参照後に決して変更されてはならないからです。

GraphQL型は、以下のルートでテンプレートに対して生成されます:

• /sitecore/templates/Foundation
• /sitecore/templates/Feature
• /sitecore/templates/Project
• /sitecore/templates/User Defined

ページ分け

ページ分けを使って、大きな結果セットを小さく予測可能なチャンクにまとめて取得しましょう。

Experience Edgeスキーマ内のページ内検索クエリやフィールド、例えば検索クエリは、カーソルベースのシステムを使って結果ページをリクエストします。

ページ付きクエリについて以下の点に注目してください:

• クエリの引数にはfirst (リクエストあたり返すべき結果数)とafter (最初のカーソル)が含まれます。 firstのデフォルト値は10 、最大値は1000です。

• クエリ結果には、hasNext(結果が複数あるかどうか)とendCursor(次のページを得るために使われる)を含むpageInfoが含まれます。

• クエリ結果にはtotal (利用可能な結果の総数を示す)も含まれます。

  合計1000件以上の結果を取得するには、複数のリクエストを行ってください。各応答のendCursorpageInfo値を次のリクエストのafter引数として使い、hasNextがfalseになるまで繰り返します。複数のページ付きリクエストで取得できる結果の総数に制限はありません。

  !注最初の引数は、Previewスキーマの基盤となるGraphQLライブラリで使われる複雑度計算を問い合わせる特別な意味を持ちます。特に、Itemグラフタイプでネストされたchildrenフィールドを使用すると、Queryが複雑すぎて実行できないなどのエラーが発生することがあります。以下のセクションでは、クエリ複雑さの扱いに関する推奨事項が含まれています。

クエリ複雑性

Experience Edgeは、パフォーマンスと可用性を保護するためにクエリの複雑度制限を強制します。

クエリの複雑度とは、実行にどれだけリソースを消費するかに基づいてGraphQLクエリに割り当てられる数値スコアを指します。このスコアは、過度に複雑なクエリがパフォーマンスを低下させたり、サービス拒否のリスクを生むのを防ぐのに役立ちます。Experience Edgeクエリには複雑さの上限があります。現在、クエリの計算された複雑度スコアを取得する方法はありません。クエリが制限を超えたと分かるのは、Experience Edgeがクエリを却下したときだけです。もしクエリが複雑すぎる場合は、以下の方法を試してみてください。

• クエリを複数の小さなクエリに分割してください。例えば、1つのクエリでデータセットを取得し、その後のクエリをそのデータセットに適用します。複数のオブジェクトに対する大規模なクエリはクエリの複雑さを大幅に増加させます。
• クエリから不要なフィールドを削除してください。

!注Experience Edge(配信)クエリのコストは設定できません。

データ構造の本質的な違いにより、プレビューエンドポイントとデリバリーエンドポイントで複雑度の計算方法が異なります。複雑さ計算ができるだけ一致するようにデフォルト設定を導入しました。しかし、それらを完全に一致させることは不可能です。

プレビューエンドポイントの複雑性制限を引き上げることは、クエリがDeliveryエンドポイントで成功するかどうかを推定する信頼できる方法ではありません。両エンドポイントは複雑さの計算方法が異なり、プレビューを通過したクエリはDeliveryエンドポイントで却下されることがあります。

プレビューエンドポイントのいくつかの設定オプションは、sitecore.configファイルのcomplexityConfigurationオブジェクト内で利用可能です。

非本番環境では、クエリ開発中の拒否を減らすためにプレビューエンドポイントの複雑さ制限を上げることができます。しかし、複雑度はDeliverエンドポイントで異なる計算方法であるため、プレビューエンドポイントで成功したクエリはDeliveryエンドポイントで却下されることがあります。上記のようにクエリを反復的に簡略化することが推奨されるアプローチです。

コンテンツ検索用の利用可能なフィールド

Experience Edgeでは、以下の表に記載された特殊フィールドに対してGraphQL searchクエリを使用できます。テンプレートをクエリする際は、ユーザー定義のフィールドと以下の特殊フィールドのみを照会できます。例えば、サンプルアイテムテンプレートのユーザー定義titleフィールドをクエリすることはできますが、_Sortorderはできません。

フィールド

概要

_templates

すべてのテンプレートGUIDを含み、基本テンプレートも含まれます。階層内でテンプレートを使用しているすべてのアイテムを見つけるために使えます。

_path

親項目を含み、GUIDによってアイテムの子孫を取得するために使用できます。例えば、 contains 節と /home パスのIDを用いると、結果には /home とその子(例: /home/about_us)が含まれます。

_parent

そのアイテムの直系親のIDです。

_name

アイテム名。

_language

アイテムの言語。

_hasLayout

アイテムにプレゼンテーションの詳細やレイアウトデータがあるかどうかを示します。

_latestversion

アイテムの最新バージョンのみを表示するかどうかを判定するブール値です。

!注 _latestversionフィールドはプレビュースキーマとデリバリースキーマで異なる処理が行われます。Delivery APIへのクエリで _latestversionをtrueに設定すると、最新の公開可能なバージョンが返されます。 _latestversionの値はデリバリー APIへの通話時にのみtrueに設定されます。 falseに設定されている場合はエラーを返します。プレビュー APIへのクエリで _latestversionをtrueに設定すると、最新の利用可能なバージョンが返されます。 falseに設定されている場合、すべてのバージョンのアイテムを返します。

メディアとの仕事

Experience Edgeで画像のリサイズや変換は直接可能です。画像操作には以下のオプションがサポートされています:

クエリパラメータ

概要

w

画像の幅。

h

画像の高さ。

mw

画像の最大幅。

mh

画像の最大高さ。

f

画像ファイル形式。以下の数値がサポートされています:

• avif - 可能であれば avif 形式で画像を生成する。できなければ webpにフォールバック。
• webp - Google Webp形式で画像を生成すること。
• jpeg - インターレースプログレッシブJPEG形式の画像生成。この形式では、データを複数回の段階的に圧縮し、徐々に詳細が増します。
• baseline-jpeg - ベースラインの連続JPEG形式で画像を生成すること。ターゲットデバイスがプログレッシブJPEGやその他の最新のファイル形式をサポートしていない場合に使う。
• json - 画像を生成する代わりに、画像に関する情報をJSON形式で出力します。JSONオブジェクトには、画像サイズ(リサイズ前後)、ソース画像のMIMEタイプ、ファイルサイズなどのデータが含まれています。