Backlogコネクタ

概要

Backlogコネクタは、Backlogスペースの課題、Wikiページ、ドキュメント、ファイルを取得して Fess のインデックスに登録する機能を提供します。 APIキーでスペースに認証します。 索引化された各文書は、そのBacklogプロジェクトのメンバーだけが検索できるように制限されます（後述の「権限」を参照）。

この機能には fess-ds-backlog プラグインが必要です。

対応コンテンツ

• 課題（コメントを含む）

• Wikiページ

• ドキュメント

• 課題、Wikiページ、ドキュメントの添付ファイル

• プロジェクトの共有ファイル

クロールは毎回フルクロールです。既定では、Backlogから消えた文書はクロール終了時に削除されず、 有効期限が切れた時点で削除されます（「削除されたコンテンツと取り消されたアクセス権」を参照）。

前提条件

1. プラグインのインストールが必要です

2. クロール専用のBacklogユーザーとそのAPIキーが必要です

3. そのユーザーを、クロール対象のすべてのプロジェクトのメンバーにする必要があります

プラグインのインストール

管理画面の「システム」→「プラグイン」からインストールするか、bin/fess-setup install plugin fess-ds-backlog を実行して Fess を再起動します。 詳細は プラグイン を参照してください。

Backlog側の設定

1. クロール専用のBacklogユーザーを作成し、そのAPIキーを発行します（「個人設定」→「API」）。 クロールには、このユーザーに見えるものがそのまま見えます。

2. クロール対象のすべてのプロジェクトにそのユーザーを追加します。コネクタは、ユーザーが参加していないプロジェクトを取得しません。 スペース管理者であっても同様です。

3. 制限のないロール（管理者または一般ユーザー）をユーザーに付与します。制限のあるロールでは、機能によってBacklogがHTTP 403を返します。 「閲覧のみ」のユーザーは課題の添付ファイルをダウンロードできず、共有ファイルをダウンロードできるのは制限のないユーザーだけです。 このような403では、コネクタはプロジェクトと機能ごとに警告を1件ログに出力し、そのプロジェクトのその機能 （課題の添付ファイル、Wikiの添付ファイル、ドキュメントの添付ファイル、共有ファイル）をスキップして、残りのクロールを続行します。

4. スペースがAPIアクセスに2段階認証を要求している場合、Backlogはエラーコード12 (RequiredMFAError)を返し、クロールは中止されます。

APIキーは Backlog-API-Key リクエストヘッダーでのみ送信されます。スクリプトには渡されず、 このコネクタがログに出力することもありません。HTTPリダイレクトには従わないため、キーがスペースのホストの外に出ることはありません。

警告

org.codelibs.curl ロガーの FINE ログを有効にしないでください。HTTPクライアントはそのレベルでリクエストヘッダーをログに出力し、 マスクするのは Authorization や Cookie のようなヘッダーだけなので、Backlog-API-Key ヘッダーがログに書き込まれます。

設定方法

管理画面から「クローラー」→「データストア」→「新規作成」で設定します。

基本設定

項目	設定例
名前	Company Backlog
ハンドラ名	BacklogDataStore
権限	（空にします。「権限」を参照）
有効	オン

パラメーター設定

api_key=**********************************************
space_url=https://example.backlog.com

パラメーター一覧

パラメーター	必須	説明
api_key	はい	BacklogのAPIキー。スクリプトには渡されず、ログにも出力されません
space_url	はい	スペースのURL（例: https://example.backlog.com）。https のみ指定でき、スキームとホストだけを指定します（末尾のスラッシュは無視されます）。未指定、不正な値、http の場合はクロールが中止されます
project_keys	いいえ	クロール対象のプロジェクトキーのカンマ区切りリスト（大文字小文字は区別しません）。空の場合は、ユーザーに見えるすべてのプロジェクトをクロールします。ユーザーに見えないキーは警告としてログに出力されます
include_archived	いいえ	アーカイブされたプロジェクトもクロールします（デフォルト: false）
include_issues	いいえ	課題を索引化します（デフォルト: true）
include_comments	いいえ	課題のコメントを課題の文書に含めます（デフォルト: true）
include_wikis	いいえ	Wikiが有効なプロジェクトで、Wikiページを索引化します（デフォルト: true）
include_documents	いいえ	ドキュメントが有効なプロジェクトで、ドキュメントを索引化します（デフォルト: true）
include_attachments	いいえ	課題、Wikiページ、ドキュメントの添付ファイルをダウンロードして索引化します（デフォルト: true）
include_shared_files	いいえ	ファイル共有が有効なプロジェクトで、共有ファイルをダウンロードして索引化します（デフォルト: true）
permission_sync	いいえ	プロジェクトの各文書に、プロジェクトメンバーごとに1つの {user} ロールを付与します（デフォルト: true）。「権限」を参照してください
default_permissions	いいえ	すべての文書に追加する権限のカンマ区切りリスト（{user}name、{group}name、{role}name）
max_file_size	いいえ	このバイト数を超えるファイルはスキップし、索引化しません（デフォルト: 10485760）
include_pattern	いいえ	backlog.url が一致する必要がある正規表現
exclude_pattern	いいえ	backlog.url が一致してはいけない正規表現。課題、Wikiページ、ドキュメントが除外されると、その添付ファイルもスキップされます
request_interval	いいえ	各APIリクエストの前に待機するミリ秒数（デフォルト: 200）
search_request_interval	いいえ	検索型リクエスト（課題一覧、Wiki一覧）の最小間隔（ミリ秒）。Backlogはクライアントに1秒以上の間隔を空けるよう求めています（デフォルト: 1000）
max_retry_count	いいえ	HTTP 429、5xx、接続失敗のリトライ回数（デフォルト: 5）
connection_timeout	いいえ	接続タイムアウト（ミリ秒、デフォルト: 10000）
read_timeout	いいえ	読み取りタイムアウト（ミリ秒、デフォルト: 30000）
ignore_error	いいえ	ダウンロードしたファイルのテキスト抽出に失敗した場合に、失敗として記録せず、空のコンテンツで索引化します（デフォルト: true）

注釈

不正な値（数値でない値、負の間隔やリトライ回数、0以下のタイムアウトや max_file_size、true / false 以外の真偽値）は、 警告をログに出力して既定値を使用します。 request_interval、search_request_interval、max_retry_count では 0 も有効です。

スクリプト設定

title=backlog.title
content=backlog.content
url=backlog.url
mimetype=backlog.mimetype
created=backlog.created
last_modified=backlog.updated
role=backlog.roles

重要

プロジェクトメンバーへの制限を有効にするには、role=backlog.roles が必須です。 指定しない場合、索引に反映されるのは、データストア設定の「権限」フィールドの値だけです。

利用可能なフィールド

すべての文書は、スクリプトから backlog オブジェクトとして参照できます。

フィールド	種別	説明
backlog.type	すべて	issue、wiki、document、attachment、file のいずれか
backlog.id	すべて	課題、Wikiページ、ドキュメント、添付ファイル、共有ファイルのBacklog上のID
backlog.project_key、backlog.project_name	すべて	プロジェクト
backlog.title	すべて	課題は [KEY-1] 件名。それ以外はページ名、ドキュメントのタイトル、ファイル名
backlog.content	すべて	課題: 説明、属性、カスタムフィールド、コメント。Wikiページ: ページの内容。ドキュメント: プレーンテキスト。添付ファイルとファイル: 抽出したテキスト
backlog.url	すべて	「URL」を参照
backlog.mimetype	すべて	課題、Wikiページ、ドキュメントは text/plain。ファイルは検出した種別
backlog.created、backlog.updated	すべて	ISO 8601形式のUTC日時（Backlogが返した場合）
backlog.created_by、backlog.updated_by	すべて	ユーザー名（Backlogが返した場合）
backlog.roles	すべて	検索ロール（「権限」を参照）
backlog.issue_key、backlog.issue_type、backlog.status、backlog.priority、backlog.assignee	課題	課題の属性（名前）
backlog.categories、backlog.milestones、backlog.versions	課題	名前のリスト
backlog.custom_fields	課題	カスタムフィールド名から値のテキストへのマップ
backlog.comments	課題	作成者: 内容 の形式のコメントテキスト（空行区切り）
backlog.tags	Wikiページ、ドキュメント	タグ名のリスト
backlog.parent_type、backlog.parent_url、backlog.parent_title	添付ファイル	添付ファイルが属する課題、Wikiページ、ドキュメント
backlog.size	添付ファイル、ファイル	ダウンロードしたバイト数
backlog.path	ファイル	共有ファイルのパス（例: /docs/spec.pdf）

URL

種別	URL
課題	{space_url}/view/{ISSUE-KEY}
Wikiページ	{space_url}/alias/wiki/{ID}
ドキュメント	{space_url}/document/{PROJECT}/{ID}
ファイル	{space_url}/file/{PROJECT}{ディレクトリ}{名前} （パスの各セグメントはパーセントエンコードされます）
添付ファイル	{親のURL}#attachment-{ID}

注釈

ドキュメントと共有ファイルのURL形式、およびドキュメントの添付ファイルのダウンロード用エンドポイントは、 実際のBacklogスペースでは確認されていません。リンクが期待したページを開かない場合でも、 文書は索引化されて検索できます。誤っているのはリンク先だけです。

権限

permission_sync=true （既定）の場合、プロジェクトのすべての文書に次のロールが付与されます:

• プロジェクトの各メンバーの mailAddress に対する {user} ロールと、userId に対する {user} ロール（空の値は除きます）。 メンバーは、どちらでも Fess にログインできます

• default_permissions の値

• データストア設定の「権限」フィールドの値

プロジェクトのメンバーを取得できない場合や、メンバーの誰も使用可能な mailAddress または userId を持たない場合は、 プロジェクト全体をスキップし、「クローラー」→「障害URL」に記録します。メンバーのロールなしで索引化されることはありません。

permission_sync=false の場合は、default_permissions と「権限」フィールドだけが適用されます。

警告

データストア設定の「権限」フィールドを空にしてください。管理画面は、このフィールドに {role}guest を初期入力しますが、 このロールは匿名の検索ユーザーを含むすべてのユーザーが持っています。そのままにすると、すべての文書のロールに加えられ、 Backlogのすべてのコンテンツが全員に検索可能になります。 permission_sync=true の場合、ゲストロールが付与されるプロジェクトごとに、コネクタは警告をログに出力します。

メンバーのロールに頼る前に、次の点に注意してください:

• メンバーの識別子は Fess のログイン名として扱われます。Backlogの userId が tanaka の場合、Fess のログイン名が tanaka である人にアクセスが許可されますが、 それが同一人物とは限りません（例: LDAPやActive Directoryのアカウント名）。mailAddress のロールにはこの問題がありません。 permission_sync は、Fess のログイン名がBacklogのユーザーIDまたはメールアドレスと一致する環境でのみ使用してください。

• ゲストロールや別のログインに対応してしまう識別子を持つメンバーは、プロジェクトとメンバーIDを示す警告を出力して無視されます。 userId が guest の場合と、バックスラッシュを含む識別子が該当します（Fess はユーザー名のバックスラッシュまでを取り除きます）。

• プロジェクトのメンバーは全員、添付ファイルや共有ファイルを含め、プロジェクトの索引化されたすべての項目を検索で見つけられます。 Backlog自体がそのメンバーにダウンロードを許可しない場合（「閲覧のみ」のユーザーは課題の添付ファイルをダウンロードできません）でも同様です。 ロールは機能単位ではなく、プロジェクト単位です。

削除されたコンテンツと取り消されたアクセス権

既定では、Fess は各文書に有効期限（全般設定の「以前のドキュメントを削除」、既定は3日）を付け、 有効期限が付いた文書はクロール終了時に削除しません。有効期限が切れた文書は、ドキュメントパージャーが削除します。そのため、既定では次のようになります:

• Backlogで削除したコンテンツは、最大で約3日間、検索できる状態で残ります

• メンバーがプロジェクトから外れても、そのメンバーは、索引化済みのプロジェクトの文書に最大で約3日間アクセスできます。 次のクロールで同じ文書が新しい文書IDで索引化され（IDにはロールのリストが含まれます）、古いロールを持つ古い文書は有効期限が切れるまで残ります。 その間、残りのメンバーには重複した検索結果が表示されます

クロール終了時にこのような文書を削除するには、データストア設定のパラメーターに keep_expires_docs=false を追加します。 Fess は、そのクロールで再索引化されなかったその設定のすべての文書を削除します。これは、クロールが到達しなかったすべての文書にも当てはまります（「エラー処理」を参照）。

使用例

特定のプロジェクトをクロール

パラメーター:

api_key=**********************************************
space_url=https://example.backlog.com
project_keys=PROJ,DOCS
include_shared_files=false

課題とWikiページのみ（添付ファイルなし）

パラメーター:

api_key=**********************************************
space_url=https://example.backlog.com
include_documents=false
include_attachments=false
include_shared_files=false

Backlogで削除した文書をクロール終了時に削除

パラメーター:

api_key=**********************************************
space_url=https://example.backlog.com
keep_expires_docs=false

エラー処理

• クロールが中止されるのは、HTTP 401、Backlogのエラーコード11 (AuthenticationError)または12 (RequiredMFAError)、 api_key または space_url の未指定や不正、プロジェクト一覧の取得失敗の場合だけです。

• HTTP 429 では、X-RateLimit-Reset ヘッダーが示す時刻まで待機してからリトライします（最大120秒。ヘッダーがない場合は60秒）。 HTTP 5xx と接続失敗では、指数バックオフ（1秒、2秒、4秒、最大60秒）でリトライします。 max_retry_count 回のリトライを使い切ると、その項目は失敗になります。

• それ以外の失敗（403、404、リトライの使い切り）は、その1項目について記録され、クロールは続行します。

• 項目の失敗によって、クロールジョブが失敗になることはありません。クロール後に、「クローラー」→「障害URL」とクローラーのログを確認してください。

• keep_expires_docs=false の場合、失敗した部分のコンテンツは再索引化されないため、そのクロールの終了時に削除されます。 失敗した一覧取得、スキップされたプロジェクト、403でスキップされた機能の配下のすべてが、失敗なしでクロールが完了するまで索引から消えます。 クロールが中止された場合も同様です。既定では、そのようなコンテンツは有効期限が切れるまで検索できる状態で残ります。

トラブルシューティング

クロールが開始時に中止される

1. api_key が正しく、このスペースのユーザー向けに発行されたものか確認します

2. space_url が、ホストだけの https URL（例: https://example.backlog.com）か確認します

3. スペースがAPIアクセスに2段階認証を要求している場合、クロールはRequiredMFAErrorで中止されます

プロジェクトが索引化されない

1. APIユーザーがそのプロジェクトのメンバーか確認します

2. permission_sync=true の場合、メンバーを取得できないプロジェクトや、メンバーの誰も使用可能なメールアドレスまたはユーザーIDを持たないプロジェクトはスキップされます。「クローラー」→「障害URL」を確認してください

3. project_keys と include_archived を確認します

添付ファイルや共有ファイルがない

制限のないロールをAPIユーザーに付与してください。HTTP 403でスキップされたプロジェクトと機能ごとに、ログに警告が1件出力されます。

参考情報

• データストアコネクタの概要 - データストアコネクタ概要

• Atlassianコネクタ - Atlassianコネクタ

• データストアクロール - データストア設定ガイド

• 障害URL - 障害URL

• プラグイン - プラグイン管理ガイド

• Backlog APIドキュメント