External Entities
REST API、ファイルシステム、SQLデータベース、その他のストレージバックエンドを通じて、外部ソースのデータセットをネイティブDrupalエンティティとして接続・利用できるようにします。
external_entities
概要
External Entitiesは、外部データソースに接続し、それらをネイティブDrupalエンティティとして公開できる強力なモジュールです。コンテンツは外部（リモートサーバー、ファイル、外部データベース）に存在しながら、Drupalはこれらのエンティティを内部コンテンツであるかのように扱います。これにより、フィールド表示設定、エンティティ参照、コメント、パスエイリアス、Views統合など、Drupalのエンティティシステム機能を活用できます。
このモジュールは5種類のプラグインタイプを持つ柔軟なプラグインアーキテクチャを提供します：複数ソースを結合するData Aggregator、異なるデータバックエンドに接続するStorage Client、ソースデータをDrupalフィールドにマッピングするField Mapper、ソースプロパティをフィールドプロパティにマッピングするProperty Mapper、データ値を変換するData Processorです。このモジュールはアノテーション（外部エンティティにローカル保存データを追加する機能）をサポートし、言語固有の設定オーバーライドによる多言語サポートも提供します。
External Entitiesは、外部REST APIからデータを表示する必要がある場合、レガシーシステムからコンテンツをインポートする場合、複数ソースからデータを集約する場合、またはDrupalのデータベースにデータを複製せずに分散データの統一ビューを作成する場合に最適です。
Features
- リモートデータをDrupalエンティティにマッピングし、完全なエンティティシステム統合を持つ外部エンティティタイプを作成
- 認証、カスタムヘッダー、クエリ制限、レスポンスキャッシングを含む包括的な設定でREST APIに接続
- ファイルメタデータ抽出とパスパターンマッチングのサポートにより、ファイルをエンティティとして使用
- コンパニオンモジュールxnttsqlを介してSQLデータベース（MySQL/PostgreSQL）に接続
- 水平、垂直、またはグループ集約モードを使用して、複数のStorage Clientからデータを集約
- JSONPathサポートを持つ設定可能なField MapperとProperty Mapperを使用して、ソースデータをDrupalフィールドにマッピング
- ブール変換、日付/時刻フォーマット、数値抽出、文字列大文字小文字変換、値マッピング用の組み込みData Processorでデータ値を処理
- 外部エンティティをローカルコンテンツエンティティにリンクすることで、ローカルアノテーションを追加
- 言語ごとのフィールドマッピングとStorage Clientオーバーライドによる多言語設定をサポート
- パフォーマンス向上のための設定可能なキャッシュ期間によるエンティティキャッシング
- 外部エンティティタイプの読み取り専用モードサポート
- トラブルシューティング用の詳細ログ付きデバッグモード
- コンパニオンモジュールxntt_viewsによるViews統合
- コンパニオンモジュールexternal_entities_pathautoによるPathauto統合
- コンパニオンモジュールxntt_file_fieldによるファイルおよび画像フィールドサポート
Use Cases
REST APIデータをDrupalコンテンツとして表示
外部REST API（製品カタログ、ニュースフィード、ユーザーディレクトリなど）に接続し、データをネイティブDrupalコンテンツとして表示します。フィールドマッピングを設定してAPIレスポンスを構造化されたエンティティフィールドに変換し、Viewsを適用して一覧を作成し、表示モードを使用して一貫したテーマ設定を行います。
Drupal 7からの移行
JSON:APIまたはREST Storage Clientを使用して、RESTful Web Servicesを実行しているDrupal 7サイトに接続します。移行中にDrupal 10/11でD7コンテンツを表示し、オプションでExternal Entity Managerを使用してデータを物理的にインポートおよび同期できます。
複数ソースからのデータ集約
Group Aggregatorを使用して複数のStorage Clientからのデータを結合します。例えば、REST APIからの製品情報とSQLデータベースからの価格データをマージしたり、ジョイン条件を使用して異なるシステムからのユーザープロファイルを結合したりします。
ファイルベースのエンティティストレージ
Files Storage Clientを使用してローカルファイルをエンティティとして扱います。ファイルメタデータ（名前、サイズ、日付）とパスコンポーネントをフィールドとして抽出します。ファイルシステムに保存されたドキュメントライブラリやメディアアセットの管理に便利です。
外部コンテンツへのアノテーション追加
アノテーションを有効にして、外部エンティティにローカルDrupalデータ（コメント、評価、タグ）を追加します。外部エンティティをローカルコンテンツタイプにリンクし、表示用にアノテーションエンティティから選択したフィールドを継承します。
多言語外部コンテンツ
現在の言語コンテキストに基づいて異なるAPIエンドポイントまたはデータベースからローカライズされたコンテンツを取得するために、言語固有のStorage Clientまたはフィールドマッピングを設定します。
Tips
- エンティティの読み込みと一覧表示に必要なため、常にエンティティ識別子（id）フィールドを最初にマッピングしてください
- 他のDrupalサイトに接続する場合は、最適化された統合を提供するJSON:API Storage Clientを使用してください
- 開発中はデバッグモードを有効にして、すべてのStorage Client操作をログに記録し、マッピングの問題を特定してください
- 外部APIへの負荷を軽減するために本番環境では永続キャッシングを設定してください
- IDが重複する可能性のあるソースを結合する場合は、Group Aggregatorの「仮想グループプレフィックス」機能を使用してください
- 大規模な外部データセットを持つViewsでより良いクエリパフォーマンスを得るためにSearch API統合を検討してください
- 偶発的なUI変更を防ぐために、プログラムで作成した外部エンティティタイプ設定をロックしてください
- 画像スタイルを活用するために外部ファイルURLをマッピングする場合はxntt_file_fieldモジュールを使用してください
Technical Details
Admin Pages 3
/admin/structure/external-entity-types
システムに設定されているすべての外部エンティティタイプを一覧表示します。このページから外部エンティティタイプの追加、編集、削除、およびフィールドと表示を管理するためのField UI操作にアクセスできます。
/admin/structure/external-entity-types/add
基本設定、ストレージソース、フィールドマッピング、キャッシング、アノテーションオプションを設定して新しい外部エンティティタイプを作成します。
/admin/config/external
外部データ関連設定の設定カテゴリページ。
権限 6
Hooks 1
hook_external_entity_transform_raw_data_alter
生データが外部エンティティにマッピングされる前に変更します
Troubleshooting 5
エンティティ識別子フィールド（id）が正しくマッピングされていることを確認してください。Storage Clientエンドポイントがアクセス可能で有効なデータを返していることを確認してください。デバッグモードを有効にしてAPIリクエストとレスポンスをログに記録してください。
Property Mapper設定が正しいパス構文を使用していることを確認してください。ネストされたデータの場合、JSONPath式（$.field.subfield）またはシンプルなドット記法（field.subfield）を使用してください。値の変換が必要な場合はData Processor設定を確認してください。
REST Storage Clientの「1秒あたりの最大クエリ数」設定を構成してAPIレート制限を遵守してください。クエリ制限を有効にしてリクエストを追跡および制限してください。
適切なキャッシュ期間で永続キャッシングを有効にしてください。Viewsクエリ用に外部データをインデックス化するためにSearch APIの使用を検討してください。RESTソースの場合、個別のエンティティ読み込みを避けるために、リストエンドポイントが完全なエンティティデータを返すことを確認してください。
保存する前に必須フィールドマッピング（id、title）が設定されていることを確認してください。Storage Client設定のバリデーションエラーを確認してください。キャッシュをクリアし、galbar/jsonpathライブラリがインストールされていることを確認してください。
Security Notes 6
- 外部データソースには、適切にフィルタリングされないとサイトのセキュリティを危険にさらす可能性のある信頼できないコンテンツが含まれている場合があります
- 「administer external entity types」権限を持つ管理者はシステムファイルとデータベース資格情報にアクセスできます - この権限は信頼できるユーザーにのみ付与してください
- 外部ソースからのデータ、特にユーザー生成コンテンツを表示する場合は、常に検証とサニタイズを行ってください
- 外部システムへの書き込みアクセスが不要な場合は、Storage Clientを読み取り専用モードで設定してください
- 機密データを送信する場合は、REST APIエンドポイントに安全な接続（HTTPS）を使用してください
- 設定されたデータベースで任意のクエリを実行できるため、SQL Storage Clientには注意してください