Sitecore著作および管理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 } } }

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

itemクエリを使ってアイテムを取得することができます。このクエリは、サポートされている識別子引数(例

)に基づいて単一のアイテムを取得します。

クエリ

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

} } } } }

アイテムをコピーする

copyItem突然変異を使って既存のアイテムのコピーを作成できます。

クエリ

mutation { copyItem( input: { itemId: "{SOURCE_ITEM_ID}" targetParentId: "{TARGET_PARENT_ITEM_ID}" copyItemName: "Copied Sample Item" } ) { item { itemId name path parent { itemId path } } } }

結果

{ "data": { "copyItem": { "item": { "itemId": "ad15387ecce14faabf27866ec06fe045", "name": "Copied Sample Item", "path": "/sitecore/content/Home/Copied Sample Item", "parent": { "itemId": "110d559fdea542ea9c1c8a5df7e70ef9", "path": "/sitecore/content/Home" } } } }, "extensions": {} }

テンプレート

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

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 absolute 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のクエリで「 指定されたキーはこのアルゴリズムの有効なサイズでない」というメッセージが返された場合、GraphQL.UploadMediaOptions.EncryptionKey設定に値があるか確認してください。例えば:

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

レスポンスから事前署名済みのアップロード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

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

Example text content on the page

" }

} }

} } }, "extensions": {} }

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