スクリプティング概要

概要

Fess では、様々な場面でスクリプトを使用してカスタムロジックを実装できます。 スクリプトを活用することで、クロール時のデータ加工、URLの変換、 スケジュールジョブの実行などを柔軟に制御できます。

対応スクリプト言語

Fess は以下のスクリプト言語をサポートしています:

言語 識別子 説明
JavaScript javascript （エイリアス: js , sai ）

Fess に標準で組み込まれているスクリプト言語で、既定のスクリプト言語（ Constants.DEFAULT_SCRIPT ）。Sai（Fess がDI XMLの式判定にも利用している、 CodeLibsによるNashornフォーク）上で動作し、スクリプトは ECMAScript 6 として実行されます。
Groovy groovy

fess-script-groovy プラグインとして提供されるスクリプト言語。 プラグインは配布物に同梱されない ため、管理画面または bin/fess-setup install plugin fess-script-groovy でのインストールが必要です。

注釈

スクリプトの設定にスクリプトタイプが記録されていない場合、そのスクリプトは Groovy として 扱われます。これは移行期間中だけの措置ではなく恒久的な仕様です。15.9より前に作成された設定は Groovy構文のスクリプトを保持したままスクリプトタイプが記録されていないため、この既定によって アップグレード後もそのまま動作し続けます。15.9以降に新規作成される設定には、明示的に スクリプトタイプ javascript が記録されます。

本ドキュメントのスクリプト例は、特に断りがない限りJavaScript構文で記述しています。 Groovy構文については Groovyスクリプトガイド を参照してください。

スクリプトの使用場面

データストア設定

データストアコネクタでは、取得したデータをインデックスフィールドにマッピングするために スクリプトを使用します。設定は フィールド名=式 の形式で1行ごとに記述し、 各行はそれぞれ独立した1つのスクリプト式として評価されます（既定の言語はJavaScript）。

url=site_url
title=name
content=description
last_modified=updated_at

データストアスクリプトで参照できる変数名は、コネクタの種類によって異なります。 たとえばCSVデータストアやJSONデータストアでは、各カラム名・フィールド名が そのまま変数として利用できます（ data のような共通の接頭辞は付きません）。 ファイル系コネクタ（Box、Google Drive、OneDrive など）では file.* 、 Slackでは message.* など、コネクタごとに接頭辞が異なります。 利用できる変数の詳細は、各データストアコネクタのドキュメントを参照してください。

注釈

データストアの各行は1つの式として評価されるため、複数行にまたがる if ブロックや、 let / const による変数宣言文は使用できません。 条件によって値を変える場合は、フィールドごとに三項演算子を使用してください （例: title=enabled === "true" ? name : null ）。クラスを参照する場合は 完全修飾名（FQCN）をインラインで記述します。

パスマッピング

パスマッピングは、クロール対象のURLを正規化・変換するための機能です。 標準では「正規表現」と「置換文字列」のペアで設定し、スクリプトではありません。 たとえば、正規表現に http:// 、置換文字列に https:// を指定すると、 URLのスキームを置き換えられます。

置換文字列の先頭が （エンジン名）: の形式になっている場合、コロンより前の部分が 実行するスクリプトエンジンの名前として解釈され、登録済みのエンジン名と一致すれば コロン以降の文字列がそのエンジンのスクリプトとして評価されます。たとえば groovy: はGroovyエンジン（ fess-script-groovy プラグインが必要）を選び、 javascript: （エイリアス js: , sai: ）はJavaScriptエンジンを選びます。 先頭部分が登録済みのスクリプトエンジン名と一致しない場合（たとえば https:// の ようにコロンの前がURLスキーム名になっている場合など）はスクリプトとしては扱われず、 文字列全体がそのまま正規表現の置換文字列として使用されます。スクリプトとして評価 される場合、そのスクリプト内では変換対象のURL文字列を表す url と、正規表現の java.util.regex.Matcher を表す matcher が利用できます。

javascript:url.replace(/http:\/\//g, "https://")

スケジュールジョブ

スケジュールジョブでは、カスタムの処理ロジックをスクリプトで記述できます。 スクリプト全体が1つのスクリプトとして評価されるため、複数行の記述や、 JavaScriptの場合は let / const による変数宣言、条件分岐なども使用できます。

return container.getComponent("crawlJob").logLevel("info").gcLogging().execute(executor);

JavaScriptでは通常、トップレベルの return 文は構文エラーになりますが、 Fess のスクリプトエンジンはスクリプトをまず式として解釈しようと試み、 それに失敗した場合にのみ文（ステートメント）のブロックとして再解釈します。 上記の例は式としては解釈できないため文ブロックとして扱われ、そのまま動作します。 詳細は JavaScriptスクリプトガイド を参照してください。

logLevel("info") などのメソッドはジョブクラス（ ExecJob とそのサブクラス）の メソッドで、メソッドチェーンで記述できます。 executor 変数については 「実行コンテキストと利用可能なオブジェクト」を参照してください。

基本的な構文

以下はJavaScriptの基本的な構文例です。コメントは // （行コメント）または /* */ （ブロックコメント）を使用します。 # で始まるコメントはJavaScriptでは 使用できない点に注意してください。

変数アクセス

// データストアのフィールド（CSV/JSONではカラム名・フィールド名でアクセス）
title

// DIコンテナからコンポーネントを取得
container.getComponent("systemHelper")

文字列操作

// 連結
title + " - " + category

// 置換（正規表現を使用。ECMAScript 6には String#replaceAll はありません）
content.replace(/old/g, "new")

// 分割
tags.split(",")

条件分岐

// 三項演算子
status === "active" ? "有効" : "無効"

// null/空の場合のデフォルト値（論理OR演算子。JavaScriptにElvis演算子はありません）
description || "説明なし"

日付操作

// 現在日時
new Date()

// フォーマット（Java相互運用はGroovyと同じ記法で利用可能）
new java.text.SimpleDateFormat("yyyy-MM-dd").format(updated_at)

実行コンテキストと利用可能なオブジェクト

スクリプト内で使用できるオブジェクトは、スクリプトを実行するコンテキストによって 異なります。 container のみがすべてのコンテキストで利用可能です。

実行コンテキスト 利用可能なオブジェクト 説明
すべてのコンテキスト container

DIコンテナ。 container.getComponent("systemHelper") や container.getComponent("fessConfig") で各コンポーネントにアクセス可能
データストアスクリプト コネクタ固有のフィールド変数

データストアから取得した各フィールドが変数として利用可能 （変数名・接頭辞はコネクタによって異なる。CSV/JSONはフィールド名がそのまま変数になる）
パスマッピング url matcher

変換対象のURL文字列と、正規表現の Matcher （置換文字列が （エンジン名）: 形式の ときのみ。前置されたエンジン名（ groovy や javascript など）が実行言語を決める）
スケジュールジョブ executor ジョブ実行インスタンス（ JobExecutor ）。ジョブのシャットダウン制御に使用

注釈

container 以外のオブジェクトは特定のコンテキストでのみ注入されます。 たとえば executor はスケジュールジョブでのみ利用可能で、データストアスクリプトや パスマッピングでは利用できません。

セキュリティ

警告

スクリプトは強力な機能を持つため、信頼できるソースからのみ使用してください。

  • スクリプトはサーバー上で実行されます

  • ファイルシステムやネットワークへのアクセスが可能です

  • 管理者権限を持つユーザーのみがスクリプトを編集できるようにしてください

  • スクリプトの実行は監査ログ（ audit.log ）に記録されます。 記録の有無は script.audit.log.enabled で制御し、デフォルトは true です。 記録されるスクリプト文字列の最大長は script.audit.log.max.length で制御し、 デフォルトは 100 文字です。

パフォーマンス

スクリプトのパフォーマンスを最適化するためのヒント:

  1. 複雑な処理を避ける: データストアスクリプトはドキュメントごとに実行されます

  2. 外部リソースへのアクセスを最小化: ネットワーク呼び出しは遅延の原因になります

  3. キャッシュを活用: 繰り返し使用する値はキャッシュを検討

デバッグ

スケジュールジョブのスクリプトでは、スクリプト全体が1つのスクリプトとして 評価されるため、ログ出力を活用してデバッグできます。 （データストアスクリプトは1行が1つの式として評価されるため、 複数行の処理は使用できません。）

const logger = org.apache.logging.log4j.LogManager.getLogger("fess.script");
logger.info("executor = {}", executor);

上記の例では fess.script という名前のロガーを使用しています。 このログを出力するには、 app/WEB-INF/classes/log4j2.xml に対応するロガー設定を 追加します。

<Logger name="fess.script" level="DEBUG"/>

また、スクリプトエンジン自体のデバッグログを有効にするには、 org.codelibs.fess.script パッケージのログレベルを DEBUG に設定します。

<Logger name="org.codelibs.fess.script" level="DEBUG"/>

参考情報