Sitecoreオーサリングと管理GraphQL API

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

Version:

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

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

オーサリング操作は、次のGraphQLタイプのクエリとミューテーションを使用して実行できます。

アイテム
メディア
Search
敷地
テンプレート

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

Search criteria (検索条件)

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

正確

検索条件は、クエリ用語と完全に一致します。たとえば、「apple」を検索すると、クエリは正確な値が「apple」である結果のみを返します。

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

スタート

指定した検索条件で始まるフィールド値を返します。たとえば、「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

値内のフルテキストフレーズを検索します。たとえば、「アップルパイ」を検索すると、値が「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の間の値) を使用して、検索語にどの程度一致する必要があるかを判断します。値が大きいほど、一致が厳密になります。たとえば、類似性パラメータが0.8の "example" を検索すると、"exampel" と "exmple" に一致する可能性があります。

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

間近

検索語が他の単語で区切られている可能性があるドキュメントを検索するために使用されます。区切りとなる単語の数はparametersで指定されます。たとえば、近接パラメータが5で "apple pie" を検索すると、"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またはパスを指定できます。両方を指定すると、pathパラメータは無視されます。要求入力でpermanentlyパラメーター値をtrueに設定することで、完全な削除を要求できます。

クエリ

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

結果

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

テンプレートアイテムの作成

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"
    }
  }
}

メモ

署名済みのアップロードURLのクエリでエラーが返され、The specified key is not a valid size for this algorithmというメッセージが表示された場合は、GraphQL.UploadMediaOptions.EncryptionKey設定に値があるかどうかを確認します。例えば：

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

そうでない場合は、設定する必要があります。

応答から署名済みのアップロードURLを取得したら、POSTリクエストを送信してメディアファイルをSitecoreにアップロードできます。

たとえば、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クエリを使用して、すべてのアイテムを検索できます。示されている例に加えて、クエリでは、_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"
          }
        }
      ]
    }
  }
}

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