カテゴリー: Fess

Fessの/api/v2/searchでファセットの数値を誤ったとき、検索結果が0件だったのか、リクエストが間違っていたのかを区別しやすくする修正を行いました。APIを利用する検索画面や連携プログラム向けの変更です。

空の検索結果からリクエストエラーへ

従来はfacet.size=abc、facet.size=0、facet.size=-1やfacet.minDocCount=xを指定すると、HTTP 200でrecord_countが0、partial=trueの応答になる場合がありました。修正後は検索を開始する前に検証し、HTTP 400のinvalid_requestとして返します。

facet.sizeは1以上の整数、facet.minDocCountは整数で指定します。facet.fieldやfacet.queryの要素数・文字列長の制限超過も、検索開始前のリクエストエラーとして扱います。

指定例と初期値

curl --get 'http://localhost:8080/api/v2/search'   --data-urlencode 'q=manual'   --data-urlencode 'facet.field=label'   --data-urlencode 'facet.size=20'   --data-urlencode 'facet.minDocCount=1'

数値を省略した場合は設定値を使います。開発版の初期値はquery.facet.fields.size=100、query.facet.fields.min_doc_count=1です。facet.sizeの上限を制御するquery.facet.fields.size.maxは1000、最小文書数の上限query.facet.fields.min_doc_count.maxは2147483647です。

上限を超える有効な数値は従来どおり上限へ調整されます。負のfacet.minDocCountも拒否する変更ではなく、検索側で0に調整されます。クライアントでは意味の分かりやすい0以上の値を指定するとよいと思います。

クライアントでの確認

HTTPステータスを確認してから検索結果を扱い、400 invalid_requestなら送信したパラメーターを見直します。特に「ファセットを出さない」という意味でfacet.size=0を送っている実装は、不要なfacet.fieldやfacet.queryを送らない形へ変更します。ファセットを要求しない場合、facet.sizeとfacet.minDocCountは読み取られません。

検索エンジンなどの障害時に空の部分的結果を返す挙動は維持されます。partial=trueを一律に入力誤りと判断しないでください。変更対象はv2 APIで、旧v1 APIや他の検索経路へ一律に適用するものではありません。num=abcやstart=abcが既定値になる挙動も今回の対象外です。

関連PR

• fess #3556

Fessの15.9開発版に、CodeLibsの検索エンジンプラグインを導入できないOpenSearch向けの種別 vanilla が追加されました。マネージドサービスなどを使う場合に、作成するインデックスと利用できる管理機能を明示できます。

初期値と使い分け

search_engine.type の初期値は default です。これはCodeLibsのanalysis-fess、analysis-extension、minhash、configsyncを導入したOpenSearchを前提にします。プラグインなしでは vanilla を指定します。aws も同じインデックス定義を使い、cloud は非推奨の別名として起動時に警告を出します。プラグインの自動判定はありません。

設定手順

DockerではFessサービスに次の環境変数を追加します。接続先URLは実際のOpenSearchに合わせてください。

SEARCH_ENGINE_HTTP_URL=http://search01:9200
SEARCH_ENGINE_TYPE=vanilla

ZIP/RPM/DEB版では fess_config.properties に search_engine.type=vanilla を指定し、Fessを再起動します。Docker以外の bin/fess.in.sh は SEARCH_ENGINE_TYPE を読み込まないため、環境変数だけで設定したつもりにならないようにします。

初回起動前に種別を決めてください。後から変更しても既存インデックスのマッピングは変わりません。独自の _aws / _cloud 定義を使っていた環境は、15.9で _vanilla が使われる点も確認します。

利用条件と制限

CodeLibsのプラグインは不要ですが、OpenSearch公式の analysis-kuromoji、analysis-nori、analysis-smartcn、opensearch-knn は必要です。起動時のプラグイン確認は不足を警告するだけで、起動継続をもって全機能の利用可能とは判断できません。

辞書管理と辞書API、辞書初期化、ドキュメントインデックスのリロード、検索結果の重複折り畳み、重複文書レポートは利用できません。休眠文書レポートは利用できます。日本語などの解析はOpenSearch標準の解析器になり、default と分割結果が異なります。ベトナム語と繁体字中国語の専用言語フィールドは空の解析器ですが、共通のcontent/titleフィールドには登録されます。

Amazon OpenSearch ServiceではOpenSearch 3.x、必要なプラグイン（Noriはオプションのパッケージ）、HTTPS、内部ユーザーのBasic認証を確認します。IAMのSigV4署名にはまだ対応していません。

関連PR

• fess #3564
• fess-docs #571
• docker-fess #92

Microsoft 365データストアのOneDriveDataStoreに、Microsoft Purviewの機密ラベルを読み取り、ラベルに応じてクロール結果を制御する変更が入りました。OneDrive、SharePointの文書ライブラリー、Microsoft 365グループのドライブで、本文を取り込まない運用や対象から外す運用を選べます。

有効化とポリシー例

初期値はsensitivity_label_enabled=falseです。データストア設定のパラメーター欄に、1行ずつ次のように設定します。

sensitivity_label_enabled=true
sensitivity_label_policy.Highly Confidential=skip
sensitivity_label_policy.Confidential=no_content;restrict:{group}legal@example.com

この例ではHighly Confidentialとその子ラベルを取り込まず、Confidentialとその子ラベルは本文を取得せず、法務グループに絞ります。indexは通常の取り込み、skipは除外、no_contentは名前などのメタデータだけの取り込み、restrictは閲覧ロールの絞り込みです。

ラベルのID、名前、親ラベル、暗号化を示す@protected、残りを表す*をルールに利用できます。複数ラベルの結果は厳しい側へ組み合わせます。ルールが不正な場合はクロールを停止するため、実際のラベルと権限を用意してから設定します。

権限と取得対象

ファイルの機密ラベル取得には既存のFiles.Read.Allを使います。ラベルの名前、親子関係、暗号化設定を読むには追加でSensitivityLabel.Readが必要です。定義を取得できない場合、基本的にはそのラベル自身のIDと*だけで一致判定します。名前や親ラベルによる規則を安全に解決できない場合は失敗ポリシーへ進みます。

初期設定の取得対象はOffice形式とPDFです。対象ファイルごとにGraphへの追加リクエストが発生します。sensitivity_label_extensionsで対象拡張子を指定できます。取得APIは古いラベルを再抽出し、Microsoft 365側のメタデータを更新する場合もあります。

制限はACLとの共通部分

restrictは既存ACL、デフォルト権限、クロール設定の権限から作るロールを狭めます。新しい閲覧権限を与える設定ではなく、共通するロールがなくなると取り込みません。Graphから暗号化ラベルの許可ユーザー一覧を取得できないため、管理者が対応するロールを指定します。グループ経由ではなく直接権限を与えたユーザーが除外される場合にも注意してください。

必要ならスクリプトでsensitivity_label=file.sensitivity_label_namesとマッピングできます。検索APIへ返す場合やフィールド検索に使う場合は、対応する追加フィールド設定も必要です。

暗号化ファイルと失敗時の扱い

定義を取得できる暗号化ラベルのファイルは、個別ルールがない場合、原則として本文なしで取り込みます。Graphが返すファイルは暗号化されたままで、本文を抽出できません。定義を取得できないとこの暗号化判定が使えない場合があります。

sensitivity_label_failure_policyの初期値skipは、ラベルを取得できないファイルを失敗URLとして記録して取り込みません。index_without_labelへ変えると取得できた情報で処理を継続するため、意図した制限を適用できない可能性があります。二重キー暗号化のファイルは423 Lockedで失敗ポリシーへ進みます。

このPRの検証はGraphの模擬応答によるもので、実テナントの検証は行われていません。変更を含むMicrosoft 365プラグインを用意し、少数のファイルでラベル・権限・失敗URLを確認してから対象を広げてください。

利用できるバージョン

Fess 15.9.0に含まれる予定の機能になります。現時点では、まだ、リリースしていないので、今後のテストで変更される可能性もあります。

関連PR

• fess-ds-microsoft365 #84