Backlogの課題、コメント、Wiki、ドキュメント、添付・共有ファイルをFessから検索するための実験的なデータストアが用意されています。今回のPRでは、実験的な提供であることと設定上の注意が明記され、HTTP 429後の待機を最低1秒にする改善がマージされました。
Fess本体15.9.0は正式公開済みですが、fess-ds-backlogは実環境での検証を広げている段階です。特にドキュメント・共有ファイルのURLや一部の添付取得には実スペースで未検証の項目があり、事前検証を前提として導入します。
プラグインと専用アカウントを準備する
Fess 15.9に対応するプラグインJARを管理画面の「システム」→「プラグイン」でローカルファイルとして導入するか、app/WEB-INF/plugin/へ配置して再起動します。データストア設定のハンドラーでBacklogDataStoreを選びます。
Backlogにはクロール専用ユーザーを用意し、対象プロジェクトへ参加させてAPIキーを発行します。管理者でも未参加プロジェクトをすべて取得する設定ではありません。閲覧のみ等の制限ロールでは添付や共有ファイルが403となり、該当機能がスキップされる場合があります。
Fessのパラメーターは、まず小さな1プロジェクトに限定して設定します。
api_key=REPLACE_WITH_BACKLOG_API_KEY
space_url=https://example.backlog.com
project_keys=EXAMPLE
script_type=javascript
space_urlはHTTPSのスキームとホストを指定します。対応するホストは*.backlog.com、*.backlog.jp、*.backlogtool.comです。APIキーは専用ヘッダーで送信され、リダイレクトは追跡しません。Javaのorg.codelibs.curlロガーをFINEへ上げると専用ヘッダーが記録される可能性があるため、診断時も注意してください。
スクリプトには次を設定します。権限同期には最後の行が必要です。
title=backlog.title
content=backlog.content
url=backlog.url
mimetype=backlog.mimetype
created=backlog.created
last_modified=backlog.updated
role=backlog.roles
データストアのスクリプト種類が未設定だとGroovyになります。Groovyは15.9本体に同梱されないため、この例ではscript_type=javascriptを明示しています。
初期値と所要時間を確認する
| パラメーター | 初期値 |
|---|---|
project_keys | 空（APIユーザーが参照できる全プロジェクト） |
include_archived | false |
include_issues / include_comments / include_wikis | true |
include_documents / include_attachments / include_shared_files | true |
permission_sync | true |
default_permissions | 空 |
max_file_size | 10485760バイト |
request_interval | 200ミリ秒 |
search_request_interval | 1000ミリ秒 |
max_retry_count | 5 |
毎回全件クロールします。課題ごとにコメント取得があるため、10万件なら200ミリ秒の待機だけでも約5.5時間かかり、実際には一覧・添付取得等の時間が加わります。レート制限はAPIキー単位ではなくユーザー単位で共有されるため、同じユーザーの別処理も考慮します。
429ではX-RateLimit-Resetに従って1〜120秒待機し、ヘッダーがなければ60秒待機します。今回の修正は、サーバー時刻との差等でリセット時刻が過去になっても再試行を即座に使い切らないためのものです。
プロジェクト権限を検索へ反映する
permission_sync=trueでは、プロジェクトメンバーのメールアドレスとユーザーIDから{user}権限を作ります。Fessのログイン名がBacklogの識別子に対応していることが前提です。別人が同じログイン名を持つ環境では、そのまま対応付けてはいけません。
Fess管理画面の「アクセス権限」に初期入力される{role}guestは削除してください。これを残すと同期した権限へ追加され、匿名検索を含む全員が検索できる構成になります。role=backlog.rolesも忘れず設定します。
検索権限はプロジェクト単位です。Backlogで添付をダウンロードできない閲覧専用メンバーでも、Fess側では同プロジェクトの取得済み添付を検索できる場合があります。元サービスの機能別権限まで再現するものではありません。メンバー取得に失敗したプロジェクトは権限なしで登録せず、スキップして失敗URLへ記録します。
削除とメンバー変更は即時反映とは限らない
標準では文書に有効期限が付き、初期値3日で期限切れ後に削除されます。元データを削除した場合やメンバーが脱退した場合も、古い権限の文書が約3日残る可能性があります。権限を含む文書IDが変わるため、残ったメンバーには重複結果が見える場合もあります。
クロール終了時に未再登録文書を削除したい場合は、次を検討します。
keep_expires_docs=false
ただし、途中の403、一覧取得失敗、プロジェクトのスキップ、中断でも到達できなかった既存文書が削除対象になります。即時削除を優先するか、一時障害中も結果を保持するかを決めて設定してください。
失敗項目があってもジョブ全体は成功する場合があります。「クローラー」→「失敗URL」とfess-crawler.log、利用者ごとの検索結果、結果リンクの遷移を確認します。未知の共有ファイル種別は警告を出してスキップします。まず課題・Wikiなどの小さな範囲で、権限と更新・削除の動作まで検証するのがよいでしょう。