GraphQL コンテンツ スキーマ
このページの翻訳はAIによって自動的に行われました。可能な限り正確な翻訳を心掛けていますが、原文と異なる表現や解釈が含まれる場合があります。正確で公式な情報については、必ず英語の原文をご参照ください。
Sitecore GraphQL には、Sitecore コンテンツ アイテムのクエリに使用する標準スキーマ プロバイダーがあります。このプロバイダーには、厳密に型指定されたテンプレート アクセス、フィールド型のメタデータのサポート、コンテンツ データなどを必要とするほとんどの Sitecore フロントエンド プロジェクトの理想的なアクセス レイヤーとなるその他の機能があります。
厳密に型指定されたアイテム
GraphQL は型とインターフェイスをサポートしており、テンプレート定義をスキーマに挿入することでそれらを使用します。特定の型からフィールドを選択するインライン フラグメントを使用して、厳密に型指定する方法でテンプレート フィールドを取得できます。以下の例は、既定のホーム アイテムのフィールドをこの方法で取得しています。
{
item(path: "/sitecore/content/home") {
id
...on SampleItem {
text {
editable
}
title {
editable
}
}
}
}
このクエリは、以下と同様のものを返します。
{
"data": {
"item": {
"id": "{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}",
"text": {
"editable": "<p style=\"line-height: 22px;\">From a single connected platform that also integrates with other customer-facing platforms, to a single view of the customer in a big data marketing repository, to completely eliminating much of the complexity that has previously held marketers back, the latest version of Sitecore makes customer experience highly achievable. Learn how the latest version of Sitecore gives marketers the complete data, integrated tools, and automation capabilities to engage customers throughout an iterative lifecycle – the technology foundation absolutely necessary to win customers for life.</p>\n<p>For further information, please go to the <a rel=\"noopener noreferrer\" href=\"https://doc.sitecore.net/\" target=\"_blank\" title=\"Sitecore Documentation site\">Sitecore Documentation site</a></p>"
},
"title": {
"editable": "Sitecore Experience Platform"
}
}
}
}
GraphQL の型システムは、テンプレートの継承をサポートします。以下の例は、アイテムの Insert Options
がポイントするアイテムを取得する方法を示しています。
{
item(path: "/sitecore/content/home") {
# Treat the home item as the system 'Insert Options' template type, and this works
...on InsertOptions {
masters {
targetItems {
displayName
uri
}
}
}
}
}
型指定されたフィールドへのアクセス
Sitecore GraphQL は、リンク フィールドやマルチリストなどのフィールド値への型指定されたアクセスをサポートします。
以下はパスによるアイテムのクエリの例で、拡張サンプル アイテム テンプレート上で実行します。
{
item(path: "/sitecore/content/home") {
__typename
# Sample multilist and link (additional fields also available)
...on SampleItem {
myMultilist {
targetItems {
id
path
...on Home {
navigationTitle {
editable
}
}
}
}
myLinkField {
url
text
editable
}
}
# Typing in named-field API
myLinkFieldByName: field(name: "My Link Field") {
name
editable
...on LinkField {
url
text
}
}
}
}
上の例で定義したクエリに対して、Sitecore GraphQL は次のようなデータ構造を返します。
{
"data": {
"item": {
"__typename": "SampleItem",
"myMultilist": {
"targetItems": [
{
"id": "{C7C95984-E060-42D9-BBC6-B45C18768905}",
"path": "/sitecore/content/Habitat/Settings"
},
{
"id":
"{DAC24EDD-44FB-42EF-9ECD-1E8DAF706386}",
"path": "/sitecore/content/Habitat/Home",
"navigationTitle": {
"editable": "Navigation Title"
}
}
]
},
"myLinkField": {
"url": "https://sitecore.net",
"text": "Awesome Link",
"editable": "<a
href=\"https://sitecore.net\">Awesome Link</a>"
},
"myLinkFieldByName": {
"name": "My Link Field",
"editable": "<a href=\"https://sitecore.net\">Awesome
Link</a>",
"url": "https://sitecore.net",
"text": "Awesome Link"
}
}
}
}
テンプレートへのアクセス
API を使用して、Sitecore テンプレートにアクセスできます。以下は例です。
{
templates(path: "/sitecore/templates/sample/Sample Item") {
name
baseTemplates {
name
}
ownFields {
name
id
unversioned
shared
}
}
}
GraphQL の型システムのため、ownFields
によって返される型は、同じ実装で、アイテム フィールドの定義によって返される型の配列と同じです。これにより、たとえば、アイテムの特別なフィルタリングの結果を公開する場合など、豊富な API を簡単に公開できます。その後、GraphQL のフィールドから ItemInterfaceGraphType
を返して、アイテムをソースとして渡します。テンプレート フィールドの定義の取得を含め、ItemInterfaceGraphType
をクエリする全機能をコンシューマーは利用できます。
コンテンツ検索 API
キーワード検索のニーズを満たすように設計された基本的なコンテンツ検索 API があります。これは主に、検索クエリは一般的な API が提供できるものを超えて、すぐに複雑になる可能性があるためです。以下は、この API の使用例です。
{
search(keyword: "sample" first: 3 facetOn: ["_template"]) {
results {
# Result info using the Connection pagination pattern
# (the standard way to do paging in GraphQL)
totalCount
pageInfo {
hasNextPage
hasPreviousPage
}
items {
# these values are from the index
score
path
# but this resolves the actual item - and because it's an Item type
# we can do anything we can do to an item - type it, query it
# anything. It's lazy, so unless we query the item property, the item
# is not looked up.
item {
icon
...on Template {
masters {
displayName
}
}
}
}
}
# and we can do faceting, too
facets {
name
values(hideEmpty: true) {
count
# just like the search results, for facets that are IDs,
# we can choose to resolve their Item from the database
# and query it with full capabilities
item {
displayName
icon
}
}
}
}
}
結果は以下のようになります。
{
"data": {
"search": {
"results": {
"totalCount": 12,
"pageInfo": {
"hasNextPage": true,
"hasPreviousPage": false
},
"items": [
{
"score": 2.16668963432312,
"path": "/sitecore/system/settings/rules/insert options/rules/analytics campaigns",
"item": {
"icon": "http://habitat.dev.local/-/icon/Software/32x32/shape_ellipse.png"
}
},
...
]
},
"facets": [
{
"name": "_template",
"values": [
{
"count": 3,
"item": {
"displayName": "Sublayout",
"icon": "http://habitat.dev.local/-/icon/Software/16x16/element_selection.png"
}
},
{
"count": 2,
"item": {
"displayName": "Folder",
"icon": "http://habitat.dev.local/-/icon/Applications/16x16/folder.png"
}
},
...
]
}
]
}
}
}
サブスクリプション
サブスクリプションは、リアルタイムのデータ更新を単純に抽象化したものです。サブスクリプションが特定の型の GraphQL クエリに制限されることを除いて、これは SignalR の動作に似ています。クエリを実行しても、すぐには結果が得られない場合があります。クエリは、停止するように指示するまで開いたままになり、複数のリアルタイムの結果を返すことがあります。itemSaved
サブスクリプションの使用例を以下に示します。
subscription {
itemSaved {
item {
id
...on SampleItem {
title {
rendered
}
}
}
changes {
fieldChanges {
fieldName
newValue
}
}
}
}
このサブスクリプションが開始されると、アイテムがコンテンツ エンドポイントのデータベースに保存されるたびに、新しいクエリ結果が得られます。
{
"itemSaved": {
"item": {
"id": "{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}",
"title": {
"rendered": "subscriptions rock"
}
},
"changes": {
"fieldChanges": [
{
"fieldName": "__Updated",
"newValue": "20171222T153248Z"
},
...
]
}
}
}
サブスクリプションは、WebSocket プロトコルを使用してリアルタイムの性質を有効にします。これらは UI でリアルタイム要素を有効にします。サブスクリプションは、サーバー上で Reactive Extensions およびクライアント上で RxJS からの Observable パターンによく一致します。Observable は、イベントの非同期ストリーム、または複数回解決できる JavaScript の Promise のようなものと考えることができます。
一意の名前
Sitecore では、複数のテンプレートに同じ名前を付けることができます (File など)。また、アイテム グラフ型の core フィールドと名前が競合するフィールドを持つ複数のテンプレート (Icon など) を持つことができます。
GraphQL では、型とフィールドの名前は一意である必要があります。名前の競合が発生した場合、作成日が最も新しいアイテムまたはフィールド アイテムの名前に _{guid}
が追加されます。順序が安定している必要があるため、作成日が使用されます。したがって、参照したグラフ型名は変更されません。間違えてシステム テンプレートと同じ名前のテンプレートを作成しても、システム テンプレートのグラフ型名が古いため変更されません。
この問題を回避するために、Sitecore で定義されたテンプレートのサブセットのみを厳密に型指定することできます。これは、ユーザーが作成した API エンドポイントが、ユーザーのプロジェクトで定義したテンプレートのみを提供する必要がある場合のベスト プラクティスです。