--- title: "Experience Edgeスキーマ" slug: "the-experience-edge-schema" abstract: "エントリポイント、エンドポイント、テンプレート定義を記述します。" --- # Experience Edgeスキーマ Sitecore Experience EdgeはヘッドレスSitecore開発の一般的なフロントエンドユースケースに対応するために設計された読み取り専用のGraphQLスキーマを持っています。Sitecoreの製品に関する限定的な情報しか公開していません。例えば、標準フィールドは存在しません。 ## 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](https://doc.sitecore.com/sai/ja/developers/sitecoreai/experience-edge/experience-edge-apis/set-up-the-graphql-ides.html "Set up the GraphQL IDEs") **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オブジェクト内で利用可能です。 15 10000 2 非本番環境では、クエリ開発中の拒否を減らすためにプレビューエンドポイントの複雑さ制限を上げることができます。しかし、複雑度は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に設定されている場合、すべてのバージョンのアイテムを返します。 ### Search演算子の挙動 Searchオペレーターの挙動は、Previewエンドポイント( [トークン化された検索インデックス](https://doc.sitecore.com/sai/ja/developers/sitecoreai/experience-edge/experience-edge-apis/preview-graphql-api.html "Preview GraphQL API")を使用する)かDeliveryエンドポイントかによって異なります。 > !注GraphQLの検索フィールドは、全文検索やサイト検索機能の実装ではなく、コンテンツのフィルタリング用に設計されています。より高度な検索機能を求めるなら、専用の検索サービスを利用することを検討してください。 searchクエリは以下の演算子をサポートしています: - CONTAINS - フィールド内で部分文字列のマッチを行う。このオペレーターは部分的なテキストマッチや、フィールド内の単語やフレーズに基づくコンテンツのフィルタリングに使います。 - *Preview* -CONTAINS演算子はトークン化されたフィールド値に基づいて複数の結果を返すことができます。これはプレビューエンドポイントがトークン化された検索インデックスを使用しているためです。 - *Delivery* - トークン化やランキングなしで、そのまま価値をマッチングすること。 例えば、CONTAINS演算子で*ipsum*を検索すると、テキスト内のどこかに値が現れる任意のフィールド(*例えばlorem ipsum dolor sit amet*)と一致します。 - NCONTAINS (含まれません) - 指定された部分文字列をフィールド値に含まない項目とマッチングします。これはCONTAINSの逆です。 - EQ (等しい) - 値が完全に一致するユーザー定義フィールドのみにマッチします。正確な全フィールドマッチングが必要な場合はこの演算子を使いましょうが、プレビューエンドポイントでのトークン化動作には注意してください。 - *Preview* - Solr検索インデックスのすべてのテキストフィールドがデフォルトでトークン化されているため、テキストフィールドのCONTAINS演算子として機能します。つまり、完全に一致すると予想されていても複数の結果が返されることがあります。 例えば、EQ演算子で*ipsum*を検索すると、*lorem ipsum dolor sit amet*を含むフィールドの結果が返ってくることがあります。 プレビューエンドポイントのEQと正確に一致させるために、SearchQueryFieldMapping機能を使ってトークン化されたフィールドを非トークン化された計算フィールドにマッピングします。関連するサポート記事も参照[KB1003665](https://support.sitecore.com/kb?id=kb_article_view&sysparm_article=KB1003665)。 - *Delivery* - この演算子は、値が完全に一致するユーザー定義フィールドのみにマッチします。フィールド全体が検索値と完全に一致しなければならず、部分的な一致は返されません。 例えば、EQ演算子で*ipsum*を検索しても*、lorem ipsum dolor sit amet*を含むフィールドにはマッチしませんが、ipsumの値が正確に*ipsum*であるフィールドにはマッチします。 - NEQ (等しくない) - フィールド値が指定された値と一致しない項目をマッチングします。これはEQの逆です。 検索 [およびフィルタリングクエリの例](https://doc.sitecore.com/sai/ja/developers/sitecoreai/experience-edge/experience-edge-apis/query-examples-for-the-delivery-graphql-api.html "Query examples for the Delivery GraphQL API")も参照してください。 以下の演算子は数値または日付フィールドの値を比較し、範囲のクエリに利用できます: - GT (大きい) - フィールド値が指定された値より大きい項目にマッチします。 - GTE (大きいまたは等しい) - フィールド値が指定された値より大きい項目にマッチする。 - LT (Below) - フィールド値が指定された値より小さい項目とマッチします。 - LTE (小さいまたは等しい) - フィールド値が指定された値以下である項目とマッチする。 また、[レンジ演算子クエリの例](https://doc.sitecore.com/sai/ja/developers/sitecoreai/experience-edge/experience-edge-apis/query-examples-for-the-delivery-graphql-api.html "Query examples for the Delivery GraphQL API")も参照してください。 ## メディアとの仕事 Experience Edgeで画像のリサイズや変換は直接可能です。画像操作には以下のオプションがサポートされています: クエリパラメータ 概要 w 画像の幅。 h 画像の高さ。 mw 画像の最大幅。 mh 画像の最大高さ。 f 画像ファイル形式。以下の数値がサポートされています: - avif - 可能であれば avif 形式で画像を生成する。できなければ webpにフォールバック。 - webp - Google Webp形式で画像を生成すること。 - jpeg - インターレースプログレッシブJPEG形式の画像生成。この形式では、データを複数回の段階的に圧縮し、徐々に詳細が増します。 - baseline-jpeg - ベースラインの連続JPEG形式で画像を生成すること。ターゲットデバイスがプログレッシブJPEGやその他の最新のファイル形式をサポートしていない場合に使う。 - json - 画像を生成する代わりに、画像に関する情報をJSON形式で出力します。JSONオブジェクトには、画像サイズ(リサイズ前後)、ソース画像のMIMEタイプ、ファイルサイズなどのデータが含まれています。