Search API Autocomplete
Search API検索にオートコンプリート機能を追加し、ユーザーが入力中に検索候補を表示します。
search_api_autocomplete
インストール
composer require 'drupal/search_api_autocomplete:8.x-1.11'
composer require 'drupal/search_api_autocomplete:8.x-1.9'
概要
Search API Autocompleteは、Search API検索にオートコンプリート機能を追加します。ユーザーが検索フィールドに入力すると、インデックスされたデータ、過去の検索履歴、またはライブ検索結果に基づいてリアルタイムで候補が表示されます。
このモジュールはオートコンプリートの動作をきめ細かく制御でき、管理者は各検索ごとにオートコンプリートを有効化・設定できます。Viewsモジュールで作成した検索ビューやSearch API Pagesモジュールで作成した検索ページも対象となります。
検索ごとに複数のサジェスターメソッド（サジェスター）を設定でき、インデックスデータからのサーバーベースのサジェスト、ユーザーが入力中に実際の検索結果を表示するライブリザルト、高度なユースケース向けのカスタムスクリプト連携などがあります。各サジェスターは個別に重み付けと件数制限を設定できます。
検索ごとの権限設定により適切なアクセス制御が可能で、包括的な設定オプションにより候補の最大件数、入力遅延、最小文字数、結果件数の表示、自動送信の動作などをカスタマイズできます。
Features
- Search API Viewsの公開フォームの全文検索フィールドへのオートコンプリート
- Search API Pages検索フォームへのオートコンプリート
- 複数のサジェスタープラグイン：サーバーベースのサジェスト、ライブリザルト、カスタムスクリプト
- 検索ごとの設定と個別の有効/無効切り替え
- 検索ごとの最大候補件数の設定
- 候補表示前の最小入力文字数の設定
- キーストロークからサジェストリクエストまでの遅延調整
- 各候補の推定結果件数のオプション表示
- 候補選択時の自動送信機能
- サジェスターごとの重み順序と結果件数制限
- 検索ごとの権限制御によるきめ細かなアクセス管理
- オートコンプリートマッチングでの音訳（トランスリテレーション）サポート
- エンティティバンドルごとにビューモードを設定可能なライブリザルトサジェスター
- Search API Highlightプロセッサを使用したライブリザルトのハイライト表示
- パフォーマンス最適化された外部エンドポイント用のカスタムスクリプトサジェスター
- カスタムサジェスターと検索タイプ向けの拡張可能なプラグインアーキテクチャ
Use Cases
Viewsの基本的な検索オートコンプリート
Search API Viewの公開全文検索フィルターでオートコンプリートを有効にします。インデックスのAutocompleteタブに移動し、Viewの検索を有効にして、「Retrieve from server」サジェスターを選択し、保存します。ユーザーが入力すると、インデックスされたコンテンツに基づいてキーワード候補が表示されます。
ライブリザルトプレビュー
ユーザーが入力中に実際の検索結果を表示します。「Display live results」サジェスターを設定し、オプションで各コンテンツタイプのビューモードを選択します。ユーザーが入力すると、エンティティラベルまたはレンダリングされたビューモードコンテンツを含むクリック可能な結果リンクが表示されます。
複合候補戦略
複数のサジェスターを異なる重みで有効にします。例えば、キーワード候補に「Retrieve from server」（重み-10）を使用し、結果プレビューに「Display live results」（重み0）を使用します。サジェスターごとの制限を設定して、5つのキーワード候補と3つのライブリザルトを表示します。
高パフォーマンスのカスタムオートコンプリート
高トラフィックサイトでは、enable_custom_scripts設定を有効にし、検索サーバーに直接クエリを実行する軽量なPHPエンドポイントを指す「Use custom script」サジェスターを設定します。Drupalのブートストラップをバイパスして応答時間を短縮します。
検索ページのオートコンプリート
Search API Pages検索ブロックにオートコンプリートを追加します。モジュールを有効にすると、Search API Pagesでオートコンプリートが自動的に利用可能になります。関連するインデックスのAutocompleteタブから設定します。
フィールド固有のオートコンプリート
オートコンプリートの候補を特定のインデックスフィールドに制限します。サジェスター設定で「Override used fields」を選択し、候補生成に検索するフィールドのみを選択します（例：本文フィールドではなくタイトルフィールドのみ）。
Tips
- Solrバックエンド使用時は、単語補完とスペルチェック連携を改善するためにSearch API Solr Autocompleteモジュールを使用してください
- 複数のサジェスターを使用する場合は、候補タイプの良好なバランスを確保するためにサジェスターごとの制限を設定してください
- 「Display live results」サジェスターは、バックエンドが部分一致をサポートしている場合、またはHighlightプロセッサと併用する場合に最も効果的です
- 複数の全文検索フィルターを持つViewsでは、全文検索フィールドとして識別されるすべてのフィールドにオートコンプリートが追加されます
- 権限が正しく設定されていることを確認するために、異なるユーザーロールでオートコンプリートをテストしてください
- ユーザーに結果への直接ジャンプではなく検索を絞り込んでほしい場合は、ライブリザルトの「Suggest result labels as keywords」オプションを検討してください
- 遅延設定はユーザー体験とサーバー負荷のバランスを取ります - 300msが良いデフォルトですが、高トラフィックサイトでは増やしてください
Technical Details
Admin Pages 2
/admin/config/search/search-api/index/{index}/autocomplete
Search APIインデックスに関連付けられたすべての検索のオートコンプリート設定を管理する概要ページ。利用可能なすべての検索（Views、Pages）がタイプ別にグループ化されて一覧表示され、各検索のオートコンプリートを有効/無効にするチェックボックスがあります。個々の検索設定を編集したり、既存の設定を削除するリンクも提供されます。
/admin/config/search/search-api/index/{index}/autocomplete/{search}/edit
個々のオートコンプリート検索の詳細設定フォーム。サジェスタープラグインの選択と設定、オートコンプリートの動作オプションの設定、検索プラグイン固有の設定が可能です。
権限 2
Hooks 4
hook_search_api_autocomplete_suggestions_alter
オートコンプリートリクエストに対して返される候補を変更します。クライアントに送信される前に候補を追加、削除、または修正できます。
hook_search_api_autocomplete_suggester_info_alter
利用可能なサジェスタープラグイン定義を変更します。プラグインクラス、ラベル、説明、その他のプロパティを上書きできます。
hook_search_api_autocomplete_search_info_alter
利用可能な検索プラグイン定義を変更します。検索プラグインのプラグインクラスやその他のプロパティを上書きできます。
hook_search_api_autocomplete_views_fulltext_fields_alter
オートコンプリート用の全文検索フィールドとして認識されるViewsフィールドを変更します。これらのフィールドのテキスト入力にオートコンプリートが追加されます。
Troubleshooting 6
次を確認してください：1) インデックスのAutocompleteタブで検索のオートコンプリートが有効になっている、2) ユーザーに「Use autocomplete for X」権限がある、3) 少なくとも1つのサジェスターが有効で設定されている、4) 「Retrieve from server」サジェスターの場合、バックエンドがsearch_api_autocomplete機能をサポートしていることを確認、5) ブラウザコンソールでJavaScriptエラーを確認。
検索サーバーのバックエンドが「search_api_autocomplete」機能をサポートしている必要があります。バックエンドの機能サポートについてはSearch APIのドキュメントを確認してください。代替として「Display live results」サジェスターの使用を検討してください。
「遅延」設定を増やしてリクエスト頻度を下げます（例：500ms）。サジェスターごとの制限を使用することを検討してください。高トラフィックサイトでは、Drupalをバイパスするカスタムスクリプトサジェスターを実装してください。
どのフィールドが検索されているか確認してください。サジェスター設定で「Override used fields」を使用して、検索するフィールドを明示的に選択します。インデックスが最新で、期待するコンテンツが含まれていることを確認してください。
ライブリザルトサジェスターはアイテムのアクセス権を尊重します。検索インデックスに適切なアクセスチェックが設定されていることを確認してください。ユーザーがアクセスできないアイテムは候補からフィルタリングされます。
drush config:setまたは設定YAMLを直接編集して、search_api_autocomplete.settings:enable_custom_scriptsをTRUEに設定し、非表示のサジェスターを有効にしてください。
Security Notes 5
- 各オートコンプリート検索には独自の権限があります - これらの権限を確認し、適切なロールに慎重に割り当ててください
- 「Use custom script」サジェスターは通常のDrupalアクセスチェックをバイパスします - セキュリティへの影響を理解した上でのみ有効にしてください
- カスタムスクリプトエンドポイントは独自のアクセス制御と入力検証を実装する必要があります
- オートコンプリートエンドポイントは'value'キーにサニタイズされていない値を含むJSONを返します - HTMLとしてレンダリングする前に必ずエスケープしてください
- 結果件数はコンテンツの存在に関する情報を漏洩する可能性があります - 機密性の高い検索ではshow_countを無効にすることを検討してください