GraphQL Compose

DrupalでGraphQLスキーマを生成するためのツールキット。Drupal GraphQLモジュール用の拡張可能なノーコードGraphQLスキーマを提供します。

graphql_compose
2,132 sites
46
drupal.org
api gui development
graphql API headless decoupled esquema alternativa-rest api-de-contenido jamstack

概要

GraphQL Composeは、DrupalでGraphQLスキーマを生成するための包括的なツールキットです。DrupalのGraphQL 4.x/5.xモジュール用の拡張可能なノーコードGraphQLスキーマを提供し、「Drupal特有の概念」を最小限に抑えた、シンプルで理解しやすいスキーマの提供を目指しています。

このモジュールは、プラグインベースのアーキテクチャを通じてDrupalのEntityとFieldからGraphQLスキーマを自動生成します。50種類以上のFieldタイプをそのままサポートし、オプションのサブモジュールを通じてNode、Media、Taxonomy Term、User、Paragraphなどをサポートします。

主要なアーキテクチャ機能には、各GraphQLサーバーが独立した設定を持てるサーバー単位の設定、Edgesサブモジュールによるカーソルベースのページネーション、ルーティングとURL解決、Menuサポート、Layout Builder統合、カスタマイズのための豊富なHookシステムが含まれます。

Features

  • コードを書かずにDrupal EntityからGraphQLスキーマを自動生成
  • 54以上のFieldタイプハンドラー、8以上のEntityタイプハンドラー、30以上のスキーマタイプ定義を持つプラグインベースのアーキテクチャ
  • サーバー単位の設定 - 各GraphQLサーバーが独立したGraphQL Compose設定を持てる
  • Connection/Edgeパターンによるカーソルベースのページネーションサポート（graphql_compose_edgesサブモジュール経由）
  • パスエイリアスとリダイレクトをサポートするコンテンツルーティングとURL解決
  • DrupalメニューをGraphQLクエリとして公開するMenuシステム統合
  • 複雑なページレイアウトのためのLayout BuilderとLayout Paragraphsサポート
  • 7言語での単数形/複数形変換に対応した多言語サポート
  • レスポンシブ画像のためのImage Style派生サポート
  • カスタムBlockとプラグインBlockを含むBlockコンテンツの公開
  • コメント作成のMutationを含むCommentsサポート
  • フィルタリングとソートが可能なGraphQLクエリのためのViews統合
  • SEOメタデータのためのMetatagモジュール統合
  • カスタムEntityタイプのためのEntity Construction Kit (ECK) サポート
  • RoleとStatusを含むユーザー情報の公開
  • スキーマ生成、Field解決、タイプ定義のカスタマイズを可能にする豊富なHookシステム
  • 有効化されたEntityタイプに簡単に参照できるUUIDコピー操作を追加

Use Cases

React/Vue/Next.jsを使用したヘッドレスDrupal

GraphQL Composeを使用してDrupalコンテンツをJavaScriptフロントエンドフレームワークに公開します。必要なEntityタイプとFieldを有効にし、URLをコンテンツに解決するためにroutesサブモジュールを使用し、ページネーション付きリストのためにedgesサブモジュールを使用します。新しいコンテンツタイプやFieldを追加すると、スキーマは自動的に更新されます。

モバイルアプリバックエンド

GraphQL経由でDrupalコンテンツをネイティブモバイルアプリケーションに公開します。オフライン同期のためにEntity ID公開を有効にし、最適化されたモバイル画像のためにImage Styleを使用し、認証のためにuserサブモジュールを活用します。シンプルクエリオプションにより、モバイル開発者向けのよりクリーンなAPIが提供されます。

マルチサイトコンテンツAPI

サーバーごとの設定を使用して、異なるコンシューマー向けに異なるGraphQL APIを作成します。各クライアントアプリケーション用に異なるEntity/Field設定、エンドポイントパス、アクセス制御を持つ別々のGraphQLサーバーを作成します。

コンテンツプレビューシステム

Entityプレビューバッファ付きのroutesサブモジュールを使用してコンテンツプレビューシステムを構築します。モジュールは編集ワークフローのためのドラフトコンテンツ解決と言語固有のプレビューを処理します。

複雑なページ構築

Layout BuilderまたはLayout Paragraphsサブモジュールを組み合わせて複雑なページ構造を公開します。スキーマはセクション、リージョン、コンポーネントを表現し、フロントエンドがDrupalで定義された柔軟なページレイアウトをレンダリングできるようにします。

ECサイト商品カタログ

商品コンテンツタイプとそのField、異なる表示コンテキスト用の複数のImage Styleを持つ画像、カテゴリ用のTaxonomy Termを公開します。ページネーション付きのフィルタリング/ソート可能な商品リストのためにViews統合を使用します。

多言語コンテンツ配信

組み込みの言語サポートを活用して複数の言語でコンテンツを提供します。言語コンテキストはすべてのリゾルバーを通じて流れ、Inflectorサービスは非英語言語の適切な複数形化を処理します。

Tips

  • Entityドロップボタンに追加された「UUIDをコピー」操作を使用して、テストクエリ用のEntity UUIDを簡単に取得できます
  • 「シンプルなEntityクエリ」を有効にしてスキーマの複雑さを軽減 - 別々のnodePage、nodeArticleクエリの代わりに、Unionを返す単一のnodeクエリが得られます
  • /admin/config/graphql/servers/{server}/explorer のGraphQL Explorerを使用してクエリをインタラクティブにテストできます
  • infoクエリはスキーマバージョンとカスタム設定を提供します - キャッシュ無効化と機能フラグに使用してください
  • 開発時は、デバッグオプションのためにgraphql_compose.services.ymlの「development」パラメータを確認してください
  • InformationフォームのカスタムE設定は、Tokenモジュールがインストールされている場合Drupal Tokenをサポートします
  • Inflectorは7言語をサポート - 正しい複数形化のために主要なコンテンツ言語に適切な言語を設定してください
  • hook_graphql_compose_field_results_alter()を使用して、クライアントに届く前にField値を変換できます
  • 各GraphQLサーバーは独立したGraphQL Compose設定を持てます - バージョン管理されたAPIや異なるクライアントニーズに使用してください

Technical Details

Admin Pages 3
GraphQL Compose Schema /admin/config/graphql/servers/manage/{graphql_server}/graphql_compose

GraphQL経由で公開するDrupal Entityタイプ、バンドル、Fieldを設定します。これは、特定のコンテンツタイプ、Taxonomyボキャブラリー、Mediaタイプ、およびそれらの個別のFieldのGraphQL公開を有効/無効にするメイン設定ページです。

GraphQL Compose Information /admin/config/graphql/servers/manage/{graphql_server}/graphql_compose/info

GraphQLの「info」クエリ経由で公開されるスキーマメタデータとサイト情報を設定します。バージョン情報、サイト名、スローガン、カスタムキーバリューペアが含まれます。

GraphQL Compose Settings /admin/config/graphql/servers/manage/{graphql_server}/graphql_compose/settings

Entity処理、Fieldオプション、文字列変換ルールを含むGraphQL Composeの一般的な動作設定を構成します。

Hooks 18
hook_graphql_compose_print_types

スキーマにカスタムGraphQLタイプを追加します。新しいObjectType、InterfaceType、EnumType、その他のGraphQLタイプ定義を登録するためにスキーマ生成中に呼び出されます。

hook_graphql_compose_print_extensions

既存のGraphQLタイプに拡張を追加します。Query、Mutation、またはスキーマ内の既存のタイプに新しいFieldを追加するために使用します。

hook_graphql_compose_singularize_alter

言語単数形化からの結果を変更します。GraphQLタイプ命名のためにバンドル名が単数形に変換される方法をカスタマイズします。

hook_graphql_compose_pluralize_alter

言語複数形化からの結果を変更します。コレクションクエリのためにタイプ名が複数形に変換される方法をカスタマイズします。

hook_graphql_compose_field_enabled_alter

Fieldの有効状態を変更します。管理者設定に関係なく、GraphQLスキーマでFieldをプログラム的に表示/非表示にするために使用します。

hook_graphql_compose_field_results_alter

Field解決からの結果を変更します。特定のFieldに対して返されるデータを変更、フィルタリング、または完全に置き換えます。

hook_graphql_compose_entity_interfaces_alter

Entityタイプにカスタムインターフェースを追加します。共通のFieldや動作に基づいてEntityタイプ間で共有インターフェースを追加するために使用します。

hook_graphql_compose_entity_bundle_enabled_alter

Entityバンドルの有効状態を変更します。GraphQLスキーマにEntityバンドルをプログラム的に含めたり除外したりするために使用します。

hook_graphql_compose_entity_base_fields_alter

Entityタイプで利用可能なベースFieldを変更します。GraphQL公開のために処理される前にベースFieldを追加または削除します。

hook_graphql_compose_entity_type_form_alter

Entityタイプ設定フォームを変更します。EntityバンドルのGraphQL Compose Schemaフォームにカスタム設定を追加します。

hook_graphql_compose_field_type_form_alter

Fieldタイプ設定フォームを変更します。個々のFieldのGraphQL Compose Schemaフォームにカスタム設定を追加します。

hook_graphql_compose_entity_translate_alter

Entity翻訳動作を上書きします。特定の言語コンテキストで解決されるときにEntityがどのように翻訳されるかをカスタマイズします。

hook_graphql_compose_current_language_alter

Fieldコンテキストの言語解決を上書きします。多言語コンテンツを解決するときに使用される言語をカスタマイズします。

hook_graphql_compose_routes_incoming_alter

ルート解決前にURLパスを変更します。Entityに解決される前にパスを変換または正規化します。

hook_graphql_compose_routes_union_alter

カスタムルートタイプを解決します。RouteUnionのルート値を特定のGraphQLタイプにマッピングします。

hook_graphql_compose_edges_alter

Entity用のEdgeコネクションを変更します。Entityコレクションのページネーション、フィルタリング、またはソートをカスタマイズします。

hook_graphql_compose_blocks_union_alter

カスタムBlockタイプを解決します。BlockUnionのBlockプラグイン値を特定のGraphQLタイプにマッピングします。

hook_graphql_compose_metatags_union_alter

カスタムMetatagタイプを解決します。MetaTagUnionのMetatag値を特定のGraphQLタイプにマッピングします。

Troubleshooting 7
Fieldを有効にした後にGraphQLスキーマが更新されない

GraphQL ComposeフォームのいずれかでCで「設定を保存」をクリックするか、「drush cr」を実行してGraphQLキャッシュをクリアします。設定が変更されると、モジュールは自動的にキャッシュをクリアします。

EntityタイプがSchemaフォームに表示されない

EntityタイプにGraphQL Compose Entityタイププラグインがあることを確認してください。コアタイプ（node、media、taxonomy_term、user、paragraph）はサポートされています。その他のタイプについては、適切なサブモジュールを有効にしてください（block_content用のgraphql_compose_blocks、ECK Entity用のgraphql_compose_eck）。

Fieldタイプがサポートされていない

Fieldに対応するFieldタイププラグインが存在するか確認してください。モジュールは54以上のFieldタイプをサポートしています。サポートされていないFieldについては、hook_graphql_compose_print_types()とhook_graphql_compose_print_extensions()を実装してカスタム処理を追加してください。

GraphQLクエリでアクセス拒否エラーが発生する

GraphQL ComposeはDrupalのアクセス制御を尊重します。Entityアクセス権限を確認し、「exclude_unpublished」設定がニーズに合っているか確認し、クエリを実行するユーザーが適切な権限を持っているか確認してください。

Entity参照がnullを返す

参照されるEntityが公開されていること（exclude_unpublishedが有効な場合）、参照されるEntityタイプ/バンドルがGraphQL Composeで有効になっていること、ユーザーが参照されるEntityを表示する権限を持っていることを確認してください。

ページネーションが機能しない

カーソルベースのページネーションのためにgraphql_compose_edgesサブモジュールを有効にしてください。これがないと、Entity参照Fieldはページネーションサポートのないフラットな配列を返します。

Routesクエリがパスを解決しない

graphql_compose_routesサブモジュールを有効にし、Entityバンドルが SchemaフォームでD「ルート読み込みを有効化」にチェックが入っていることを確認してください。Drupalでパスエイリアスが正しく設定されているか確認してください。

Security Notes 7
  • デフォルトでは、列挙攻撃を防ぐためにEntity IDは公開されません。アプリケーションが数値IDを必要とする場合のみ「Entity IDを公開」を有効にしてください。
  • モジュールはDrupalのEntityアクセスシステムを尊重します。ユーザーは表示権限を持つコンテンツのみをクエリできます。
  • Mutationを伴うcommentsサブモジュールを使用する場合、入力はXSSに対してサニタイズされますが、アプリケーションでユーザー入力を適切に検証してください。
  • 「未公開Entityを除外」設定は、表示権限を持つ可能性のあるユーザーからも未公開コンテンツを非表示にすることで多層防御を提供します。
  • SVG埋め込みには、大きなSVGファイルによるサービス拒否を防ぐためのファイルサイズ制限があります。ニーズに応じて制限を調整してください。
  • GraphQLイントロスペクションはデフォルトで有効になっています。スキーマの公開を望まない場合は、本番環境で無効にしてください。
  • routesサブモジュールは受信パスを正規化します - 追加のパス検証が必要な場合はhook_graphql_compose_routes_incoming_alter()を実装してください。