コンテンツをテストするためにGraphQL IDEをセットアップします

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

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

GraphQL IDE(GraphQL Playground)はグラフィカルなブラウザ内型IDEで、GraphQL APIを探索したり、クエリを作成したり、レスポンス構造を検査・理解したりできます。IDEは特に、アプリケーションで使用する前に開発中のクエリをテストするのに有効です。

このGraphQL IDEは以下の用途で利用可能です:

プレビュー GraphQL API - ドラフト(未公開)および公開済みのコンテンツを含むすべてのコンテンツを取得します。ローカル開発やアプリの非本番環境(テストやステージング)に理想的です。これらの環境では、コンテンツ作成者はドラフトをプレビューでき、開発者は公開前にドラフトを含むフロントエンドを構築しテストできます。裏側では、すべてのSitecoreコンテンツがあなたのコンテンツ管理インスタンスに保存されています。コンテンツ管理インスタンスはこのAPIを公開します。
Delivery GraphQL API - 公開コンテンツのみ取得。ドラフトコンテンツが利用できないアプリ本格環境に理想的です。舞台裏では、公開コンテンツはExperience Edgeから提供されています。Experience EdgeはこのAPIを公開します。Experience Edgeは、グローバルに分散された高性能なコンテンツ配信レイヤーです。静的でキャッシュされたコンテンツを提供するため、非常に効率的です。

注記

プレビューGraphQL APIとDelivery GraphQL APIは異なるコンテンツを返しますが、認証方法、機能、クエリの形状、応答の形状は同一です。両方のGraphQL APIは読み取り専用です。

GraphQL IDEはAuthoringや管理GraphQL APIでも利用可能で、コンテンツの取得や改Sitecoreが可能です。

The GraphQL IDE showing an example query for a page layout.

プレビューAPIのIDEを設定してください

プレビュー APIのGraphQL IDEを設定するには:

Sitecore Cloud PortalホームページのQUICK LINKSセクションでSitecoreAI Deployをクリックしてください。
DeployアプリのProjectsページで、該当するプロジェクトをクリックしてください。
GraphQL IDEを使いたい環境をクリックしてください。
DetailsタブのPreview GraphQL IDEセクションでGenerate Preview API tokenをクリックしてトークンをコピーします。トークンは後のステップでGraphQL IDEで使います。

警告

プレビュー APIトークンは /sitecore/system/Settings/Services/API Keys/に安全に保存されています。このアイテムを削除または修正すると、Generate Preview API tokenボタンが壊れる可能性があります。
Preview GraphQL IDEセクションでLaunch IDEをクリックします。GraphQL IDEは新しいタブで開きます。

注記

また、ウェブブラウザで以下のURLを開くことでIDEにアクセスすることもできます:

https://{:placeholder-token:}<YOUR_ENVIRONMENT_HOST_NAME>{/:placeholder-token:}/sitecore/api/graph/edge/ide/

プレースホルダーを環境ホスト名に置き換えてください。環境のDetailsタブで値を見つけてください。

Sitecore開発にDockerを使っているなら、localhostを使ってプレビュー APIのGraphQL IDEにアクセスすることもできます。
GraphQL IDEのHTTP HEADERSタブで、以下のコードを入力し、APIトークンのプレースホルダーを前のステップでコピーしたトークンに置き換えます:
{ "sc_apikey": "<YOUR_API_TOKEN>" }
これでIDEでGraphQLクエリを始められます。

Delivery APIのIDEを設定してください

デリバリーのGraphQL IDEを設定するにはAPI:

Sitecore Cloud PortalホームページのQUICK LINKSセクションでSitecoreAI Deployをクリックしてください。
DeployアプリのProjectsページで、該当するプロジェクトをクリックしてください。
GraphQL IDEを使いたい環境をクリックしてください。
DetailsタブのLive GraphQL IDE (Experience Edge)セクションでGenerate Delivery API tokenをクリックしてトークンをコピーします。トークンは後のステップでGraphQL IDEで使います。

注記

これはDelivery APIを呼び出す際に認証に使うトークンと同じです。
Live GraphQL IDE (Experience Edge)セクションでLaunch IDEをクリックします。GraphQL IDEは新しいタブで開きます。

注記

また、ウェブブラウザで以下のURLを開くことでIDEにアクセスすることもできます:

https://edge.sitecorecloud.io/api/graphql/ide
GraphQL IDEのHTTP HEADERSタブで、以下のコードを入力し、APIトークンのプレースホルダーを前のステップでコピーしたトークンに置き換えます:
{ "sc_apikey": "<YOUR_API_TOKEN>" }
これでIDEでGraphQLクエリを始められます。

クエリを出す

GraphQL IDEを設定したら、クエリを始めることができます。

以下は、すべてのサイト名、言語、ルートパスを含むすべてのサイト情報を取得する例のクエリです:

query {
  site {
    allSiteInfo {
      results {
        name
        hostname
        language
        rootPath
      }
    }
  }
}

クエリ変数を使う

GraphQL IDEでクエリを増やすにつれて、特定のデータをクエリ変数として保存し、その情報をクエリにハードコーディングしないようにすることができます。

以下は、ページのパスでレイアウトデータ(ページ表現)を完全に取得する例のクエリです。クエリは $site、$language、$routePathに対してGraphQL変数を使用していることに注意してください。

query LayoutQuery($site: String!, $language: String!, $routePath: String!) {
  layout(site: $site, language: $language, routePath: $routePath) {
    item {
      rendered
    }
  }
}

このクエリを実行するには、まずQUERY VARIABLESタブで変数とその値を指定する必要があります:

{
  "site": "my-site",
  "language": "en",
  "routePath": "/"
}

これにより、よく使われる値を一か所で指定・更新でき、クエリ全体で再利用できます。

GraphQLスキーマへのアクセス

GraphQLスキーマは、APIが公開するすべての型、フィールド、引数、関係を定義する契約です。これはSDL(スキーマ定義言語)で書かれており、どのクエリが有効で応答がどのような形になるかの唯一の真実の情報源です。IDEからGraphQLスキーマをダウンロードし、開発環境でクエリ検証、オートコンプリート、型生成などのローカルツールを設定することができます。

スキーマファイルは特に検索や型定義のコピーペスト、LLMに読み取ってもらい質問できるのに便利です。

GraphQLスキーマにアクセスするには:

GraphQL IDEの右側でSCHEMAをクリックします。GraphQLスキーマが表示されます。
オプションでスキーマをダウンロードするには、DOWNLOADをクリックして利用可能なフォーマットのいずれかを選択してください。
- JSON - スキーマをJSONファイルとしてダウンロードすること。
- SDL - スキーマをSDL(.graphql)ファイルとしてダウンロードすること。

GraphQL参照ドキュメントへのアクセス

GraphQLの参照ドキュメントは、ナビゲートしやすく人間に優しい参照資料です。特にクエリのナビゲートやタイプ、インターフェースの詳細を読むのに便利です。

GraphQLの参考ドキュメントにアクセスするには:

GraphQL IDEの右側でDOCSをクリックします。GraphQLの参照ドキュメントが掲載されています。
ナビゲートを始めるには、ルートクエリをクリックしてください。タイプ、インターフェース、引数の詳細が表示されたら、詳しく知りたいものをクリックしてください。

注記

GraphQLスキーマと参照ドキュメントはどちらも同じ基盤データを使用しています。主な違いは、スキーマが機械可読で検索に理想的であるのに対し、参照ドキュメントは人間が読みやすく、GraphQL実装のナビゲーションに適している点です。

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