Sitecore GraphQL API

GraphQLコンテンツスキーマ

Version:

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

このページの翻訳は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 &ndash; 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を返し、それをソースとしてItemに渡します。 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"
              }
            },
            ...
          ]
        }
      ]
    }
  }
}

サブスクリプション

サブスクリプションは、リアルタイムのデータ更新を単純に抽象化したものです。これはSignalRの動作方法と似ていますが、サブスクリプションが特定の種類のGraphQLクエリに制限される点が異なります。クエリを実行しましたが、すぐには結果が得られません。クエリは、停止するように指示するまで開いたままになり、クエリは複数のリアルタイム結果を返すことができます。ユースケースの例としては、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パターンによく適合します。オブザーバブルは、イベントの非同期ストリーム、または複数回解決できるJavaScript Promiseと考えることができます。

一意の名前

Sitecoreでは、複数のテンプレートに同じ名前 ( Fileなど) を付けたり、アイテムグラフタイプのコアフィールドと名前が競合するフィールドを持つテンプレート ( Iconなど) を持つことができます。

GraphQLでは、型とフィールドの名前は一意である必要があります。名前の競合が発生すると、作成日が最新のアイテムまたはフィールドアイテム _{guid} 名前に追加されます。作成日が使用されるのは、順序が安定している必要があるため、グラフ・タイプ名は参照後に変更されません。間違えてシステムテンプレートと同じ名前のテンプレートを作成した場合、システムテンプレートのグラフタイプ名は古いため変わりません。

この問題を回避するために、Sitecoreで定義されているテンプレートのサブセットのみを厳密に入力できます。これは、お客様が作成したAPIエンドポイントのベストプラクティスであり、プロジェクトで定義されたテンプレートのみを提供する必要があるためです。

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