今回は、実案件の Sitecore XM Cloud で実際に使用した GraphQL クエリを題材に、XM Cloud における GraphQL の使い方を紹介します。
本記事の後半では、Authoring and Management API を利用したコンテンツの作成・更新・取得・削除といった操作を中心に解説します。
GraphQLについて
GraphQL は、API のために作られたされたクエリ言語です。
クライアントが必要なデータ構造を明示的に指定できる点が特徴で、REST API と比較して柔軟かつ効率的なデータ取得が可能です。（1）
Sitecore XM Cloudで使用したAPI
Sitecore XM Cloud は、フロントエンドとバックエンドを分離したヘッドレスアーキテクチャ（2）を採用しています。
この構成において、フロントエンドと XM Cloud を接続する手段としてGraphQL API が提供されています。
XM Cloud では、用途に応じて以下の GraphQL API を使い分けます。
Authoring and Management API
- コンテンツの取得だけでなく、作成・更新・削除が可能です。
- 管理画面を拡張するカスタム UI やツールの実装に利用されます。
Experience Edge for XM APIs
- 公開済みコンテンツの取得に特化した Read-only APIを使用しています。
- 本番サイトのフロントエンドから利用されることが多いです。
Sitecore XM CloudでGraphQLを使うメリット
XM Cloudのコンテンツ配信層である Experience Edge（3） は、ヘッドレス配信を前提とした GraphQL ベースの参照専用（Read-only）API として構築されています。
Experience Edgeによる高速・安定した配信
Experience Edge は、ヘッドレス配信を前提としたGraphQL ベースの参照専用 API です。
- 公開コンテンツは CDN にキャッシュされ、高速に配信されます。
- 高負荷アクセスを想定した設計のため、安定したパフォーマンスを維持できます。
最適化されたデータ取得
GraphQL では、取得したいフィールドを明示的に指定できます。
- 不要なフィールドを取得しないため、通信量を削減できます。
- 複雑なページ構成でも、1 回のリクエストで必要なデータを取得できます。
開発者体験の向上
- GraphQL Playground（4）を使って、ブラウザ上でクエリを試行できます。
- ローカル・検証・本番で共通のスキーマを利用でき、環境差分による問題を防ぎやすくなります。
一貫したAPI設計
配信系・管理系の両方で GraphQL を採用しており、実装や保守の一貫性が高まります。
サンプル紹介
今回は、Authoring and Management APIの新規作成、更新、削除、取得のコードのサンプルコードを紹介したいと思います。
新規作成クエリ
以下のように作成するアイテム名、使用するテンプレートID、作成対象となる親アイテムのID、作成言語し、各フィールドの値を指定します。
# カスタムフィールドすべてに値を入れてアイテムを作成するクエリ
mutation {
createItem(
input: {
# 作成するアイテム名、使用するテンプレートID、作成対象となる親アイテムのID、作成言語
name: "TestCreate"
templateId: "{76036F5E-CBCE-46D1-AF0A-4143F9B557AA}"
parent: "{CEA1631E-5FBC-4F0A-8655-ABE9F1D5EA4D}"
language: "en"
# 各フィールドの値
fields: [
{ name: "Title", value: "TitleTestCreate" }
{ name: "Checkbox", value: "1" }
{ name: "Date", value: "20250715T000000Z" }
{ name: "Datetime", value: "20250714T013000Z" }
{ name: "Multi-Line", value: "testMulti" }
{ name: "Rich", value: "teastRich" }
{ name: "Single-Line", value: "testSingle" }
{
name: "CheckList"
value: "{D1D16DB6-5BB3-4C80-86DD-29CAD071ACAE}|{34AC799A-75C6-442D-BF90-8F3202D70551}"
}
{ name: "Droplist", value: "ID View" }
{
name: "Grouped Droplink"
value: "{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}"
}
{ name: "Grouped Droplist", value: "Home" }
{
name: "Treelist"
value: "{9811DC81-9410-4251-B66D-C5340867DAED}"
}
{
name: "Droplink"
value: "{D1D16DB6-5BB3-4C80-86DD-29CAD071ACAE}"
}
{
name: "Droptree"
value: "{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}"
}
{
name: "General Link"
value: ""
}
{ name: "Datasource", value: "/sitecore/layout/Renderings" }
{ name: "Number", value: "1" }
{ name: "Integer", value: "6" }
]
}
) {
# 戻り値
item {
itemId
name
path
# Standard Fields を除外
fields(excludeStandardFields: true) {
nodes {
name
value
}
}
}
}
}
更新クエリ
以下のように更新するアイテムのパスを指定し、更新するフィールドと値 の指定をします。
# カスタムフィールドを一括更新するクエリ
mutation {
updateItem(
# 更新するアイテムパス、更新するフィールドと値
input: {
path: "/sitecore/content/Home/Test/tes5"
fields: [
{
name: "Checkbox"
value: "1"
}
{
name: "Date"
value: "20250715T000000Z"
}
{
name: "Datetime"
value: "20250714T013000Z"
}
{
name: "Multi-Line"
value: "testMulti"
}
{
name: "Rich"
value: "teastRich"
}
{
name: "Single-Line"
value: "testSingle"
}
{
name: "CheckList"
value: "{D1D16DB6-5BB3-4C80-86DD-29CAD071ACAE}|{34AC799A-75C6-442D-BF90-8F3202D70551}"
}
{
name: "Droplist"
value: "ID View"
}
{
name: "Grouped Droplink"
value: "{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}"
}
{
name: "Grouped Droplist"
value: "Home"
}
{
name: "Treelist"
value: "{9811DC81-9410-4251-B66D-C5340867DAED}"
}
{
name: "Droplink"
value: "{D1D16DB6-5BB3-4C80-86DD-29CAD071ACAE}"
}
{
name: "Droptree"
value: "{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}"
}
{
name: "Datasource"
value: "/sitecore/layout/Renderings"
}
{
name: "Number"
value: "2"
}
{
name: "Integer"
value: "3"
}
]
}
) {
item {
# 戻り値
name
path
# Standard Fields を除外
fields(excludeStandardFields: true) {
nodes {
name
value
}
}
}
}
}
検索クエリ
以下のように検索対象のフィールド値を指定し、検索条件の指定を行います。
# 特定のパス配下に存在し、かつアイテム名が指定された値のものを検索
query {
search(
query: {
searchStatement: {
operator: MUST
# MUST [ SHOULD, SHOULD ] でいずれか必須(Or)
criteria: [
# api key
{ operator: SHOULD, criteriaType: SEARCH, field: "_path", value: "59b41b5fe22e460b941efb64fe8da8fc" },
# rendering hosts
{ operator: SHOULD, criteriaType: SEARCH, field: "_path", value: "895e25c412b24b2c823382f3b79eef53" },
]
# MUST { MUST } でどちらも必須(And)
subStatements: {
operator: MUST
# MUST [ SHOULD, SHOULD ] { MUST [ SHOULD, SHOULD ] } なので
# _path がいずれかを含む、かつ _name がいずれかに一致
criteria: [
{ operator: SHOULD, criteriaType: EXACT, field: "_name", value: "Default" },
{ operator: SHOULD, criteriaType: EXACT, field: "_name", value: "Rendering Hosts" },
]
}
}
}
) {
# 戻り値
totalCount
results {
path
name
}
}
}
削除クエリ
以下のように、削除対象のアイテムパスを指定します。
mutation{
deleteItem(
input:{
path: "/sitecore/content/Home/Test/TestCreate"
}
){
successful
}
}
本記事では、Sitecore XM Cloud で使用されるGraphQLと Authoring and Management API を利用したGraphQL クエリの実例を紹介しました。
本記事が、XM Cloud で GraphQL を利用する際の参考になれば幸いです。
最後まで読んでいただき、ありがとうございました。
参考文献
(1)GraphQLについて
(2)ヘッドレスについて
(3)Experience Edgeについて
(4)公式の GraphQL Playground 使い方
※エントリーの内容・画像等は、公開時点での情報に基づきます。
※Sitecoreのバージョンによって実装されている機能が異なります。