Sitecore Authoringと経営GraphQL API

オーサリング操作のクエリ例

日本語翻訳に関する免責事項

このページの翻訳はAIによって自動的に行われました。可能な限り正確な翻訳を心掛けていますが、原文と異なる表現や解釈が含まれる場合があります。正確で公式な情報については、必ず英語の原文をご参照ください。

以下のGraphQLタイプに対してクエリやミューテーションを用いてオーサリング操作を行うことができます:

アイテム
メディア
Search
遺跡
テンプレート

利用可能な種類や操作の完全なリストについては、GraphQL IDEの組み込みドキュメントを参照してください。

Search criteria

以下のセクションでは、クエリに適用できる検索条件について説明します。

正確

検索基準はクエリ語と完全に一致するものです。例えば、「apple」と検索すると、正確な値が「apple」である結果しか返ってきません。

{
    "model": {
        "index": "sitecore_master_index",
        "searchStatement": {
            "criteria": [
                {
                    "field": "_group",
                    "value": "227473f1dc3f4d3a8558865f49b4f64f",
                    "criteriaType": "EXACT"
                }
            ]
        }
    }
}

StartsWith

指定された検索基準で始まるフィールド値を返します。例えば、「app」と検索すると「apple」と「application」の両方が表示されます。

{
    "model": {
        "index": "sitecore_master_index",
        "searchStatement": {
            "criteria": [
                {
                    "field": "_group",
                    "value": "227473f1dc3f4d3a8558",
                    "criteriaType": "STARTSWITH"
                }
            ]
        }
    }
}

包含

指定された検索基準を含むフィールド値を返します。例えば、「app」と検索すると「apple」「application」「happen」が返ってきます。

{
    "model": {
        "index": "sitecore_master_index",
        "searchStatement": {
            "criteria": [
                {
                    "field": "_group",
                    "value": "c3f4d3a8558",
                    "criteriaType": "CONTAINS"
                }
            ]
        }
    }
}

終わり

指定された検索基準で終わるフィールド値を返します。例えば、「ple」で検索すると「apple」と「maple」の両方が表示されます。

{
    "model": {
        "index": "sitecore_master_index",
        "searchStatement": {
            "criteria": [
                {
                    "field": "_group",
                    "value": "65f49b4f64f",
                    "criteriaType": "ENDSWITH"
                }
            ]
        }
    }
}

ワイルドカード

検索基準にワイルドカードが含まれています。例えば、「a*e」で検索すると「apple」と「angle」の両方が表示されます。

{
    "model": {
        "index": "sitecore_master_index",
        "searchStatement": {
            "criteria": [
                {
                    "field": "_group",
                    "value": "227*f64f",
                    "criteriaType": "WILDCARD"
                }
            ]
        }
    }
}

Search

値の中の全文フレーズを検索します。例えば、「apple pie」と検索すると「We made apple pie」という値の項目が返ってきます。

{
    "model": {
        "index": "sitecore_master_index",
        "searchStatement": {
            "criteria": [
                {
                    "field": "_name",
                    "value": "Unlock",
                    "criteriaType": "SEARCH"
                }
            ]
        }
    }
}

分布域

数値および日付フィールド内の範囲の値を検索します。例えば、1から5の間の任意の値を検索できます。この基準を適用する際には、カッコ内にクエリ範囲を定義する文字列valueも入力します。 valueに入る際、以下の点に注意してください:

括弧の種類によって、範囲が包括的か排他的かが決まります。四角括弧は包括的な範囲を示し、丸括弧は排他的範囲を示します。例えば、1つのクエリで括弧タイプを混ぜることができます。例えば、値が10 TO 20)なら10は含め、20は除外します。
文字列TOで最小値と最も高い値を分けます(大文字を区別)。
アスタリスク*は制限のない値(上限も制限もない)を示します。例えば、値が (10 TO *)の場合、10は除外され、上限はありません。

{
    "model": {
        "index": "sitecore_master_index",
        "searchStatement": {
            "criteria": [
                {
                    "field": "__boost",
                    "value": "[1 TO 5]",
                    "criteriaType": "RANGE"
                }
            ]
        }
    }
}

ファジー

検索語に似たマッチを見つけるために使われ、誤字や綴りの違いなどの細かな違いを許容します。類似度parameters (0と1の間の値)を用いて、検索語にどれだけ近いかを判断します。値が高いほど、より厳密なマッチングを意味します。例えば、「example」を類似パラメータ0.8で検索すると、「exampel」や「exmple」と一致することがあります。

{
    "model": {
        "index": "sitecore_master_index",
        "searchStatement": {
            "criteria": [
                {
                    "field": "_name",
                    "value": "secuty",
                    "criteriaType": "FUZZY",
                    "parameters": "0.5"
                }
            ]
        }
    }
}

近接性

検索語が他の単語で区切られている可能性のある文書を見つけるために使われました。分離する単語の数はparametersで表されます。例えば、「apple pie」を近接パラメータ5で検索すると「apple is not a pie」が返ってきます。

{
    "model": {
        "index": "sitecore_master_index",
        "searchStatement": {
            "criteria": [
                {
                    "field": "_name",
                    "value": "collection",
                    "criteriaType": "PROXIMITY",
                    "parameters": "0"
                }
            ]
        }
    }
}

正則表現

正則表現(RegEx)を適用する検索語。例えば、「a.*e$」で検索すると「apple」と「angle」が返ってきます。

{
    "model": {
        "index": "sitecore_master_index",
        "searchStatement": {
            "criteria": [
                {
                    "field": "_name",
                    "value": "\\w*configuration",
                    "criteriaType": "REGEXP"
                }
            ]
        }
    }
}

クエリの例

以下のセクションでは、オーサリング操作の例となるクエリを紹介します。

アイテム

アイテムを作成する

createItem変異を持つアイテムを作成できます。

クエリ

mutation {
  createItem(
    input: {
      name: "Sitecore Authoring and Management API"
      templateId: "{76036F5E-CBCE-46D1-AF0A-4143F9B557AA}"
      parent: "{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}"
      language: "en"
      fields: [
        { name: "title", value: "Welcome to Sitecore" }
        { name: "text", value: "Welcome to Sitecore" }
      ]
    }
  ) {
    item {
      itemId
      name
      path
      fields(ownFields: true, excludeStandardFields: true) {
        nodes {
          name
          value
        }
      }
    }
  }
}

結果

{
  "data": {
    "createItem": {
      "item": {
        "itemId": "30a8616da7c6411db307d4f2c9684e76",
        "name": "Sitecore Authoring and Management API",
        "path": "/sitecore/content/Home/Sitecore Authoring and Management API",
        "fields": {
          "nodes": [
            {
              "name": "Text",
              "value": "Welcome to Sitecore"
            },
            {
              "name": "Title",
              "value": "Welcome to Sitecore"
            }
          ]
        }
      }
    }
  }
}

アイテムを削除する

deleteItem突然変異を使ってアイテムを削除できます。アイテムIDやパスを指定することができます。両方を指定すると、パスパラメータは無視されます。リクエスト入力でpermanentlyパラメータ値をtrueに設定することで、恒久的な削除を要求できます。

クエリ

mutation {
  deleteItem( input: { 
      path: "/sitecore/content/Home/Sitecore Authoring and Management API"
      permanently: true
    }
  ) {
    successful
  }
}

結果

{
  "data": {
    "deleteItem": {
      "successful": true
    }
  }
}

アイテムを入手しましょう

getItem変異を使ってアイテムを取り戻すことができます。

クエリ

query {
    item(
        where: {
            database: "master",
            itemId: "{A58AAB49-FE07-4GT5-B03F-927C581E74D7}"
    }){
        itemId
        name
        path
        fields(ownFields: true, excludeStandardFields: true) {
            nodes {
                name
                value
            }
        }
    }
}

結果

{
    "data": {
        "item": {
            "itemId": "a58aab49fe074gt5b03f927c581e74d7",
            "name": "Sitecore Authoring and Management API",
            "path": "/sitecore/content/Home/Sitecore Authoring and Management API",
            "fields": {
                "nodes": [
                    {
                        "name": "Text",
                        "value": "Welcome to Sitecore"
                    },
                    {
                        "name": "Title",
                        "value": "Welcome to Sitecore"
                    }
                ]
            }
        }
    }
}

アイテムの更新

updateItemミューテーションを使ってアイテムフィールドを更新できます。

クエリ

mutation {
  updateItem(
    input: {
      fields: [
        { name: "Title", value: "My new page", reset: false }
        { name: "Content", value: "Lorem Ipsum", reset: false }
      ]
      database: "master"
      itemId: "{59C9BA60-6483-451C-A435-B60BED2DBA75}"
      language: "en"
      path: "/sitecore/content/mycollection/mysite/Home/PageTest"
      version: 1
    }
  ) {
    item {
      name
      itemId
      fields(ownFields: true) {
        nodes {
          name
          value
        }
      }
    }
  }
}

結果

{
  "data": {
    "updateItem": {
      "item": {
        "name": "PageTest",
        "itemId": "59c9ba606483451ca435b60bed2dba75",
        "fields": {
          "nodes": [
            {
              "name": "Title",
              "value": "My new page"
            },
            {
              "name": "Content",
              "value": "Lorem Ipsum"
            }
          ]
        }
      }
    }
  }
}

テンプレート

テンプレートアイテムを作成する

createItemTemplateミューテーションを使ってアイテムテンプレートを作成できます。

クエリ

mutation {
  createItemTemplate(
    input: {
      name: "NewTemplate"
      parent: "{B29EE504-861C-492F-95A3-0D890B6FCA09}"
      sections: {
        # Create a new template section if the ID is empty, otherwise update the template section
        name: "newSection"
        fields: [
          # Create a new template field if the ID is empty, otherwise update the template field
          { name: "Field 1", type: "Single-Line Text" }
          { name: "Field 2", type: "Rich Text" }
        ]
      }
    }
  ) {
    itemTemplate {
      name
      ownFields {
        nodes {
          name
          type
        }
      }
    }
  }
}

結果

{
  "data": {
    "createItemTemplate": {
      "itemTemplate": {
        "name": "NewTemplate",
        "ownFields": {
          "nodes": [
            {
              "name": "Field 1",
              "type": "Single-Line Text"
            },
            {
              "name": "Field 2",
              "type": "Rich Text"
            }
          ]
        }
      }
    }
  }
}

テンプレート項目とそのフィールドを更新する

updateItemTemplateミューテーションを使ってアイテムテンプレートを更新できます。

クエリ

mutation {
  updateItemTemplate(
    input: {
      templateId: "{A597BE8E-3DD6-483F-B474-A18AF0560E89}"
      name: "UpdatedTemplate"
      sections: [
        {
          # Create a new template section if the ID is empty, otherwise update the template section
          templateSectionId: "{C8076CA2-FDDE-423C-A819-B6C7573B3FF2}"
          name: "Updated Section 1"
          fields: [
            {
              # Create a new template field if the ID is empty, otherwise update the template field
              fieldId: "{59B88198-5C5B-4E64-A051-3D5ADD003884}"
              name: "Updated Field 1"
            }
            { name: "Create New Field", type: "Single-Line Text" }
          ]
        }
        { name: "Create New Section 2" }
      ]
    }
  ) {
    itemTemplate {
      name
      ownFields {
        nodes {
          name
          type
        }
      }
    }
  }
}

結果

{
  "data": {
    "updateItemTemplate": {
      "itemTemplate": {
        "name": "UpdatedTemplate",
        "ownFields": {
          "nodes": [
            {
              "name": "Updated Field 1",
              "type": "Single-Line Text"
            },
            {
              "name": "Field 2",
              "type": "Rich Text"
            },
            {
              "name": "Create New Field",
              "type": " Single-Line Text "
            }
          ]
        }
      }
    }
  }
}

メディア

メディアのアップロード

uploadMedia変異を使って事前署名されたアップロードURLを得ることができます。事前に署名されたアップロードURLを使ってメディアファイルをSitecoreにアップロードします。

クエリ

mutation
{
  # The itemPath parameter should not include the Sitecore media library obsolete path
  # The media item name should be included in the itemPath
  uploadMedia(input: { itemPath: "Default Website/new media" }) {
    presignedUploadUrl
  }
}

結果

{
  "data": {
    "uploadMedia": {
      "presignedUploadUrl": "https://xmcloudcm.localhost/sitecore/api/v1/authoring/media/upload?token=dFh6hm_yH2DrUppd2v7zAU4kvIHk7CgMsXgg2ieaeQzKCU7v7q_W_L9mBY7wGyPw0"
    }
  }
}

XM Cloudは現在SitecoreAIとなっています

一部のコード例、画像、UIラベルは、エンジニアリング資産の更新中もXM Cloudを使用している場合があります。

注記

事前署名されたアップロードURLのクエリでメッセージThe specified key is not a valid size for this algorithmのエラーが返された場合、GraphQL.UploadMediaOptions.EncryptionKey設定に値があるか確認してください。例えば：

<setting name="GraphQL.UploadMediaOptions.EncryptionKey" value="432A462D4A614E64" />

もし合わなければ、設定しなければなりません。

レスポンスから事前署名済みのアップロードURLを取得したら、メディアファイルをSitecoreにアップロードするためのPOSTリクエストを送ることができます。

例えば、curlクライアントを使うと:

curl --request POST "https://<your_server>/sitecore/api/v1/authoring/media/upload?token=dFh6hm_yH2DrUppd2v7zAU4kvIHk7CgMsXgg2ieaeQzKCU7v7q_W_L9mBY7wGyPw0" 
--header "Authorization: Bearer <JWT_TOKEN>" --form =@<path_to_your_file>

リクエストへの応答は、メディアアイテムのID、名前、そして成功したメディアアップロード時のフルパスを含むJSON形式の応答です。

遺跡

設定されたサイトを入手してください

特定のサイトについて、そのサイトの名前で情報を検索することができます。

クエリ

query {
  site(siteName: "website") {
    name
    domain
    rootPath
    startPath
    browserTitle
    cacheHtml
    cacheMedia
    enablePreview
  }
}

結果

{
"data": {   
  "site": {     
    "name": "website",     
    "domain": "extranet",    
    "rootPath": "/sitecore/content",     
    "startPath": "/home",     
    "browserTitle": "Website - Sitecore",     
    "cacheHtml": true,     
    "cacheMedia": true,     
    "enablePreview": true   
    }
  }
}

Search

特定の経路でアイテムをSearch

searchクエリを使ってすべてのアイテムを検索できます。示した例に加えて、クエリには_name、_template、_templatenameなどのシステムフィールドを利用できます。

クエリ

query {
  search(
    query: {
      index: "sitecore_master_index"
      searchStatement: {
        criteria: [
          { criteriaType: SEARCH, field: "Title", value: "sample item" }
          {
            operator: MUST
            field: "_path"
            value: "110d559fdea542ea9c1c8a5df7e70ef9"
          }
        ]
      }
    }
  )
 {
    results {
      innerItem {
        path
        field(name: "Title") {
          value
        }
      }
    }
  }
}

結果

{  "data": {
    "search": {
      "results": [
        {
          "innerItem": {
            "path": "/sitecore/content/Home/Sample Item1",
            "field": {
              "value": "Sample Item1"
            }
          }
        },
        {
          "innerItem": {
            "path": "/sitecore/content/Home/Sample Item2",
            "field": {
              "value": "Sample Item2"
            }
          }
        }
      ]
    }
  }
}

検索結果を作成日順に並べ替え

検索結果はフィールド値でソートできます。

クエリ

query {
  search(
    query: {
      index: "sitecore_master_index"
      sort: { field: "__smallcreateddate", direction: DESCENDING }
      searchStatement: {
        criteria: [
          {
            operator: MUST
            field: "_template"
            value: "76036f5ecbce46d1af0a4143f9b557aa" # Sample Item template ID
          }
        ]
      }
    }
  ) {
    results {
      innerItem {
        name
        path
        field(name: "__Created") {
          value
        }
      }
    }
  }
}

結果

{
  "data": {
    "search": {
      "results": [
        {
          "innerItem": {
            "name": "NewestItem",
            "path": "/sitecore/content/Home/NewestItem",
            "field": {
              "value": "20241114T120709Z"
            }
          }
        },
        {
          "innerItem": {
            "name": "OldItem",
            "path": "/sitecore/content/Home/OldItem",
            "field": {
              "value": "20230512T110132Z"
            }
          }
        }
      ]
    }
  }
}

ページングを使って検索結果を設定する

デフォルトでは、クエリは最初の10個の検索結果を返します。クエリにページングパラメータを追加することでこれを変えることができます。

そのためには、以下のパラメータを使用します。

pageSize - ページあたりの結果数。
skip - スキップすべき結果の数。
pageIndex - 検索結果ページのインデックス名を返す。

クエリ

query {
  search(
    query: {
      index: "sitecore_master_index"
      paging: { pageSize: 3, skip: 0, pageIndex: 0 }
      searchStatement: {
        criteria: [
          {
            operator: MUST
            field: "_template"
            value: "76036f5ecbce46d1af0a4143f9b557aa" # Sample Item template ID
          }
        ]
      }
    }
  ) {
    results {
      innerItem {
        name
        path
      }
    }
  }
}

結果

{
  "data": {
    "search": {
      "results": [
        {
          "innerItem": {
            "name": "One",
            "path": "/sitecore/content/Home/One"
          }
        },
        {
          "innerItem": {
            "name": "Two",
            "path": "/sitecore/content/Home/Two"
          }
        },
        {
          "innerItem": {
            "name": "Three",
            "path": "/sitecore/content/Home/Three"
          }
        }
      ]
    }
  }
}

検証

アイテムテンプレートの検証結果を取得する

フィールドテンプレート内のフィールドの検証エラーの可能性については、validation項目をクエリすることで詳細を得られます。

クエリ

query fieldValidation {
  item(where: { itemId: "{F704D058-D53C-490A-8803-37249B4F4031}" }) {
    field(name: "Title") {
      value
      validation {
        mode
        results {
          nodes {
            message
            result
            valid
            validator
          }
        }
      }
    }
  }
}

結果

{
  "data": {
    "item": {
      "field": {
        "value": "Page",
        "validation": [
          {
            "mode": "FieldRegexValidation",
            "results": {
              "nodes": [
                {
                  "message": "Only numbers are allowed!",
                  "result": "Error",
                  "valid": false,
                  "validator": "Field RegEx validator"
                }
              ]
            }
          }
        ]
      }
    }
  },
  "extensions": {}
}

複数クエリの例

このセクションでは、コンテンツ管理のための一連のオーサリング操作について説明します。

すべてのページのコンテンツを入手できます

ページの全内容を取得するには、以下の3つのクエリを行えます。これは、ページからテキスト内容や最後に編集した日付、最後に編集したユーザーなどの詳細を取得するカスタムソリューション、例えばSitecore Marketplaceアプリのようなカスタムソリューションを構築する場合に役立ちます。

クエリ

まず、利用したいサイトの経路をsitesに問い合わせることができます:

query GetSites {
  sites {
    name
    rootPath # Get site path
    rootItem {
      itemId
    }
  }
}

結果

{
  "data": {
    "sites": [
      {
        "name": "<SITE_NAME>",
        "rootPath": "<SITE_PATH>",
        "rootItem": {
          "itemId": "<SITE_ID>"
        }
      }
    ]
  },
  "extensions": {}
}

クエリ

次に、サイトパスを使ってすべてのサイトページ、ページIDやパスを検索・取得できます。

query GetSitePages {
  search(
    query: {
      index: "sitecore_master_index"
      searchStatement: {
        criteria: [
          {
            criteriaType: STARTSWITH
            field: "_fullpath"
            value: "<SITE_PATH>" # Replace with your site path
          }
          { operator: MUST, field: "_templatename", value: "Page" }
        ]
      }
      paging: { pageSize: 100, pageIndex: 0 }
    }
  ) {
    totalCount
    results {
      innerItem {
        itemId # Get the page ID
        name
        path # Get the page path
      }
    }
  }
}

結果

{
  "data": {
    "search": {
      "totalCount": 127,
      "results": [
        {
          "innerItem": {
            "itemId": "<PAGE_ID>",
            "name": "<PAGE_NAME>",
            "path": "<PAGE_PATH>"
          }
        }
      ]
    }
  },
  "extensions": {}
}

クエリ

最後に、ページIDとパスを使ってページの内容(データソースを含む)を取得することができます。

query GetPageContents {
  # Replace itemId with your page ID
  page: item(where: { itemId: "<PAGE_ID>" }) {
    itemId
    name
    path

    fields(ownFields: true, excludeStandardFields: true) {
      nodes {
        name
        value
      }
    }
  }

  # Query the Data folder directly using the page path + /Data
  dataFolder: item(
    where: {
      path: "<PAGE_PATH>/Data" # Replace with your page path
    }
  ) {
    itemId
    name
    path
    template {
      name
    }

    # Get all data source items under the Data folder (Text 1, Text 2, etc.)
    dataSources: children {
      nodes {
        itemId
        name
        path
        createdField: field(name: "__Created") {
          value
        }
        modifiedField: field(name: "__Updated") {
          value
        }
        createdByField: field(name: "__Created by") {
          value
        }
        updatedByField: field(name: "__Updated by") {
          value
        }
        template {
          name
        }

        # Get all fields from data source items
        fields(ownFields: true, excludeStandardFields: true) {
          nodes {
            fieldId
            name
            value
          }
        }
      }
    }
  }
}

結果

{
  "data": {
    "page": {
      "itemId": "<PAGE_ID>",
      "name": "<PAGE_NAME>",
      "path": "<PAGE_PATH>",
      "fields": {
        "nodes": [
          {
            "name": "Title",
            "value": "<PAGE_TITLE>"
          }
        ]
      }
    },
    "dataFolder": {
      "itemId": "<DATA_ITEM_ID>",
      "name": "Data",
      "path": "<DATA_PATH_ID>",
      "template": {
        "name": "Page Data"
      },
      "dataSources": {
        "nodes": [
          {
            "itemId": "<DATASOURCE_ID>",
            "name": "<DATASOURCE_NAME>",
            "path": "<DATASOURCE_PATH>",
            "createdField": {
              "value": "<DATASOURCE_CREATED_DATETIME>"
            },
            "modifiedField": {
              "value": "<DATASOURCE_MODIFIED_DATETIME>"
            },
            "createdByField": {
              "value": "<CREATED_BY_USER>"
            },
            "updatedByField": {
              "value": "<UPDATED_BY_USER>"
            },
            "template": {
              "name": "Text"
            },
            "fields": {
              "nodes": [
                {
                  "fieldId": "<FIELD_ID>",
                  "name": "Text",
                  "value": "<div class=\"ck-content\"><p>Example text content on the page</p></div>"
                }
              ]
            }
          }
        ]
      }
    }
  },
  "extensions": {}
}

この記事を改善するための提案がある場合は、お知らせください!