JinbaでBox文書の項目を抽出する方法

概要

• 5段階のワークフロー：Box OAuthで認証し、検索とダウンロード、REDUCTO_EXTRACT、JINBA_MODULES_CHECKER_V2の順に処理し、書き込みと記録を行います。
• 必ず考慮する制約：BOX_DOWNLOAD_FILEの上限は50 MBで、base64形式を返します。Boxにはファイルのアップロードで起動する専用機能がないため、定期実行や別の起動条件が必要です。
• 重要なポイント：Boxが扱うのはファイル操作のみであり、指定した項目の抽出と検証は、REDUCTO_EXTRACTとJINBA_MODULES_CHECKER_V2が行います。
• 本番運用前の確認：base64を復号し、明確なJSON Schemaを定義し、抽出した項目を検証します。失敗は例外ログに回し、すべての実行を記録します。
• この処理を繰り返し構築する規制業種のチームは、Jinba Flowで同じ手順をオンプレミスの統制されたワークフローにできます。

Boxに保存された文書を構造化データに変換するには、BOX_SEARCHまたはBOX_LIST_FILESでファイルを探し、BOX_DOWNLOAD_FILEで内容を取得します。次に、JSON Schemaを指定したREDUCTO_EXTRACTで名前付きの項目を抽出し、JINBA_MODULES_CHECKER_V2で検証します。検証済みの項目を出力先に書き込み、操作を記録すると、ワークフローが完成します。

五つの手順は、OAuthでBoxに接続し、対象ファイルを探してダウンロードし、REDUCTO_EXTRACTで項目を抽出し、JINBA_MODULES_CHECKER_V2で検証してから、書き込みと記録を行うことです。

Boxの自動化で適切なツールの組み合わせが必要な理由

Boxは文書を保存しますが、内容を解析するわけではありません。請求書、契約書、新規登録フォームから手動でデータを入力する組織には、繰り返しのコストがあります。構造化されたワークフローなら数秒で取得できる項目を、担当者が時間をかけて転記しています。

用途を示しているのは、Box AI Extract APIです。手作業を自動抽出に置き換えるさまざまな用途と、ステップ2で扱うファイルの制約が記載されています。

• 営業・財務：請求書の合計額、日付、取引先の情報を抽出します。顧客の契約書から主要な条件を取得し、CRMの記録を最新に保ちます。
• 法務：すべての文書を全文読まずに、秘密保持契約の特定の条項を見つけ、コンプライアンス審査に使います。
• 人事：形式の異なる履歴書から個人情報を抽出し、入社手続きを標準化します。

どの用途にも共通する制約があります。Boxのツールが扱うのはファイル操作のみです。BOX_SEARCH、BOX_LIST_FILES、BOX_DOWNLOAD_FILE、アップロードが利用可能な操作です。ファイルのアップロードをきっかけに起動する専用機能はありません。Boxを自動化するワークフローは、ファイルが届くイベントではなく、定期的または必要時に起動します。抽出ロジックを構築する前に、起動方法を計画してください。

ワークフローで使うツール

各ツールには役割が定まっています。その役割を取り違えることが、導入の失敗で最もよくある原因です。

Boxのツール（ファイルへのアクセス）：

• BOX_OAUTH：保存したシークレットを使い、Boxに対してアプリケーションを認証します。サーバー間のワークフローに推奨される方式は、Client Credentials Grant（CCG）で、利用者が対話的にログインする手順を省けます。
• BOX_SEARCH：Box環境に照会し、条件に一致するファイルを返します。
• BOX_LIST_FILES：指定したフォルダーの内容を返します。対象のファイルの場所が分かっている場合に便利です。
• BOX_DOWNLOAD_FILE：ファイルの内容をそのまま取得します。出力はbase64形式で、ファイルの上限は50 MBです。

Jinbaのツール（データの処理）：

• REDUCTO_EXTRACT：文書の内容を解析し、名前付きの項目を構造化されたJSONで返します。返す項目は、ワークフローに指定したJSON Schemaで定義します。この処理で、構造化されていない内容が照会可能なデータになります。
• JINBA_MODULES_CHECKER_V2：抽出した項目を後続のシステムに渡す前に、検証ルールを適用します。

名前付きの項目の抽出を担うのは、REDUCTO_EXTRACTであり、Boxではありません。Boxがファイルを届け、Jinbaが処理します。

Box文書から項目を抽出する手順

ステップ1 OAuthでBoxに接続する

認証では、対象環境に設定したBOX_OAUTHのシークレットを使います。サーバー間のワークフローにはClient Credentials Grantが適しています。自動化のロジックに直接書くのではなく、BOX_CLIENT_IDとBOX_CLIENT_SECRETを.envファイルに保存します。認証情報をバージョン管理の対象から外し、容易に更新できるようにします。

CCGには利用者のセッションが不要です。アプリケーションがサービスアカウントとして直接認証するため、人の操作なしで定期的または必要時に実行するBoxの自動化に適しています。

ステップ2 対象ファイルの検索とダウンロード

認証後、次のいずれかの方法で文書を探します。

• 使用するツールがBOX_SEARCHの場合は、ファイル名や内容は分かるものの、フォルダーの場所が不明な場合に適しています。検索条件を指定し、必要に応じてファイルの種類で絞り込みます。
• 使用するツールがBOX_LIST_FILESの場合は、ファイルが決まったフォルダーに届く場合に適しています。取得した一覧を順に処理し、ワークフローのロジックでファイル名やメタデータによる絞り込みを行います。

ファイルを特定したら、そのIDを指定してBOX_DOWNLOAD_FILEを呼び出します。すべてのダウンロードに二つの制約があります。

1. 上限は50 MBこの上限を超えるファイルは、本ツールで処理できません。容量の大きいファイルは例外として扱い、別途記録します。
2. base64形式返される内容はbase64形式です。REDUCTO_EXTRACTに渡す前に復号してください。符号化した内容を直接渡すと、正しく読めない出力になります。

ステップ3 名前付き項目の抽出に使うREDUCTO_EXTRACT

この処理で、文書の内容を構造化データに変換します。復号済みの内容をREDUCTO_EXTRACTに渡し、抽出する項目を定義したJSON Schemaも指定します。

スキーマは指示として機能し、項目名、想定するデータ型、必須かどうかを指定します。請求書の最小限のスキーマは次のようになります。

{
"type": "object",
"properties": {
"invoice_id": { "type": "string" },
"vendor_name": { "type": "string" },
"invoice_date": { "type": "string", "format": "date" },
"total_amount": { "type": "number" }
},
"required": ["invoice_id", "vendor_name", "total_amount"]
}

REDUCTO_EXTRACTは、見つけた値を含むJSONオブジェクトを返します。出力の品質はスキーマの明確さに直接左右されます。曖昧な項目名は曖昧な結果を生むため、可能な限り、元の文書に表示された具体的な項目名に合わせてください。

ステップ4 抽出したデータの検証

検証していない抽出結果を、本番システムに書き込んではいけません。見た目が正しい項目と、形式の検証を通過した項目は別です。

JINBA_MODULES_CHECKER_V2でルールを適用する対象は、REDUCTO_EXTRACTの出力です。文書の抽出ワークフローには、次の確認が役立ちます。

• 日付の項目がYYYY-MM-DDの形式に従っている
• 金額が正の数値になっている
• 必須項目が存在し、空の値になっていない
• メールアドレスが有効な形式に合っている

検証に失敗したレコードは、黙って破棄するのではなく、例外ログに回します。検証の失敗は、元の文書の形式が不正か、スキーマの調整が必要なことを示す手掛かりです。

ステップ5 検証済みデータの書き込みと操作の記録

レコードが検証を通過したら、構造化されたJSONを、データベースの表、CRMの記録、後続のAPI、ファイル保管先などに書き込みます。出力先は後続の業務によって異なりますが、出力の形式はどの場合も共通です。

すべての操作を記録します。各ログには、BoxのファイルID、抽出日時、検証結果、出力先への書き込み状態を含めます。コンプライアンス審査のための監査証跡と、失敗した実行を調査するための記録になります。

Box Automateは、ワークフローのロジック内の条件分岐に対応し、検証済みの内容によって出力先を変えられます。しきい値を超える請求書は上位の承認者に回し、それ以下のものは直接登録するといった処理ができます。

実用的な開始方法

実装を参照できるのは、box-metadata-extract-and-tagリポジトリです。このパターンをPythonで実装した動作例があり、Python 3.10以降が必要です。依存パッケージは次のコマンドでインストールします。

pip install -r requirements.txt

単一のファイルを抽出するには、次を実行します。

python -m src.cli run --file-id <BOX_FILE_ID>

フォルダー内の全ファイルを処理するには、次を実行します。

python -m src.cli run --folder-id <BOX_FOLDER_ID>

フォルダーモードは、一括処理に特に役立ちます。確実な実装では、ファイルごとに独立して処理し、例外も個別に捕捉します。一つの破損した文書や容量の大きい文書で、残りの処理を停止させないためです。失敗時にはファイルIDを記録し、全件を実行し直さず、対象を取得して再処理できるようにします。

本番運用前の確認事項

実際の文書でワークフローを動かす前に、次を確認してください。

• BOX_OAUTHの認証情報を、コードではなく環境のシークレットに保存していること。
• JSON Schemaがすべての必須項目と正しいデータ型を定義していること。問題のない一例だけでなく、代表的な文書のサンプルで検証してください。
• base64の復号が、内容をREDUCTO_EXTRACTに渡す前に行われていること。
• ファイル容量を確認し、50 MBを超える文書を途中で失敗させず、早い段階で検出・記録すること。
• JINBA_MODULES_CHECKER_V2のルールが、元の文書の実際のデータ形式と一致していること。
• ワークフローの定期実行または必要時の起動条件が定義されていること。Boxのファイルイベントで自動的に起動することはありません。
• 成功したものも含め、すべての実行でログを生成すること。

パラメーターの全一覧は、Box APIのリファレンスとJinbaのツールのドキュメントに記載されています。特定の文書に合わせたスキーマと検証ルールを確定する前に、両方を確認してください。

大量に実行する組織は、例外ログの傾向を確認してください。同じ項目で検証失敗が集中する場合、一度きりの抽出エラーではなく、文書テンプレートの変更を示していることがあります。

よくある質問

本記事のBox文書の抽出ワークフローとは？

五つの手順で構成されます。OAuthでBoxに接続し、対象ファイルを探してダウンロードし、REDUCTO_EXTRACTで名前付き項目を抽出し、JINBA_MODULES_CHECKER_V2で検証してから、操作を記録しつつ構造化された結果を出力先に書き込みます。

Box文書から構造化データを抽出するには？

ファイルを探すには、BOX_SEARCHまたはBOX_LIST_FILESを使います。BOX_DOWNLOAD_FILEで内容を取得してbase64を復号し、REDUCTO_EXTRACTに渡します。取得する項目を定義したJSON Schemaも指定してください。

Box文書の抽出を自動化するにはどのツールが必要ですか？

ファイルへのアクセスに使うツールは、BOX_OAUTH、BOX_SEARCH、BOX_LIST_FILES、BOX_DOWNLOAD_FILEです。加えてJinbaの処理ツールであるREDUCTO_EXTRACTで名前付き項目を抽出し、JINBA_MODULES_CHECKER_V2で検証します。

Box AI Extractだけでは構造化データにできない理由は？

Box AI Extractは抽出の用途に対応していますが、Boxツールが扱うのはファイル操作のみです。このワークフローで実際に項目単位の抽出と検証を行うのは、REDUCTO_EXTRACTとJINBA_MODULES_CHECKER_V2です。

どの場合にBOX_SEARCHを使い、BOX_LIST_FILESと使い分けますか？

使用するツールがBOX_SEARCHの場合は、ファイル名や内容が分かり、フォルダーの場所が不明なときです。BOX_LIST_FILESは、決まったフォルダーに届くファイルに対し、一覧にファイル名やメタデータの絞り込みを適用する場合に使います。

Box文書の抽出で50 MBの上限とは？

BOX_DOWNLOAD_FILEが扱えるファイル容量の上限は50 MBです。これを超えるファイルは本ワークフローで処理できないため、早い段階で検出し、例外として記録して別途扱う必要があります。

本番システムへの書き込み前に抽出項目を検証するには？

検証するのは、REDUCTO_EXTRACTの出力です。JINBA_MODULES_CHECKER_V2で、日付の形式、正の金額、必須項目の存在、有効なメール形式などのルールを適用します。検証に失敗したレコードは例外ログに回してください。

Boxにはアップロードで自動起動する専用機能がありますか？

ありません。Boxのツールはファイル操作のみを扱い、アップロードをきっかけに起動する専用機能はありません。このワークフローは定期的または必要時に起動する必要があるため、抽出ロジックを作る前に起動方法を計画してください。

Box文書から項目を抽出する際のよくあるミスは？

よくあるミスは、base64形式の内容を復号せずREDUCTO_EXTRACTに渡す、曖昧なJSON Schemaを使う、JINBA_MODULES_CHECKER_V2による検証を省く、Boxのファイルイベントで自動起動すると考えることです。

複数のBox文書を一括処理するには？

フォルダーモードでBOX_LIST_FILESを使い、ファイルを順に処理します。各ファイルを独立して扱い、例外も個別に捕捉することで、一つの破損した文書や容量の大きい文書で残りの処理を停止させないようにします。