1. Sitecore GraphQL API

Sitecore GraphQL APIを使い始めてください

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

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

このトピックでは、Sitecore GraphQL APIをどのように設定し、使うかを説明します。JSS server componentsパッケージをインストールすることでGraphQLが得られます。

!重要もしあなたのサイトがフォールバック言語をサポートしている場合は、始める前に必ずExperience Edgeコネクターで 出版言語のフォールバックを有効にし てください。

セットアップSitecore GraphQL

Sitecore GraphQLの準備をします:

  1. web.configファイルでを設定します。これにより、デフォルトのセキュリティ設定でGraphQL GUIが有効になります。セキュリティのため、本番環境ではGUIはデフォルトで無効化されています。

  2. GraphQLサブスクリプションやWebSocketトランスポートを使用する場合、IISでWebSockets機能を有効にしてからIISをリセットする必要があります。

    !注Windows Server 2008 R2以前ではWebSocketはサポートされていません。これらのOS上でホストされている場合、サブスクリプションは使用できません。

  3. CORSや偽装を使う場合は、master:/sitecore/system/Settings/Services/API KeysフォルダにSSC APIキーを設定してください。APIキーはGraphQLとSitecore Services Clientと同じように動作します。

GraphQLエンドポイントの設定

Sitecore Headless Services 16.0以降では、Edge Previewエンドポイント はデフォルトで有効化されていますが、追加のエンドポイントを設定することも可能です。

GraphQLエンドポイントの設定:

  • GraphQL APIを使うエンドポイントを少なくとも1つ定義してください。

    以下の例は、マスターデータベースに必要な認証を持つコンテンツAPIエンドポイントを定義しています。

    $(url)

    false

    true

    false false false false true

    $(url) 10MB

    !注Sitecore GraphQLデフォルトの設定ファイルは利用可能な設定オプションを理解するための良いリソースです。エンドポイント設定でrefで参照されるデフォルトプリセットは特に興味深いです。ファイルは /App_Config/Sitecore/Services.GraphQLフォルダにあります。

GraphQLエンドポイントを使いましょう

GraphQLエンドポイントを定義すると、そのURLでアクセスできます。例えば、次のようなURLでAPIをクエリすることができます: http://my.sitecore.domain/sitecore/api/graph/items/master。

しかし、クエリはGraphiQL GUIで作成する方がはるかに簡単です。エンドポイントURLに /ui http://my.sitecore.domain/sitecore/api/graph/items/master/uiを追加することでGUIにアクセスします。GUI内のスキーマ制御自動完了機能を使ってGraphQLクエリを作成し、クエリをテストし、スキーマのドキュメントを確認できます。

前述の設定例では、GraphiQL GUIを使ってクエリを作成する方法:

  1. Sitecoreにログインしてください(例のエンドポイントは認証が必要です)。

  2. /sitecore/api/graph/items/master/uiへ行く。このUIはマスターデータベース内のアイテムやテンプレートをクエリできます。

  3. タイプスキーマを閲覧するにはDocsリンクをクリックしてください。

  4. GraphiQLのコード補完機能を使ってGraphQLクエリを書きます( CTRL-Spaceを押すと手動でトリガーされます)。例えば、次のクエリは、1つのクエリでアイテム、その子、テンプレート定義を取得します:

    { item(path: "/sitecore/templates") { id path children { name } template { fields { name } } } }

    結果(略して)は以下の通りです:

    { "data": { "item": { "id": "{3C1715FE-6A13-4FCF-845F-DE308BA9741D}", "path": "/sitecore/templates", "children": { "name": "Branches" }, { "name": "Sample" }, ... , "template": { "fields": { "name": "__Help link" }, ...

    } } } }

!注エンドポイントが認証を必要とするなら、GUIも認証が必要です。エンドポイントがSSCのAPIキー(?sc_apikey=api-key-guid)を必要とする場合、GUIもAPIキーを必要とします。

APIのクエリ

Sitecore GraphQL APIのクエリは他のGraphQLエンドポイントと比べて特別なものではありません。Apolloのようなクライアントライブラリの使用をお勧めします。

Sitecore GraphQLエンドポイントは以下の種類のGraphQLリクエストをサポートしています:

  • HTTP POSTは application/json コンテンツタイプと標準のJSONペイロード形式のクエリで行われます。
  • HTTP POST application/json コンテンツタイプと標準ペイロードの配列(バッチ処理に使用)JSON。
  • HTTP POSTは application/graphql コンテンツタイプと本文内の生のGraphQLクエリで行われます。
  • クエリ文字列パラメータ(query、 operationName、変数)を持つHTTP GET。
  • WebSocketは graphql-ws プロトコル(サブスクリプションまたはクエリ)で利用できます。

あらゆる種類のGraphQL操作はAPIフレームワークでサポートされています(スキーマがこれらすべての操作を実装している場合もあれば、そうでない場合もあります):

  • クエリ(データの読み取り)。
  • 突然変異(データの変更)。
  • サブスクリプション(リアルタイムのデータの更新にサブスクリプション)。

サブスクリプションはWebSocketを使用するApollo subscriptions-transport-wsプロトコルを用いて実装されます。ソケット接続は自動的にエンドポイントURLを付与GraphQL許可されます。

追加機能

GraphiQL /uiに加え、各GraphQLエンドポイントはいくつかの追加パーツもサポートしています:

  • $url/schema - GraphQLスキーマをSchema Definition Language(SDL)形式でダンプします。SDLフォーマットは、eslint-plugin-graphqlmのようなツールやgraphql-toolsのようなスキーマモッキングツールで、静的コード解析に有用です。
  • $url/stats - エンドポイントスキーマとその性能に関する基本的な統計を表示します。
  • $url/cache - エンドポイント上のGraphQLクエリキャッシュの詳細を表示します。

!注これらの追加エンドポイント機能は、web.configファイルの設定パッチでそれぞれ無効にできます:

偽 り 偽 り 偽り

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