Search API Attachments
Extrae contenido de texto de archivos adjuntos y lo indexa con Search API, permitiendo búsqueda de texto completo dentro de documentos cargados.
search_api_attachments
Install
composer require 'drupal/search_api_attachments:^10.0'
Overview
Search API Attachments extiende el módulo Search API extrayendo contenido de texto de archivos adjuntos y haciéndolo buscable. El módulo soporta la extracción de texto de varios formatos de documentos incluyendo PDF, documentos de Microsoft Office y muchos otros tipos de archivos.
El módulo proporciona múltiples métodos de extracción para adaptarse a diferentes entornos de servidor: Apache Tika (aplicación JAR o modo servidor), capacidades de extracción integradas de Solr, herramienta de línea de comandos pdftotext, biblioteca Python pdf2txt y el extractor docconv basado en Go. Cada método tiene sus propios requisitos de configuración y formatos de archivo soportados.
Una vez configurado, el módulo añade un procesador de Search API que automáticamente extrae texto de campos de archivo y referencias de entidades de medios durante la indexación. El contenido extraído se almacena en caché para mejorar el rendimiento en operaciones de índice posteriores. El módulo también proporciona un formateador de campo para mostrar el texto extraído directamente en las entidades y un filtro de Views para excluir adjuntos de las consultas de búsqueda.
Features
- Extrae contenido de texto de archivos adjuntos para indexación de Search API
- Soporta 6 métodos de extracción diferentes: Tika App JAR, Tika JAX-RS Server, Solr Extractor, Pdftotext, Python Pdf2txt y Docconv
- Indexa contenido tanto de campos File como de referencias de entidades Media
- Proporciona sistema de caché configurable con backends de almacenamiento Key Value (base de datos) o Files
- Incluye funcionalidad de prueba de extracción integrada con un archivo PDF de muestra
- Queue worker con mecanismo de reintento automático para extracciones fallidas (hasta 5 intentos)
- Formateador de campo para mostrar contenido de texto extraído en páginas de visualización de entidades
- Filtro de Views para excluir selectivamente contenido de adjuntos de las consultas de búsqueda
- Sistema de hooks para control personalizado sobre qué archivos deben indexarse
- Soporta filtrado de archivos por extensión, tipo MIME, tamaño y configuración de privacidad
- Invalidación automática de caché cuando los archivos se actualizan o eliminan
- Preserva la caché durante limpiezas de caché de todo el sitio (configurable)
- Opción para leer archivos de texto plano directamente sin herramienta de extracción
Use Cases
Búsqueda en biblioteca de documentos
Construir una biblioteca de documentos buscable donde los usuarios puedan buscar dentro de documentos PDF, archivos de Word y otros adjuntos. Crear un tipo de contenido con un campo de archivo, configurar Search API con el procesador File attachments, y crear una Vista con filtro expuesto de búsqueda de texto completo. Los usuarios pueden entonces encontrar documentos buscando texto contenido dentro de los archivos.
Gestión de activos de medios
Habilitar búsqueda dentro de documentos de medios adjuntos al contenido. Añadir un campo de media referenciando el tipo de media Documento a tu tipo de contenido, habilitar el procesador File attachments en tu índice, y añadir el campo de adjunto a la búsqueda de texto completo. Esto permite buscar tanto en el contenido como en los documentos de medios adjuntos.
Índice de archivos de medios puro
Crear una búsqueda específicamente para archivos de medios sin requerir contenido padre. Crear un índice de Search API con Media como fuente de datos, limitar al bundle Documento, habilitar el procesador File attachments, y añadir el campo de texto extraído. Construir una Vista para buscar directamente dentro del contenido de archivos de medios.
Búsqueda selectiva de adjuntos
Permitir a los usuarios elegir si incluir contenido de adjuntos en su búsqueda. Usar el filtro de Views proporcionado 'Exclude search in attachments' como filtro expuesto. Cuando está marcado, la búsqueda solo buscará en campos de contenido regulares, mejorando la precisión cuando el contenido de adjuntos no es relevante.
Procesamiento de archivos grandes con cola
Manejar extracción de archivos grandes o extractores poco fiables usando el sistema de colas. Las extracciones fallidas se ponen automáticamente en cola para reintento. Ejecutar 'drush queue-run search_api_attachments' durante cron o manualmente para procesar elementos en cola. El sistema reintenta hasta 5 veces antes de registrar un error.
Tips
- Usar Tika Server en lugar de Tika JAR para mejor rendimiento en entornos de alto volumen - el servidor puede manejar solicitudes concurrentes y evita la sobrecarga de inicio de JVM
- Establecer límites de tamaño de archivo razonables para prevenir problemas de memoria durante la extracción - archivos de más de 50MB raramente necesitan indexación de texto completo
- Habilitar 'Preserve cached extractions' para evitar re-extraer archivos después de limpiezas de caché, especialmente útil con grandes bibliotecas de documentos
- Usar la opción 'read text files directly' para archivos de texto plano para omitir llamadas innecesarias al extractor
- Monitorear la cola de extracción durante ejecuciones de cron - una cola creciente puede indicar problemas de configuración del extractor
- Para sitios solo con PDF, pdftotext es más rápido y ligero que Tika pero carece de soporte para otros formatos
- Considerar usar almacenamiento de archivos privado para archivos de caché extraídos para mantener seguro el contenido de documentos sensibles
- Probar la configuración de extracción después de cambios en el servidor ya que las rutas a ejecutables pueden cambiar
- Usar hook_search_api_attachments_indexable para excluir archivos específicos programáticamente basándose en criterios personalizados
- Añadir el filtro de Views 'Exclude search in attachments' para dar a los usuarios control sobre el alcance de la búsqueda
Technical Details
Admin Pages 1
/admin/config/search/search_api_attachments
Configurar el método de extracción de texto y opciones de caché para Search API Attachments. Esta página permite seleccionar y configurar el backend de extracción utilizado para extraer texto de archivos cargados para indexación.
Permissions 1
Hooks 3
hook_search_api_attachments_indexable
Determina si un adjunto debe ser indexado. Devuelve FALSE para evitar que un archivo específico sea indexado.
hook_search_api_attachments_content_extracted
Permite que otros módulos reaccionen después de la extracción de contenido de un archivo. Útil para activar la reindexación de entidades relacionadas.
hook_text_extractor_info_alter
Altera las definiciones de plugins de extracción de texto. Permite modificar o eliminar métodos de extracción disponibles.
Drush Commands 2
drush queue-list
Lista todas las colas incluyendo la cola search_api_attachments para ver tareas de extracción pendientes.
drush queue-run search_api_attachments
Procesa elementos en la cola search_api_attachments para reintentar extracciones fallidas.
Troubleshooting 6
Verificar que Java está instalado y accesible. Comprobar la ruta de Java en la configuración. Asegurar que la ruta del archivo JAR de Tika es correcta y el archivo existe. Intentar ejecutar el comando Java manualmente: java -jar /path/to/tika-app.jar -V
Asegurar que el procesador File attachments está habilitado en tu índice. Comprobar que los archivos no están excluidos por extensión, tamaño o configuración de privacidad. Verificar que el método de extracción está configurado y funcionando usando la función de prueba. Comprobar los permisos de archivo y que los archivos existen en disco.
Verificar que el campo de adjunto está añadido a los campos de tu índice. Asegurar que el tipo de campo está configurado como 'Fulltext'. Reindexar después de hacer cambios. Comprobar que el campo está incluido en los campos de búsqueda de texto completo de tu Vista.
Configurar la opción 'Limit size of extracted string' para restringir el tamaño del contenido extraído (p.ej., '1 MB'). Establecer 'Maximum upload size' para omitir archivos muy grandes. Considerar usar Tika Server en lugar de Tika JAR para mejor gestión de recursos.
Comprobar logs en admin/reports/dblog para errores de extracción. Verificar que el extractor sigue funcionando usando la función de prueba. Los elementos se reintentan 5 veces antes de fallo permanente. Limpiar la cola si los elementos están permanentemente atascados.
Si 'Preserve cached extractions' está habilitado, las limpiezas de caché de todo el sitio no limpiarán la caché de extracción. Usar el servicio de caché del módulo directamente o deshabilitar la opción de preservar. Cuando se cambia el backend de caché, la caché antigua se limpia automáticamente.
Security Notes 5
- El permiso 'Administer Search API Attachments' tiene acceso restringido ya que permite configurar rutas del sistema y conexiones a servicios externos
- Cuando se usa caché basada en archivos, preferir el esquema 'private' para prevenir acceso directo al contenido extraído
- El texto extraído de archivos privados puede almacenarse en base de datos o archivos públicos dependiendo de la configuración de caché - revisar las implicaciones de seguridad
- Los extractores externos (Tika Server, Solr) reciben contenido de archivos - asegurar conexiones seguras en entornos de producción
- El módulo ejecuta comandos shell para varios extractores - las rutas se validan pero asegurar el endurecimiento apropiado del servidor