External Entities
Allows connecting to and using datasets from external sources as native Drupal entities through REST APIs, file systems, SQL databases, and other storage backends.
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
Displaying REST API data as Drupal content
Connect to external REST APIs (e.g., a product catalog, news feed, or user directory) and display the data as native Drupal content. Configure field mappings to transform API responses into structured entity fields, apply Views to create listings, and use display modes for consistent theming.
Migrating from Drupal 7
Use the JSON:API or REST storage client to connect to a Drupal 7 site running RESTful Web Services. Display D7 content in Drupal 10/11 during migration, with the option to use External Entity Manager to physically import and synchronize data.
Aggregating data from multiple sources
Use the Group Aggregator to combine data from multiple storage clients. For example, merge product information from a REST API with pricing data from an SQL database, or combine user profiles from different systems using join conditions.
File-based entity storage
Use the Files storage client to treat local files as entities. Extract file metadata (name, size, date) and path components as fields. Useful for managing document libraries or media assets stored on the filesystem.
Annotating external content
Enable annotations to add local Drupal data (comments, ratings, tags) to external entities. Link external entities to local content types and inherit selected fields from the annotation entity for display.
Multi-language external content
Configure language-specific storage clients or field mappings to retrieve localized content from different API endpoints or databases based on the current language context.
Tips
- Always map the entity identifier (id) field first - this is required for entity loading and listing
- Use the JSON:API storage client for connecting to other Drupal sites as it provides optimized integration
- Enable debug mode during development to log all storage client operations and identify mapping issues
- Configure persistent caching for production to reduce load on external APIs
- Use the Group Aggregator's 'virtual group prefix' feature when combining sources with potentially overlapping IDs
- Consider Search API integration for Views with large external datasets for better query performance
- Lock external entity type configurations created programmatically to prevent accidental UI modifications
- Use the xntt_file_field module when mapping external file URLs to take advantage of image styles
Technical Details
Admin Pages 3
/admin/structure/external-entity-types
List all external entity types configured in the system. From this page you can add, edit, and delete external entity types, as well as access Field UI operations for managing fields and displays.
/admin/structure/external-entity-types/add
Create a new external entity type by configuring its basic settings, storage sources, field mappings, caching, and annotation options.
/admin/config/external
Configuration category page for external data related settings.
権限 6
Hooks 1
hook_external_entity_transform_raw_data_alter
Alter raw data before it is mapped to an external entity
Troubleshooting 5
Ensure the entity identifier field (id) is correctly mapped. Check that the storage client endpoint is accessible and returning valid data. Enable debug mode to log API requests and responses.
Verify the property mapper configuration uses the correct path syntax. For nested data, use JSONPath expressions ($.field.subfield) or simple dot notation (field.subfield). Check data processor configurations if values need transformation.
Configure the 'Maximum number of queries per second' setting in the REST storage client to respect API rate limits. Enable query limiting to track and throttle requests.
Enable persistent caching with an appropriate cache duration. Consider using Search API to index external data for Views queries. For REST sources, ensure the list endpoint returns complete entity data to avoid individual entity loading.
Ensure required field mappings (id, title) are configured before saving. Check for validation errors in the storage client configuration. Clear caches and verify the galbar/jsonpath library is installed.
Security Notes 6
- External data sources may contain untrusted content that could compromise site security if not properly filtered
- Administrators with 'administer external entity types' permission can access system files and database credentials - grant this permission only to trusted users
- Always validate and sanitize data from external sources, especially when displaying user-generated content
- Configure storage clients with read-only mode when write access to external systems is not needed
- Use secure connections (HTTPS) for REST API endpoints when transmitting sensitive data
- Be cautious with SQL storage clients as they can execute arbitrary queries on configured databases