---
title: "Sitecore GraphQL APIを使い始めてください"
slug: "start-using-sitecore-graphql-api"
abstract: "GraphQLをSitecoreでセットアップし使い始める方法を説明します"
---
# Sitecore GraphQL APIを使い始めてください

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

> !重要もしあなたのサイトがフォールバック言語をサポートしている場合は、始める前に必ずExperience Edgeコネクターで [出版言語のフォールバックを有効にし](https://doc.sitecore.com/xp/ja/developers/hd/19/sitecore-headless-development/enable-publishing-language-fallback.html "Enable publishing language fallback") てください。

## セットアップSitecore GraphQL

Sitecore GraphQLの準備をします:

1.  web.configファイルで<compilation debug="true">を設定します。これにより、デフォルトのセキュリティ設定で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エンドポイント](https://doc.sitecore.com/xp/ja/developers/hd/19/sitecore-headless-development/sitecore-experience-edge-for-xm.html "Sitecore Experience Edge for XM") はデフォルトで有効化されていますが、追加のエンドポイントを設定することも可能です。

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

-   GraphQL APIを使うエンドポイントを少なくとも1つ定義してください。
    
    以下の例は、マスターデータベースに必要な認証を持つコンテンツAPIエンドポイントを定義しています。
    
    <?xml version="1.0" encoding="utf-8" ?>
    
    <!--
     Defines the system endpoint for the master database.
    -->
    <configuration xmlns:patch="http://www.sitecore.net/xmlconfig/" xmlns:role="http://www.sitecore.net/xmlconfig/role/">
     <sitecore>
     <api>
     <GraphQL>
     <endpoints>
     <master url="/sitecore/api/graph/items/master" type="Sitecore.Services.GraphQL.Hosting.GraphQLEndpoint, Sitecore.Services.GraphQL.NetFxHost" resolve="true">
     <url>$(url)</url>
    
     <enabled role:require="ContentDelivery">false</enabled>
    
     <enableSubscriptions>true</enableSubscriptions>
    
     <!-- lock down the endpoint when deployed to content delivery -->
     <graphiql role:require="ContentDelivery">false</graphiql>
     <enableSchemaExport role:require="ContentDelivery">false</enableSchemaExport>
     <enableStats role:require="ContentDelivery">false</enableStats>
     <enableCacheStats role:require="ContentDelivery">false</enableCacheStats>
     <disableIntrospection role:require="ContentDelivery">true</disableIntrospection>
    
     <schema hint="list:AddSchemaProvider">
     <!-- defaults are defined in Sitecore.Services.GraphQL.Content.config -->
     <content ref="/sitecore/api/GraphQL/defaults/content/schemaProviders/systemContent" param1="master" />
     </schema>
    
     <!-- Determines the security of the service. Defaults are defined in Sitecore.Services.GraphQL.config -->
     <security ref="/sitecore/api/GraphQL/defaults/security/systemService" />
    
     <!-- Determines how performance is logged for the service. Defaults are defined in Sitecore.Services.GraphQL.config -->
     <performance ref="/sitecore/api/GraphQL/defaults/performance/standard" />
    
     <!--
     Cache improves the query performance by caching parsed queries.
     It is also possible to implement query whitelisting by implementing an authoritative query cache;
     WhitelistingGraphQLQueryCache is an example of this, capturing queries to files in open mode and allowing only captured queries in whitelist mode.
     -->
     <cache type="Sitecore.Services.GraphQL.Hosting.QueryTransformation.Caching.GraphQLQueryCache, Sitecore.Services.GraphQL.NetFxHost">
     <param desc="name">$(url)</param>
     <param desc="maxSize">10MB</param>
     </cache>
    
     <!--
     Extenders allow modifying schema types after they are created by a schema provider but before they are added to the final schema.
     This is useful when you want to \_extend\_ a generated schema, for example, to add external API
     data onto the item API, or to add in custom internal data (e.g. custom layout data to power an app)
     without having to modify a schema provider directly.
    
     Extenders must derive from SchemaExtender.
     -->
     <extenders hint="list:AddExtender">
     <!--<example type="Name.Space.ExtenderType, Assembly" resolve="true" />-->
     </extenders>
     </master>
     </endpoints>
     </GraphQL>
     </api>
     </sitecore>
    </configuration>
    
    > !注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ファイルの設定パッチでそれぞれ無効にできます:
> 
> 偽 り 偽 り 偽り