メールマガジン

サイバーセキュリティや
ラックに関する情報をお届けします。

サービス・製品　|　
2026年9月15日

Box抽出エージェントAPIをPythonで試す～ファイルから情報を抽出する方法【準備編】

野崎佳子

メルマガ登録する

メルマガ登録する

Boxでは、文書の種類や日付などの属性情報をメタデータとしてファイルに付与し、分類や検索に利用できます。メタデータを手作業で付与する場合は、ファイルの内容を確認しながら項目ごとに値を入力する必要があり、対象ファイルが多いほど作業の負担も大きくなります。そこで活用したいのが、Box抽出エージェントAPIです。指定した項目の値をファイルから抽出し、キーと値の組み合わせで取得できるため、ファイルの内容確認や情報入力の自動化に活用できます。

本記事では、Boxを担当する社内SEや情報システム部門の方に向けて、APIを使った値の抽出を実際に試した結果をご紹介します。メタデータテンプレート、Boxアプリ、Python実行環境を準備し、まず「抽出編」でファイルから必要な値を抽出する手順をご覧いただきます。続く「付与編」では、抽出した値をメタデータとしてファイルに付与する手順を解説します。

抽出に使用する機能と利用条件
API実行の準備
さいごに

抽出に使用する機能と利用条件

今回の検証で使用する機能と、利用可能なプランについて説明します。

使用するエンドポイント

Box抽出エージェントAPIには、抽出したい内容をプロンプトで指定するPOST /2.0/ai/extractと、抽出項目をあらかじめ定義して実行するPOST /2.0/ai/extract_structuredの2種類のエンドポイントがあります。本記事では、あらかじめ定めた項目ごとに値を取得するPOST /2.0/ai/extract_structuredを使用するための準備を行います。

POST /2.0/ai/extract_structuredのリクエストでは、itemsに対象ファイルを指定します。抽出項目の定義方法は2通りあり、fieldsでリクエスト内に直接定義する方法と、metadata_templateで事前に作成したメタデータテンプレートを指定する方法があります。これらは併用できず、いずれか一方のみを使用します。

本記事では、metadata_templateによる抽出項目の指定に必要なメタデータテンプレートとテンプレートキーを準備します。指定したテンプレートに含まれる各フィールドは抽出項目として扱われ、フィールドキーと抽出結果の値の組み合わせがレスポンスとして返されます。なお、メタデータテンプレートは抽出項目の定義として参照されるものであり、対象ファイルにメタデータを付与する処理ではありません。

使用するエージェント

Box AIの抽出エージェントには、Box AI抽出エージェント（標準）とBox AI抽出エージェント（強化）があります。Boxの公式情報では、文書の特徴やページ数、抽出項目数に応じたエージェント選択の目安が示されています。本記事では、その内容を次のように整理します。

標準	50ページ以下かつ抽出項目数が20未満の文書に推奨
強化	50ページを超え、抽出項目数が20以上の長く複雑な文書に推奨

今回使用する検証用ファイルは1ページで、抽出項目数は6項目のため、Box AI抽出エージェント（標準）を使用します。

利用可能なプラン

2026年8月時点で、Boxの法人向けプランでは、Box抽出エージェントAPIをBusiness以上で利用できます。Businessでは、Box AI抽出エージェント（標準）による自由形式と構造化のエンドポイントを利用できますが、メタデータテンプレートによる抽出項目の指定には対応していません。今回の検証では、メタデータテンプレートを使用するため、Business Plus以上のプランが対象となります。

なお、Box AI APIの利用にはAI Unitsが必要です。BusinessおよびBusiness PlusにはAI Unitsが含まれていないため、別途購入が必要です。Enterprise以上のプランにはAI Unitsが毎月含まれていますが、含まれる数量を超えて利用する場合は追加購入が必要です。各プランに含まれるAI Units数は次のとおりです。

Enterprise	1,000 AI Units/月
Enterprise Plus	2,000 AI Units/月
Enterprise Advanced	20,000 AI Units/月

API実行の準備

本検証では、請求書から6項目の値を抽出します。本章では、そのために必要なメタデータテンプレートとAPI実行環境を準備します。使用する構成と実行環境は次のとおりです。

項目	使用する環境
OS	Windows
コマンド実行環境	PowerShell
Python	Python 3.11以上
SDK	Box Python SDK v10以上
その他のパッケージ	python-dotenv
認証方式	Client Credentials Grant（CCG）

メタデータテンプレートを作成する

本検証では、extract_structuredエンドポイントのリクエストで、metadata_templateに作成済みのメタデータテンプレートを指定します。そのため、API実行前にメタデータテンプレート「請求書情報」を作成します。

テンプレート名を設定する

Boxの管理コンソールで［メタデータ］を開き、［新規］を選択します。テンプレート名には「請求書情報」と入力します。この操作には、管理者権限、またはメタデータテンプレートの作成・編集を許可された共同管理者権限が必要です。

フィールドを設定する

「請求書情報」テンプレートに、次の6項目を設定し保存します。

フィールド名	フィールド形式
請求元事業者名	テキスト
請求書番号	テキスト
発行日	日付
支払期限	日付
請求金額（税込）	数字
消費税額	数字

以上で、メタデータテンプレートの作成は完了です。APIで使用するテンプレートキーは、［テンプレートキーをコピー］をクリックして取得できます。

Boxアプリを作成する

Box APIを実行するため、Boxの開発者コンソールでPlatformアプリを作成します。本記事では、ユーザーによるログイン操作を必要としないクライアント資格情報許可（Client Credentials Grant：CCG）を認証方式として使用します。

アプリの情報を設定する

①開発者コンソールで［Platformアプリ］を開き、画面右上の［新規アプリ］をクリックします。

②アプリの新規作成画面で次の項目を設定し、［作成］をクリックします。

アプリ名	Box AI Extract Test
アプリタイプ	サーバー
方法	クライアント資格情報許可

アプリの構成を設定する

［作成］をクリックすると、アプリの［構成］画面が表示されます。次の手順で設定します。

①［アプリアクセスレベル］で、［アプリアクセスのみ］が選択されていることを確認します。
②［コンテンツ操作］で、次の3項目を選択します。
Boxに格納されているすべてのファイルとフォルダの読み取り
Boxに格納されているすべてのファイルとフォルダへの書き込み
AIを管理する ※ 書き込み権限は抽出処理では使用しませんが、後続の「付与編」で抽出結果をメタデータとして付与するために選択します。
③次の項目は、初期設定から変更しません。
［管理操作］すべて未選択
［開発者操作］すべて未選択
［追加の構成］すべてオフ
［CORSドメイン］何も入力しない
④画面上部の［保存］をクリックします。
⑤画面右側の［承認］をクリックして、アプリを承認します。この操作には管理者権限が必要です。

アプリを有効化する

アプリの承認後、有効化ステータスが無効の場合は、管理コンソールで有効化します。すでに有効の場合は、次の操作は必要ありません。

①管理コンソールで［Platform］を開きます。
②［Platformアプリ］タブにある［サーバー認証アプリ］を選択します。
③対象アプリの行にある［...］をクリックし、［有効にする］を選択します。

以上で、Boxアプリの作成と有効化は完了です。

Python実行環境を準備する

作成・設定したBoxアプリをPythonから利用できるように、Python実行環境を準備します。Box APIは、ほかの言語向けSDKやHTTPリクエストからも利用できますが、本記事ではPython 3.11以上とBox Python SDK v10以上を使用します。

Box Python SDK v10は、boxsdkというパッケージ名でインストールします。Pythonコードでは、box_sdk_genから必要なクラスをインポートします。以降のコマンドは、PowerShellで実行します。

Pythonのバージョンを確認する

PowerShellを開き、次のコマンドを実行して、Pythonのバージョンを確認します。本記事では、Boxの公式クイックスタートに合わせてPython 3.11以上を使用します。

python --version

※ Pythonがインストールされていない場合は、Python公式サイトからインストールします。

作業用フォルダと仮想環境を作成する

検証で使用するPythonコードや設定ファイルをまとめて保存するため、作業用フォルダを作成します。本記事では、作業用フォルダの名前を「box-ai-extract-test」とします。また、PowerShellで仮想環境を有効化するには、スクリプトの実行が許可されている必要があります。スクリプトの実行が制限されている場合は、事前にPowerShellの実行ポリシーを変更してください。

①PowerShellで、次のコマンドを実行してユーザーフォルダへ移動します。
```
cd $HOME
```
②作業用フォルダを作成し、そのフォルダへ移動します。
```
mkdir box-ai-extract-test
cd box-ai-extract-test
```
③PowerShellの入力行が、次のように表示されることを確認します。
```
PS C:\Users\ユーザー名\box-ai-extract-test>
```
④作業用フォルダ内に、.venvという名前の仮想環境を作成します。
```
python -m venv .venv
```
⑤作成した仮想環境を有効化します。
```
.\.venv\Scripts\Activate.ps1
```
⑥仮想環境が有効になると、PowerShellの入力行の先頭に(.venv)と表示されます。
```
(.venv) PS C:\Users\ユーザー名\box-ai-extract-test>
```

必要なパッケージをインストールする

PythonからBox APIを実行するために、Box Python SDKを使用します。また、Boxアプリの認証情報などを記載した.envファイルをPythonから読み込むため、python-dotenvを使用します。

①次のコマンドを実行し、前の手順で有効化した仮想環境にboxsdkとpython-dotenvをインストールします。
```
python -m pip install "boxsdk>=10" python-dotenv
```
②インストールされたパッケージを確認します。
```
python -m pip list
```
③一覧にboxsdkとpython-dotenvが表示されることを確認します。

Boxアプリの認証情報をファイルに保存する

PythonからClient Credentials Grant（CCG）でBox APIを利用するには、クライアントID、クライアントシークレット、Enterprise IDが必要です。これらの情報はPythonコードへ直接記載せず、.envファイルに保存します。

認証情報を確認する

Boxの開発者コンソールで、作成した「Box AI Extract Test」アプリを開きます。画面右側の［アプリの詳細］で、次の情報を確認します。

［アクセス］クライアントID
［アクセス］クライアントシークレット
［プロパティ］Enterprise ID

.envファイルを作成する

①前の手順で使用したPowerShellに戻り、次のコマンドを実行し、現在の場所を確認します。
```
Get-Location
```
②次の場所が表示されることを確認します。
```
C:\Users\ユーザー名\box-ai-extract-test
```
③作業用フォルダの直下に.envファイルを作成します。
```
New-Item -Path .env -ItemType File
```
④作成した.envファイルをメモ帳で開きます。
```
notepad .env
```
⑤.envファイルに次の内容を記載し、Boxの開発者コンソールで確認した値に置き換えて保存します。
なお、.envファイルには認証情報が含まれるため、第三者と共有しないでください。
```
BOX_CLIENT_ID=(クライアントID)
BOX_CLIENT_SECRET=(クライアントシークレット)
BOX_ENTERPRISE_ID=(Enterprise ID)
```

テンプレートキーをファイルに保存する

Pythonからextract_structuredエンドポイントを実行する際にメタデータテンプレートを指定するには、テンプレートキーが必要です。この情報はPythonコードに直接記載せず、作成した.envファイルに保存します。

①Boxの管理コンソールでメタデータテンプレート「請求書情報」を開き、［テンプレートキーをコピー］をクリックします。
②PowerShellで次のコマンドを実行し、.envファイルをメモ帳で開きます。
```
notepad .env
```
③.envファイルの末尾に次の行を追加し、コピーしたテンプレートキーに置き換えて保存します。
```
BOX_METADATA_TEMPLATE_KEY=(テンプレートキー)
```

④.envファイルに保存した値を確認するため、PowerShellで次のコマンドを実行します。

python -c "from dotenv import load_dotenv; import os; load_dotenv(); print(os.getenv('BOX_METADATA_TEMPLATE_KEY'))"

⑤コピーしたテンプレートキーが表示されることを確認します。

さいごに

今回は、Box抽出エージェントAPIの実行に必要なメタデータテンプレート、Boxアプリ、Python実行環境を準備しました。次の「抽出編」では、検証用ファイルを用意し、PythonからAPIを実行します。ファイルから指定した項目をどのように抽出できるのか、実際の結果を確認してみましょう。次回もお楽しみに。