詳解BoxAPIを使うまで（PHP+Box AI編） - サイエンスパーク株式会社

皆さん、Box APIを活用していますでしょうか。

今までに2度Box APIの使い方をご紹介しました。
詳解BoxAPIを使うまで(Java編) – サイエンスパーク株式会社
 詳解BoxAPIを使うまで2（次世代.NET編） – サイエンスパーク株式会社

第3弾である本記事では、Webサーバーでよく使われるPHPでのBox APIの使い方と近年Box社が推しているBox AIの使い方をご紹介します。
※Box AIは記事を作成した時点（2025年3月21日）はEnterprise plusのエディションでのみ使用できますが、今後、Business、Business Plus、Enterpriseでも利用可能となるように順次リリースするそうです。
　▶既存のBoxプランで利用可能な新しいAIエクスペリエンス – Box Support

Chat GPT や Microsoft Copilot のような様々な対話型AIが世に出ていますが、Box AIはBoxに特化した対話型AIとなります。

Box AIを使うことで、ユーザーの質問や疑問に対してBoxに保存しているファイルから独自の情報を組み合わせた回答を得ることができ、各企業に合わせた業務の効率化を図ることが出来ます。

Box AIを有効

Box AIのAPIを使用できるように、Enterprise設定でBox AIを使えるように設定します。

Boxへログインし、画面左側のメニュー一覧の「管理コンソール」をクリックします。

Box管理者専用画面に遷移するため、画面左側のメニュー一覧の「Enterprise設定」をクリックします。

画面上部タブの「Box AI」をクリックします。

「すべてのユーザーに対してBox AI for APIを無効にしました」の「構成の編集」をクリックします。

利用許諾の確認画面が表示されるので「利用規約を承諾します」にチェックを入れ、「承諾」をクリックします。

もう一度、「すべてのユーザーに対してBox AI for APIを無効にしました」の「構成の編集」をクリックします。

「すべてのユーザーに対して有効にする」にチェックを入れ、「保存」をクリックします。

「すべてのユーザーに対してBox AI for APIを有効にしました」に表示が変わっていることを確認してください。変わっていればBox AIを有効にできています。

Boxアプリ作成

第1弾、第2弾でも作成しましたが、今回もBoxアプリを作成します。
ただし今回はOAuth 2.0の認証方法とは異なり、JWTを使用した認証方法を使ったやり方を説明します。

Boxへログインし、画面左側のメニュー一覧の「開発者コンソール」をクリックします。

Box開発者専用画面に遷移するため、画面右上の「Platformアプリの作成」をクリックします。

今回も前回同様「カスタムアプリ」を使用します。

アプリ名や目的等、必須項目を入力し、「次へ」をクリックします。今回は以下の設定で作成しました。 

アプリ名：Box AI_Test 
説明(省略可)：詳解BoxAPIを使うまで3（PHP+Box AI編） 
目的：その他 
目的を入力：demo

今回は、「サーバー認証（JWT使用）」を選択し、「アプリの作成」を行います。

「Box AI Test」のアプリ設定画面に遷移するため、上部タブの「構成」をクリックします。

アプリアクセスレベルに「アプリ+Enterpriseアクセス」を選択します。

アプリケーションスコープの「AIを管理する」にチェックを入れます。

「公開/秘密キーペアを生成」をクリックします。

ローカルのダウンロードフォルダに構成ファイルがダウンロードされるのを確認したら、「OK」をクリックします。

ダウンロードされています。この構成ファイルの情報は実装時に使用するので大切に保管します。

画面上部タブの「承認」をクリックします。

「確認して送信」をクリックします。

「送信」をクリックします。

一覧に今送信したアプリの情報が表示されました。ただし、この段階ではまだアプリを使用することができません。「Boxアプリを承認」の操作を行う必要があります。

Boxアプリを承認

管理者権限のアカウントでBoxにログインします。

管理コンソールを表示し、「統合」をクリックします。

画面上部タブの「Platformアプリマネージャ」をクリックし、一覧を表示します。
一覧に[Boxアプリの作成]の「承認」タブで送信されたアプリが表示されています。

対象行の画面右側三点リーダーをクリックし、「アプリを承認」をクリックします。

「承認」をクリックします。

一覧の承認ステータスが「承認済み」、有効化ステータスが「有効」に変更されています。
これでBoxアプリの承認が完了したので、作成したアプリを使用することができます。

動作環境

Box APIの準備が完了したら、今度は動作環境を整えます。

必要な環境は以下となります。

Windows 10 22H2 Enterprise
Visual Stadio Code
PHP Version 8.x系（最新バージョン） ※ PHPでBox APIを利用するためにphp.iniでcURLを有効にします。
Composer （最新バージョン）

※これらのインストール方法は本筋から外れてしまうため、本記事では紹介しません。公式サイト等を確認し、インストールを行ってください。

BoxにもAIで引用するためのファイルをアップロードします。
今回は弊社が提供しているサービス「CL-UMP」のマニュアルをアップロードしています。

実装

Box APIを用いてBox AIを使用する実装をしていきます。
実装する内容は、ユーザーが質問した内容からBox AIを使って回答文を作成するアプリを想定しています。
今回はWeb画面を作成せず、バックエンド部のみ実装します。

今回用いたBox APIは以下となります。
質問を送信 – APIリファレンス – Box Developerドキュメント

フォルダ・ファイル構成

はじめに最終的なフォルダ・ファイル構成を紹介します。

フォルダ構成は以下となります。

デスクトップ直下に「BoxAITest」フォルダを作成します。
今回実装したファイルは以下の２ファイルです。

BoxAITest.class.php
Batch.php

composer.json、composer.lock、vendorフォルダは、依存コンポーネントです。

以下の手順でコンポーネントをインストールします。
Windowsの検索から、コマンドプロンプトを検索し実行します。

実装ファイルのフォルダパスをコピーします。

cdコマンドでコピーしたフォルダパスにカレントディレクトリを切り替え、以下のコマンドを実行します。

composer require firebase/php-jwt

php-jwtライブラリのインストールできました。これでフォルダ・ファイル構成は揃います。

実装ファイル

それぞれのファイルを見ていきます。

BoxAITest.class.php

Box APIを使用するためのクラスファイルで、このクラスの関数を呼び出してBox APIを使います。

2～3行目で、php-jwtライブラリを参照しています。

以降、各関数の実装内容を説明します。

ConnectUri()

実際にcURLで通信をする関数です。
17行目でcurlのハンドルを取得します。
34行目で20行目$queryのcurlオプションを設定します。
37行目で実際に通信します。この行を実行することで実際にリクエスト通信を行い$responseに通信のレスポンス結果が格納されます。
40行目でcurlのハンドルを破棄します。
詳しく説明はしませんが、17行目、34行目、37行目、40行目はphpでcurlを使う時に必ず必要となるおまじないと考えてください。

GetAccessToken()

Box APIで使用するアクセストークン取得をする関数です。
ダウンロードした構成ファイルに記載されている情報を用います。※ 関数呼び出し元Batch.phpから引数に渡すようにしています。
58行目で秘密キーを復号します。
61行目はアクセストークン取得先のURLを定義します。
64行目でJWT認証のペイロードを生成します。
75行目でJWTの署名をします。
78行目で$bodyにリクエスト用のパラメータを設定します。
86行目でConnectUri()の関数を利用して、認証URLへPOST通信をします。

※本実装の詳細は、Box社が提示している下記URL先をご確認ください。
SDKを使用しないJWT – Box Developerドキュメント

BoxAPI_RequestAsk()

下記Box API通信を行う関数です。

質問を送信 – APIリファレンス – Box Developerドキュメント

102行目でヘッダーの設定をしています。
アクセストークンの他に、接続先のユーザーを指定するためas-userヘッダーを含めます。

103行目～122行目でBodyの設定を行っています。
104行目～105行目で、今回引用するファイルのファイルIDを指定します。
今回引用するのは2ファイルと複数なので、104行目にmultiple_item_qaを指定します。
※単体ファイルの場合はsingle_item_qaを指定します。

105行目に次のid、typeのキーを定義したコレクション配列を渡します。
※今回は関数呼び出し元となるBatch.phpで定義しています。詳細はBatch.phpで説明します。

107行目～120行目でAIモデルをデフォルトから切り替える場合の設定をします。
※デフォルトから変更する必要がない場合は107行目～120行目は不要です。今回は紹介のため設定します。
110行目で使用するモデルを指定します。
111行目～118行目で回答の精度を調整するLLMパラメータの設定を行います。

今回はデフォルトのままにしています。※ 今回は確認できていませんが、精度が低い場合、これらのパラメータを調整して精度を上げるようです。
各パラメータの詳細は、Box社が提示している下記URLをご確認ください。
AI LLMエンドポイントパラメータ (OpenAI) – APIリファレンス – Box Developerドキュメント

121行目で、引用したファイル名と引用元の本文をレスポンスで受け取るように設定します。

Batch.php

今回のAPIの動作を確認するための実行ファイルです。

2行目でBoxAITest.class.phpのクラスを参照し、3行目で$sdkにBoxAITestクラスのオブジェクトを生成します。
$sdkのオブジェクトを通して、Box APIを使用します。

Box APIの使用は第１弾、第２弾と同様にアクセストークンを取得 → 目的のAPIを呼び出すという流れとなり、基本的に変わりありません。

OAuth2.0認証とJWT認証で大きく違う点は、アクセストークン取得時のパラメータがJWT認証用に変わることと、特定ユーザーのフォルダ情報を取得するためにas-userヘッダーなどを用いてユーザーIDを指定する必要がある点です。

※ユーザーIDを指定しない場合はサービスアカウントでのアクセスとなり、特定ユーザーのフォルダ情報を参照することができません。

以下、各行の説明をします。

6行目～11行目でBoxアプリを作成した時に保管した下記ファイルの情報を引用し、定義します。

※この情報は流出すると好きなところからアクセスできるようになってしまうため、本番では絶対にハードコーディングをしないようにしましょう。

13行目でBoxAITestクラスのGetAccessToken関数を呼び出し、$responseにアクセストークンを取得します。

18行目$promptで、検索する文字を定義します。
※本番ではUI画面を設けるなど、ユーザーが入力した文字を参照するようにした方が良いです。

20行目～29行目の$serchFilesに、AIで引用するファイルを以下の配列で定義します。

idのファイルIDは、引用するファイルのファイルIDを指定します。
typeは本記事作成時（2025/1/7時点）でfileしか対応していないようなので、固定にしています。
※Box APIの仕様上、指定できるファイル数は最大25ファイルまでのようです。配列の要素が26個以上にならないように気を付けた方が良いでしょう。

31行目$resultで、Box AI用の[質問を送信]APIを呼び出します。
引数に13行目$responseで取得したアクセストークン、as-userヘッダーに渡すユーザーID、18行目$promptの検索する文字と20行目$serchFilesの引用するファイルの情報を渡します。

38行目～45行目は、31行目$resultの実行結果をコンソール出力するようにします。
コンソールに出力する情報は、39行目で検索結果の回答を表示し、40行目～45行目のfor文で引用元ファイル名と引用元の本文を出力します。

動作確認

実行して結果を確認します。

コマンドプロンプトを起動し、cdコマンドでBatch.phpファイルが置いてあるフォルダにカレントディレクトリを変更します。

以下のコマンドを実行して、処理を実行します。

php Batch.php

色々と表示されました。パッと見Chat GPTなどで検索した時と似たような文章が表示されています。
※引用元ファイル名と引用元の本文を出力したことでかなりスクロールが長くなったので一部抜粋

下記、38行目$promptと39行目$result[‘answer’]で表示された内容

下記、43行目$citation[‘name’]と44行目$citation[‘content’]で表示された内容
これらは$result[‘citations’]の配列に含まれているので、for文で繰り返して取得します。

また、43行目$citation[‘name’]と44行目$citation[‘content’]の結果に同一ファイル内の複数の箇所を引用している場合があります。

その場合、43行目$citation[‘name’]だけを出力した場合、以下の赤枠のように同一ファイル名が表示されます。
※44行目$citation[‘content’]はコメントアウトしています。

まとめ

引用するファイル数も少なく試行回数が少ないため体感になりますが、外部に公開しない特定の業務マニュアルや手順書・仕様書などから特定の内容を検索したい、情報を整理したいといったケースで便利に使えそうです。

引用したファイルもAPIを通して取得できるため、この情報をユーザーが確認できればAIで取得した回答のエビデンスも容易に確認することができ、効率的に調べ物ができるのではないでしょうか。

最後に弊社では、下記Box APIを利用した自社サービスをご提供していますが、Box APIを利用した受託開発も行っています。

Boxを利用する上で業務上自動化したいといったお困りごとがあれば、Box APIを使うことで解決できるかもしれません。

その際は是非弊社にご相談ください。 

目次