概要
Boxコネクタは、Box.comのクラウドストレージからファイルを取得して Fess のインデックスに登録する機能を提供します。
この機能には fess-ds-box プラグインが必要です。
前提条件
プラグインのインストールが必要です
Box開発者アカウントとアプリケーションの作成が必要です
JWT（JSON Web Token）認証の設定が必要です
プラグインのインストール
方法1: JARファイルを直接配置
# Maven Centralからダウンロード
wget https://repo1.maven.org/maven2/org/codelibs/fess/fess-ds-box/X.X.X/fess-ds-box-X.X.X.jar
# 配置
cp fess-ds-box-X.X.X.jar $FESS_HOME/app/WEB-INF/lib/
# または
cp fess-ds-box-X.X.X.jar /usr/share/fess/app/WEB-INF/lib/
方法2: 管理画面からインストール
「システム」→「プラグイン」を開く
JARファイルをアップロード
Fess を再起動
設定方法
管理画面から「クローラー」→「データストア」→「新規作成」で設定します。
基本設定
| 項目 | 設定例 |
|---|---|
| 名前 | Company Box Storage |
| ハンドラ名 | BoxDataStore |
| 有効 | オン |
パラメーター設定
JWT認証の例:
client_id=hdf8a7sd9f8a7sdf9a87sdf98a7sd
client_secret=kMN7sd8f7a9sd8f7a9sd8f7a9sd8f
public_key_id=4tg5h6j7
private_key=<YOUR_PRIVATE_KEY>
passphrase=7ba8sd9f7a9sd8f7a9sd8f7a9sd8f
enterprise_id=1923456
パラメーター一覧
認証パラメーター（必須）
| パラメーター | 必須 | 説明 |
|---|---|---|
client_id | はい | BoxアプリのクライアントID |
client_secret | はい | Boxアプリのクライアントシークレット |
public_key_id | はい | 公開鍵のID |
private_key | はい | 秘密鍵（PEM形式、改行は \n で表現） |
passphrase | はい | 秘密鍵のパスフレーズ |
enterprise_id | はい | BoxエンタープライズID |
クロールパラメーター（任意）
| パラメーター | デフォルト値 | 説明 |
|---|---|---|
max_size | 10000000 | クロール対象の最大ファイルサイズ（バイト）。デフォルトは10MB。 |
supported_mimetypes | .* | クロール対象のMIMEタイプ（正規表現）。カンマ区切りで複数指定可能。 |
include_pattern | （なし） | クロール対象に含めるURLパターン |
exclude_pattern | （なし） | クロール対象から除外するURLパターン |
number_of_threads | 1 | クロール処理のスレッド数 |
ignore_folder | true | フォルダ自体をインデックス対象外にするかどうか |
ignore_error | true | エラー発生時に処理を継続するかどうか |
filter_term | （なし） | ユーザーフィルタリング条件 |
fields | （全フィールド） | Box APIから取得するフィールドの指定 |
接続パラメーター（任意）
| パラメーター | デフォルト値 | 説明 |
|---|---|---|
base_url | https://app.box.com | Box APIのベースURL |
max_retry_count | 10 | API呼び出しの最大リトライ回数 |
proxy_host | （なし） | HTTPプロキシのホスト名 |
proxy_port | （なし） | HTTPプロキシのポート番号 |
refresh_token_interval | 3540 | トークンの更新間隔（秒）。デフォルトは59分。 |
スクリプト設定
url=file.url
title=file.name
content=file.contents
mimetype=file.mimetype
filetype=file.filetype
filename=file.name
content_length=file.size
created=file.created_at
last_modified=file.modified_at
利用可能なフィールド
主要フィールド
| フィールド | 説明 |
|---|---|
file.url | ブラウザでファイルを開くリンク |
file.contents | ファイルのテキストコンテンツ |
file.mimetype | ファイルのMIMEタイプ |
file.filetype | ファイルタイプ |
file.name | ファイル名 |
file.size | ファイルサイズ（バイト） |
file.created_at | 作成日時 |
file.modified_at | 最終更新日時 |
file.download_url | Box直接ダウンロードURL |
file.id | BoxアイテムID |
file.description | ファイルの説明 |
file.extension | ファイル拡張子 |
file.sha1 | ファイルのSHA1ハッシュ |
file.path_collection | フォルダパスのリスト |
メタデータフィールド
| フィールド | 説明 |
|---|---|
file.type | アイテムタイプ（"file"または"folder"） |
file.file_version | ファイルバージョン情報 |
file.sequence_id | シーケンスID |
file.etag | ETagハッシュ |
file.trashed_at | ゴミ箱移動日時 |
file.purged_at | 完全削除日時 |
file.content_created_at | コンテンツ作成日時 |
file.content_modified_at | コンテンツ更新日時 |
file.created_by | 作成者情報 |
file.modified_by | 更新者情報 |
file.owned_by | 所有者情報 |
file.shared_link | 共有リンク情報 |
file.parent | 親フォルダ情報 |
file.item_status | アイテムステータス |
file.version_number | バージョン番号 |
file.comment_count | コメント数 |
file.permissions | 権限情報 |
file.tags | タグ情報 |
file.lock | ロック情報 |
file.is_package | パッケージフラグ |
file.is_watermark | ウォーターマークフラグ |
file.collections | コレクション情報 |
file.representations | 表現形式情報 |
file.api | BoxファイルAPIオブジェクト（コラボレーション・権限情報取得用） |
詳細は Box File Object を参照してください。
Box認証の設定
JWT認証の設定手順
1. Box Developer Consoleでアプリケーションを作成
https://app.box.com/developers/console にアクセス:
「Create New App」をクリック
「Custom App」を選択
認証方法で「Server Authentication (with JWT)」を選択
アプリ名を入力して作成
2. アプリケーションの設定
「Configuration」タブで設定:
Application Scopes:
「Read all files and folders stored in Box」にチェック
Advanced Features:
「Generate a Public/Private Keypair」をクリック
生成されたJSONファイルをダウンロード（重要！）
App Access Level:
「App + Enterprise Access」を選択
3. エンタープライズで承認
Box管理コンソールで:
「Apps」→「Custom Apps」を開く
作成したアプリを承認
4. 認証情報の取得
ダウンロードしたJSONファイルから以下の情報を取得:
{
"boxAppSettings": {
"clientID": "hdf8a7sd...", // client_id
"clientSecret": "kMN7sd8f...", // client_secret
"appAuth": {
"publicKeyID": "4tg5h6j7", // public_key_id
"privateKey": "-----BEGIN...", // private_key
"passphrase": "7ba8sd9f..." // passphrase
}
},
"enterpriseID": "1923456" // enterprise_id
}
秘密鍵の形式
private_key は改行を \n に置き換えて1行にします:
private_key=-----BEGIN ENCRYPTED PRIVATE KEY-----\nMIIFDjBABgk...=\n-----END ENCRYPTED PRIVATE KEY-----\n
使用例
企業のBoxストレージ全体をクロール
パラメーター:
client_id=abc123def456ghi789jkl012mno345
client_secret=pqr678stu901vwx234yz567abc890
public_key_id=a1b2c3d4
private_key=-----BEGIN ENCRYPTED PRIVATE KEY-----\nMIIFDjBABgkqhkiG9w0BBQ0wOzAbBgkqhkiG9w0BBQwwDgQI...=\n-----END ENCRYPTED PRIVATE KEY-----\n
passphrase=1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p
enterprise_id=123456789
スクリプト:
url=file.url
title=file.name
content=file.contents
mimetype=file.mimetype
filetype=file.filetype
filename=file.name
content_length=file.size
created=file.created_at
last_modified=file.modified_at
特定のフォルダのみをクロール
include_pattern パラメーターでフォルダパスによるフィルタリングが可能です。
パラメーター:
client_id=abc123def456ghi789jkl012mno345
client_secret=pqr678stu901vwx234yz567abc890
public_key_id=a1b2c3d4
private_key=-----BEGIN ENCRYPTED PRIVATE KEY-----\nMIIFDjBABgkqhkiG9w0BBQ0wOzAbBgkqhkiG9w0BBQwwDgQI...=\n-----END ENCRYPTED PRIVATE KEY-----\n
passphrase=1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p
enterprise_id=123456789
include_pattern=.*Documents/Projects/.*
スクリプト:
url=file.url
title=file.name
content=file.contents
mimetype=file.mimetype
filetype=file.filetype
filename=file.name
content_length=file.size
created=file.created_at
last_modified=file.modified_at
PDFファイルのみをクロール
supported_mimetypes パラメーターでMIMEタイプによるフィルタリングが可能です。
パラメーター:
client_id=abc123def456ghi789jkl012mno345
client_secret=pqr678stu901vwx234yz567abc890
public_key_id=a1b2c3d4
private_key=-----BEGIN ENCRYPTED PRIVATE KEY-----\nMIIFDjBABgkqhkiG9w0BBQ0wOzAbBgkqhkiG9w0BBQwwDgQI...=\n-----END ENCRYPTED PRIVATE KEY-----\n
passphrase=1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p
enterprise_id=123456789
supported_mimetypes=application/pdf
スクリプト:
url=file.url
title=file.name
content=file.contents
mimetype=file.mimetype
filetype=file.filetype
filename=file.name
content_length=file.size
created=file.created_at
last_modified=file.modified_at
トラブルシューティング
認証エラー
症状: Authentication failed または Invalid grant
確認事項:
client_idとclient_secretが正しいか確認秘密鍵が正しくコピーされているか確認（改行が
\nになっているか）パスフレーズが正しいか確認
Box管理コンソールでアプリが承認されているか確認
enterprise_idが正しいか確認
秘密鍵のフォーマットエラー
症状: Invalid private key format
解決方法:
秘密鍵の改行が正しく \n に変換されているか確認:
# 正しい形式
private_key=-----BEGIN ENCRYPTED PRIVATE KEY-----\nMIIFDj...\n-----END ENCRYPTED PRIVATE KEY-----\n
# 間違った形式（実際の改行が含まれている）
private_key=-----BEGIN ENCRYPTED PRIVATE KEY-----
MIIFDj...
-----END ENCRYPTED PRIVATE KEY-----
ファイルが取得できない
症状: クロールは成功するがファイルが0件
確認事項:
Application Scopesで「Read all files and folders」が有効か確認
App Access Levelが「App + Enterprise Access」になっているか確認
Boxストレージに実際にファイルが存在するか確認
サービスアカウントに適切な権限があるか確認
大量のファイルがある場合
症状: クロールに時間がかかる、またはタイムアウトする
解決方法:
データストア設定で処理を分割:
クロール間隔を調整
複数のデータストアに分けて設定（フォルダ単位など）
number_of_threadsパラメーターでスレッド数を増やすスケジュール設定で負荷を分散
権限とアクセス制御
Boxのファイル権限を反映
注釈
現在の実装ではBoxの詳細な権限情報は取得されません。 必要に応じて role フィールドを使用してアクセス制御を設定できます。
スクリプトで権限を設定:
url=file.url
title=file.name
content=file.contents
role="{role}box-users"
mimetype=file.mimetype
filename=file.name
created=file.created_at
last_modified=file.modified_at
参考情報
データストアコネクタの概要 - データストアコネクタ概要
Dropboxコネクタ - Dropboxコネクタ
Google Workspaceコネクタ - Google Workspaceコネクタ
データストアクロール - データストア設定ガイド