Search API Attachments
ファイル添付からテキストコンテンツを抽出し、Search APIでインデックス化することで、アップロードされたドキュメント内の全文検索を可能にします。
search_api_attachments
インストール
composer require 'drupal/search_api_attachments:^10.0'
概要
Search API Attachmentsは、ファイル添付からテキストコンテンツを抽出し、検索可能にすることでSearch APIモジュールを拡張します。このモジュールは、PDF、Microsoft Officeドキュメント、その他多くのファイル形式からテキストを抽出することをサポートしています。
モジュールは、異なるサーバー環境に対応するため、複数の抽出方法を提供しています：Apache Tika（JARアプリケーションまたはサーバーモード）、Solrの組み込み抽出機能、pdftotextコマンドラインツール、Python pdf2txtライブラリ、およびGoベースのdocconv抽出ツール。各方法にはそれぞれの設定要件とサポートされるファイル形式があります。
設定完了後、モジュールはSearch APIプロセッサを追加し、インデックス作成時にファイルフィールドとMediaエンティティ参照からテキストを自動的に抽出します。抽出されたコンテンツはキャッシュされ、後続のインデックス操作のパフォーマンスを向上させます。モジュールは、エンティティ上で抽出されたテキストを直接表示するためのフィールドフォーマッタと、検索クエリから添付ファイルを除外するためのViewsフィルタも提供します。
Features
- Search APIインデックス作成のためにファイル添付からテキストコンテンツを抽出
- 6種類の抽出方法をサポート：Tika App JAR、Tika JAX-RS Server、Solr Extractor、Pdftotext、Python Pdf2txt、Docconv
- FileフィールドとMediaエンティティ参照の両方からコンテンツをインデックス化
- Key Value（データベース）またはファイルストレージバックエンドを使用した設定可能なキャッシュシステムを提供
- サンプルPDFファイルを使用した組み込みの抽出テスト機能を搭載
- 失敗した抽出の自動リトライメカニズムを備えたキューワーカー（最大5回試行）
- エンティティ表示ページで抽出されたテキストコンテンツを表示するフィールドフォーマッタ
- 検索クエリから添付ファイルコンテンツを選択的に除外するViewsフィルタ
- どのファイルをインデックス化するかをカスタム制御するためのフックシステム
- 拡張子、MIMEタイプ、サイズ、プライバシー設定によるファイルフィルタリングをサポート
- ファイルの更新または削除時の自動キャッシュ無効化
- サイト全体のキャッシュクリア時にもキャッシュを保持（設定可能）
- 抽出ツールを使用せずにプレーンテキストファイルを直接読み取るオプション
Use Cases
ドキュメントライブラリ検索
PDFドキュメント、Wordファイル、その他の添付ファイル内を検索できる検索可能なドキュメントライブラリを構築します。ファイルフィールドを持つコンテンツタイプを作成し、File attachmentsプロセッサでSearch APIを設定し、全文検索の公開フィルタを持つViewを作成します。これにより、ユーザーはファイル内に含まれるテキストを検索してドキュメントを見つけることができます。
メディアアセット管理
コンテンツに添付されたメディアドキュメント内の検索を有効にします。コンテンツタイプにドキュメントメディアタイプを参照するメディアフィールドを追加し、インデックスでFile attachmentsプロセッサを有効にし、添付ファイルフィールドを全文検索に追加します。これにより、コンテンツと添付メディアドキュメントの両方を横断して検索できます。
純粋なメディアファイルインデックス
親コンテンツを必要とせずにメディアファイル専用の検索を作成します。データソースとしてMediaを使用するSearch APIインデックスを作成し、ドキュメントバンドルに限定し、File attachmentsプロセッサを有効にし、抽出テキストフィールドを追加します。メディアファイルの内容を直接検索するためのViewを構築します。
選択的添付ファイル検索
ユーザーが検索に添付ファイルコンテンツを含めるかどうかを選択できるようにします。提供されるViewsフィルタ「添付ファイル内の検索を除外」を公開フィルタとして使用します。チェックすると、検索は通常のコンテンツフィールドのみを対象とし、添付ファイルコンテンツが関係ない場合の精度を向上させます。
キューを使用した大容量ファイル処理
キューシステムを使用して、大容量ファイルの抽出や信頼性の低いエクストラクタを処理します。失敗した抽出は自動的に再試行のためにキューに入れられます。cronまたは手動で「drush queue-run search_api_attachments」を実行して、キュー内のアイテムを処理します。システムはエラーをログに記録する前に最大5回再試行します。
Tips
- 高負荷環境ではTika JARの代わりにTika Serverを使用してパフォーマンスを向上させてください - サーバーは同時リクエストを処理でき、JVM起動のオーバーヘッドを回避できます
- 抽出中のメモリ問題を防ぐために適切なファイルサイズ制限を設定してください - 50MBを超えるファイルは全文インデックス作成がほとんど必要ありません
- 「抽出済みキャッシュを保持」を有効にして、キャッシュクリア後のファイル再抽出を回避してください。特に大規模なドキュメントライブラリで有用です
- プレーンテキストファイルには「テキストファイルを直接読み取る」オプションを使用して、不要なエクストラクタ呼び出しをスキップしてください
- cron実行中に抽出キューを監視してください - 増え続けるキューはエクストラクタ設定の問題を示している可能性があります
- PDFのみのサイトでは、pdftotextはTikaより高速で軽量ですが、他の形式のサポートがありません
- 抽出キャッシュファイルにはプライベートファイルストレージの使用を検討して、機密ドキュメントコンテンツを安全に保ってください
- サーバー変更後は抽出設定をテストしてください。実行ファイルのパスが変更されている可能性があります
- hook_search_api_attachments_indexableを使用して、カスタム基準に基づいてプログラムで特定のファイルを除外してください
- 「添付ファイル内の検索を除外」Viewsフィルタを追加して、ユーザーに検索範囲のコントロールを提供してください
Technical Details
Admin Pages 1
/admin/config/search/search_api_attachments
Search API Attachmentsのテキスト抽出方法とキャッシュオプションを設定します。このページでは、インデックス作成のためにアップロードされたファイルからテキストを抽出するために使用する抽出バックエンドを選択・設定できます。
権限 1
Hooks 3
hook_search_api_attachments_indexable
添付ファイルをインデックス化するかどうかを決定します。特定のファイルのインデックス化を防ぐにはFALSEを返します。
hook_search_api_attachments_content_extracted
ファイルのコンテンツ抽出後に他のモジュールが反応できるようにします。関連エンティティの再インデックスをトリガーするのに便利です。
hook_text_extractor_info_alter
テキストエクストラクタプラグイン定義を変更します。利用可能な抽出方法の変更または削除を許可します。
Drush Commands 2
drush queue-list
search_api_attachmentsキューを含むすべてのキューをリスト表示し、保留中の抽出タスクを確認します。
drush queue-run search_api_attachments
search_api_attachmentsキュー内のアイテムを処理して、失敗した抽出を再試行します。
Troubleshooting 6
Javaがインストールされ、アクセス可能であることを確認してください。設定でjavaパスを確認してください。Tika JARファイルのパスが正しく、ファイルが存在することを確認してください。javaコマンドを手動で実行してみてください：java -jar /path/to/tika-app.jar -V
インデックスでFile attachmentsプロセッサが有効になっていることを確認してください。ファイルが拡張子、サイズ、またはプライバシー設定によって除外されていないか確認してください。テスト機能を使用して抽出方法が設定され動作していることを確認してください。ファイルのパーミッションとディスク上にファイルが存在することを確認してください。
添付ファイルフィールドがインデックスフィールドに追加されていることを確認してください。フィールドタイプが「Fulltext」に設定されていることを確認してください。変更後に再インデックスを実行してください。Viewの全文検索フィールドにフィールドが含まれていることを確認してください。
「抽出文字列のサイズ制限」設定を構成して、抽出コンテンツサイズを制限します（例：'1 MB'）。非常に大きなファイルをスキップするために「最大アップロードサイズ」を設定してください。リソース管理を改善するために、Tika JARの代わりにTika Serverの使用を検討してください。
admin/reports/dblogでログを確認して抽出エラーを確認してください。テスト機能を使用してエクストラクタがまだ動作していることを確認してください。アイテムは永久的な失敗の前に5回再試行されます。アイテムが永久的にスタックしている場合はキューをクリアしてください。
「抽出済みキャッシュを保持」が有効な場合、サイト全体のキャッシュクリアは抽出キャッシュをクリアしません。モジュールのキャッシュサービスを直接使用するか、保持オプションを無効にしてください。キャッシュバックエンドを変更すると、古いキャッシュは自動的にクリアされます。
Security Notes 5
- 「Search API Attachmentsを管理」権限は、システムパスと外部サービス接続の設定を許可するため、アクセス制限があります
- ファイルベースのキャッシュを使用する場合、抽出コンテンツへの直接アクセスを防ぐために「private」スキームを優先してください
- プライベートファイルから抽出されたテキストは、キャッシュ設定に応じてデータベースまたはパブリックファイルに保存される可能性があります - セキュリティへの影響を確認してください
- 外部エクストラクタ（Tika Server、Solr）はファイルコンテンツを受信します - 本番環境では安全な接続を確保してください
- モジュールはいくつかのエクストラクタでシェルコマンドを実行します - パスは検証されますが、適切なサーバーハードニングを確保してください