External Entities
Permite conectar y utilizar conjuntos de datos de fuentes externas como entidades nativas de Drupal a través de REST APIs, sistemas de archivos, bases de datos SQL y otros backends de almacenamiento.
external_entities
Overview
External Entities es un módulo potente que te permite conectarte a fuentes de datos externas y exponerlas como entidades nativas de Drupal. Mientras el contenido reside externamente (en servidores remotos, en archivos o en bases de datos externas), Drupal trata estas entidades como si fueran contenido interno. Esto hace posible aprovechar las características del sistema de entidades de Drupal, incluyendo configuración de visualización de campos, referencias de entidades, comentarios, alias de ruta, integración con Views y más.
El módulo proporciona una arquitectura de plugins flexible con cinco tipos de plugins: Data Aggregators para combinar múltiples fuentes, Storage Clients para conectarse a diferentes backends de datos, Field Mappers para mapear datos de origen a campos de Drupal, Property Mappers para mapear propiedades de origen a propiedades de campo, y Data Processors para transformar valores de datos. El módulo soporta anotaciones, que permiten agregar datos almacenados localmente a entidades externas, y proporciona soporte multilingüe con anulaciones de configuración específicas por idioma.
External Entities es ideal para escenarios donde necesitas mostrar datos de REST APIs externas, importar contenido de sistemas heredados, agregar datos de múltiples fuentes, o crear una vista unificada de datos distribuidos sin duplicarlos en la base de datos de Drupal.
Features
- Crear tipos de entidades externas que mapean datos remotos a entidades de Drupal con integración completa del sistema de entidades
- Conectar a REST APIs con configuración integral incluyendo autenticación, cabeceras personalizadas, limitación de consultas y caché de respuestas
- Usar archivos como entidades con soporte para extracción de metadatos de archivos y coincidencia de patrones de ruta
- Conectar a bases de datos SQL (MySQL/PostgreSQL) mediante el módulo complementario xnttsql
- Agregar datos de múltiples storage clients usando modos de agregación horizontal, vertical o por grupos
- Mapear datos de origen a campos de Drupal usando field mappers y property mappers configurables con soporte JSONPath
- Procesar valores de datos con data processors integrados para conversión booleana, formateo de fecha/hora, extracción numérica, transformación de mayúsculas/minúsculas y mapeo de valores
- Agregar anotaciones locales a entidades externas vinculándolas a entidades de contenido locales
- Soporte para configuraciones multilingües con mapeo de campos por idioma y anulaciones de storage client
- Caché de entidades con duraciones de caché configurables para mejorar el rendimiento
- Soporte de modo solo lectura para tipos de entidades externas
- Modo de depuración con registro detallado para solución de problemas
- Integración con Views mediante el módulo complementario xntt_views
- Integración con Pathauto mediante el módulo complementario external_entities_pathauto
- Soporte para campos de archivo e imagen mediante el módulo complementario xntt_file_field
Use Cases
Mostrar datos de REST API como contenido de Drupal
Conecta a REST APIs externos (por ejemplo, un catálogo de productos, feed de noticias o directorio de usuarios) y muestra los datos como contenido nativo de Drupal. Configura mapeos de Field para transformar respuestas de API en campos de Entity estructurados, aplica Views para crear listados y usa modos de visualización para un tema consistente.
Migración desde Drupal 7
Usa el cliente de almacenamiento JSON:API o REST para conectar a un sitio Drupal 7 que ejecute RESTful Web Services. Muestra contenido de D7 en Drupal 10/11 durante la migración, con la opción de usar External Entity Manager para importar y sincronizar datos físicamente.
Agregar datos de múltiples fuentes
Usa el Group Aggregator para combinar datos de múltiples clientes de almacenamiento. Por ejemplo, fusiona información de productos de una REST API con datos de precios de una base de datos SQL, o combina perfiles de usuarios de diferentes sistemas usando condiciones de unión.
Almacenamiento de Entity basado en archivos
Usa el cliente de almacenamiento Files para tratar archivos locales como Entity. Extrae metadatos de archivo (nombre, tamaño, fecha) y componentes de ruta como campos. Útil para gestionar bibliotecas de documentos o activos multimedia almacenados en el sistema de archivos.
Anotar contenido externo
Habilita anotaciones para agregar datos locales de Drupal (comentarios, calificaciones, etiquetas) a Entity externas. Vincula Entity externas a tipos de contenido locales y hereda campos seleccionados de la Entity de anotación para su visualización.
Contenido externo multilingüe
Configura clientes de almacenamiento o mapeos de Field específicos del idioma para recuperar contenido localizado desde diferentes endpoints de API o bases de datos según el contexto del idioma actual.
Tips
- Siempre mapea primero el campo identificador de Entity (id) - esto es requerido para cargar y listar Entity
- Usa el cliente de almacenamiento JSON:API para conectar a otros sitios Drupal ya que proporciona integración optimizada
- Habilita el modo de depuración durante el desarrollo para registrar todas las operaciones del cliente de almacenamiento e identificar problemas de mapeo
- Configura el caché persistente para producción para reducir la carga en APIs externas
- Usa la característica 'virtual group prefix' del Group Aggregator al combinar fuentes con IDs potencialmente superpuestos
- Considera la integración con Search API para Views con grandes conjuntos de datos externos para mejor rendimiento de consultas
- Bloquea las configuraciones de tipo de Entity externa creadas programáticamente para prevenir modificaciones accidentales desde la UI
- Usa el módulo xntt_file_field al mapear URLs de archivos externos para aprovechar los estilos de imagen
Technical Details
Admin Pages 3
/admin/structure/external-entity-types
Lista todos los tipos de entidad externa configurados en el sistema. Desde esta página puede añadir, editar y eliminar tipos de entidad externa, así como acceder a las operaciones de Field UI para gestionar campos y visualizaciones.
/admin/structure/external-entity-types/add
Crear un nuevo tipo de entidad externa configurando sus ajustes básicos, fuentes de almacenamiento, mapeo de campos, caché y opciones de anotación.
/admin/config/external
Página de categoría de configuración para ajustes relacionados con datos externos.
Permisos 6
Hooks 1
hook_external_entity_transform_raw_data_alter
Alterar datos sin procesar antes de mapearlos a una entidad externa
Troubleshooting 5
Asegúrate de que el campo identificador de Entity (id) esté mapeado correctamente. Verifica que el endpoint del cliente de almacenamiento sea accesible y devuelva datos válidos. Habilita el modo de depuración para registrar solicitudes y respuestas de API.
Verifica que la configuración del mapeador de propiedades use la sintaxis de ruta correcta. Para datos anidados, usa expresiones JSONPath ($.field.subfield) o notación de puntos simple (field.subfield). Revisa las configuraciones del procesador de datos si los valores necesitan transformación.
Configura el ajuste 'Número máximo de consultas por segundo' en el cliente de almacenamiento REST para respetar los límites de velocidad de la API. Habilita la limitación de consultas para rastrear y regular las solicitudes.
Habilita el caché persistente con una duración de caché apropiada. Considera usar Search API para indexar datos externos para consultas de Views. Para fuentes REST, asegúrate de que el endpoint de lista devuelva datos completos de Entity para evitar la carga individual de Entity.
Asegúrate de que los mapeos de Field requeridos (id, title) estén configurados antes de guardar. Verifica errores de validación en la configuración del cliente de almacenamiento. Limpia cachés y verifica que la biblioteca galbar/jsonpath esté instalada.
Security Notes 6
- Las fuentes de datos externas pueden contener contenido no confiable que podría comprometer la seguridad del sitio si no se filtra adecuadamente
- Los administradores con permiso 'administer external entity types' pueden acceder a archivos del sistema y credenciales de base de datos - otorga este permiso solo a usuarios de confianza
- Siempre valida y sanitiza los datos de fuentes externas, especialmente al mostrar contenido generado por usuarios
- Configura los clientes de almacenamiento con modo de solo lectura cuando no se necesita acceso de escritura a sistemas externos
- Usa conexiones seguras (HTTPS) para endpoints de REST API al transmitir datos sensibles
- Ten precaución con los clientes de almacenamiento SQL ya que pueden ejecutar consultas arbitrarias en las bases de datos configuradas