◆本記事の位置づけ
【記載内容】
・iPaaS（HULFT Square）× BoxをREST APIで連携する際の、Box API活用事例
【取り組んだテーマ】
・Copilot Studioから外部ナレッジソースをRAGとして活用し、AIによる回答生成
（Web検索やMicrosoft 365サービス以外のデータ活用）
※BoxのSandbox環境を用意し、ナレッジソースとしました。
Box-iPaaS-Copilot Studio間は API連携でデータ取得しています。
＜構成イメージ＞
【この記事は、全６回のうち第４回】
- １．Copilot Studio と Entra IDで、ユーザー認証情報の取得
- ２．Agent OrchestrationによるQiita投稿
- ３．Copilot×iPaaS の API連携手順
- ４．iPaaS×Box 特定ユーザの参照権限でデータ探索
- ５．Copilot Studio RAGの検証結果／LLMモデルによる出力特性比較
- ６．【Copilot専門資格】Microsoft AB-900受験記録
◆本編 :
はじめに
本記事はiPaaS（HULFT Square）× Box のAPI連携技術検証が中心となります。
今回のテーマは 「権限ベースのデータ探索」 です。
Copilot Studioのカスタムエージェントがサードパーティ製品（Box）をナレッジソースとして利用する際、誰が質問しているか に応じた参照権限制御をどう実現するか、を技術検証しました。
ポイント
Microsoft製品（SharePointなど）であれば、Copilotは標準でログインユーザーの参照権限に基づいて回答を生成します。
しかし サードパーティ製品では、その仕組みを自前で構築する必要があります。
本検証では、EntraIDの認証情報をCopilot Studio経由でHULFT Squareに橋渡しし、
BoxのAs-Userヘッダー機能を活用することで、ユーザーごとの権限統制を実現しました。
全体アーキテクチャのおさらい
Box API呼び出しフロー（HULFT Squareでの実装）
[各工程]上記Box API ①～⑤ の概要
① ユーザーリストの取得 GET /users
全体のユーザー一覧（user_id / public_name / login）を取得するAPIです。
HULFT Squareが受け取った認証情報=メールアドレス（login）を使い、
対応するユーザーIDを特定するために使用します。
GET https://api.box.com/2.0/users
利用するクエリパラメータ
| パラメータ | 説明 | 今回の利用 |
|---|---|---|
filter_term |
name または login が検索語句で始まるユーザーに絞り込み |
メールアドレス で絞り込み |
user_type |
all / managed / external でユーザー種別を絞り込み |
managed を指定 |
fields |
レスポンスに含める属性を指定 （例: id,type,name） |
id,login を指定 |
ポイント
filter_term にCopilot Studioから渡されたメールアドレスをセットすることで、
該当ユーザーの BoxユーザーID（一意の数値） を取得できます。
② As-Userヘッダーの利用
参考: https://developer.box.com/guides/authentication/oauth2/as-user
ここが「権限ベースのデータ探索」のポイントです。
OAuth 2.0アプリケーションは、As-User ヘッダーを付与することで、
指定したユーザーに成り代わってAPIを実行できます。
curl https://api.box.com/2.0/folders/0 \
-H "as-user: [USER_ID]" \
-H "authorization: Bearer [ACCESS_TOKEN]"
①で取得したユーザーIDをこのヘッダーにセットすることで、
そのユーザーが参照できるBoxコンテンツのみを対象にAPI操作が可能になります。
・HULFT Square RESTコネクター リクエストヘッダ設定例
③ コンテンツ検索 GET /search
As-Userヘッダーと組み合わせて、特定ユーザーの権限範囲内でキーワード検索を行います。
GET https://api.box.com/2.0/search?type=file&query="<検索キーワード>"
利用するクエリパラメータ
| パラメータ | 説明 | 今回の利用 |
|---|---|---|
query |
検索文字列（ファイル名・説明・ テキストコンテンツと照合） |
プロンプトから抽出した キーワード |
type |
file / folder / web_link に絞り込み |
file を指定 |
scope |
デフォルト user_content（認証ユーザーがアクセスできるコンテンツ） |
デフォルトのまま利用 |
注意:
owner_user_idsは不使用
owner_user_idsはファイルの 所有者（管理者） で絞り込むパラメータです。
今回は「閲覧権限を持つファイル探索」のため、As-Userヘッダーで制御します。
④-1 ファイル情報の取得 GET /files/:file_id
検索結果から得られた file_id を使い、ファイルの詳細情報を取得します。
GET https://api.box.com/2.0/files/{file_id}
その際、以下の「レプリゼンテーション」仕様を活用しました。
④-2 レプリゼンテーション（テキスト抽出）
参考: https://ja.developer.box.com/guides/representations/text/
レプリゼンテーションとは、Boxに保存されているファイルの代替アセットです。
PDF・サムネイル・テキスト抽出などに利用でき、今回はテキスト取得のため利用しました。
GET /files/:id に以下のパラメータ・ヘッダーを付与することで取得できます。
GET https://api.box.com/2.0/files/:file_id?fields=representations
X-Rep-Hints: [extracted_text]
・HULFT Square RESTコネクター プロパティ設定例
⑤ テキストレプリゼンテーションの取得（テキストのダウンロード）
テキストレプリゼンテーションでは、ドキュメントからプレーンテキストを抽出できます。
参考: https://developer.box.com/ja/guides/representations/text
APIのレスポンス(④-2)に、レプリゼンテーションのリスト(URL)が含まれています。
レスポンスのフィールド名：「url_template」
今回はレスポンスのURLから{+asset_path}を空の文字列に置き換え、リダイレクト実行。
⇒Boxからテキストデータが取得できました。
[結果]：テキストデータの取得確認
実際に一連のAPIを実行することで、ユーザーの参照権限を維持した状態で、
Boxに保存されたファイルのテキストデータ取得に成功しました。
・HULFT Square デザイナー設定例（一連のAPI処理フロー）
・Boxコンテンツからのテキストデータを取得（レスポンス内容を変数に格納）
レプリゼンテーション機能（[extracted_text]）を利用することで、ファイルの中身をそのままRAGのインプットテキストとして受け取れることを確認しています。
[課題]：レプリゼンテーションURLの分岐処理
検証を通じて、以下の課題が明らかになりました。
Boxレプリゼンテーションは、場合により返却されるURLの一部が可変となるため、
対応としてURLの数だけフローの分岐処理が必要になります。
| 項目 | 内容 |
|---|---|
| 課題 | レプリゼンテーションのURLパターンが事前に何種類あるか不明 |
| 今回の対応 | 検証スコープを絞り、1パターンのURLで実装・確認 |
| 今後の対応方針 | 実運用に向けて、URLパターンを網羅した分岐処理の実装が必要 |
[まとめ・考察]
| 比較 | Microsoft製品（SharePointなど） | サードパーティ製品 |
|---|---|---|
| Copilotの権限制御 |
標準で対応 （EntraIDの権限を適用） |
自前で構築が可能（本連載で検証） |
| 今回の実現方法 | - | EntraID認証情報 → HULFT Square → Box As-Userヘッダー |
今回の検証を通じて、以下の示唆が得られました。
- Copilot Studioエージェントがサードパーティ製品をナレッジソースにする場合、権限統制は設計上の重要課題となる。
- iPaaSをミドルウェアとして活用することで、認証情報の橋渡しと権限制御ロジックをノーコード/ローコードで実装できる。
- BoxのAs-Userヘッダーは、管理者権限トークンで動作しながらもエンドユーザーの権限を再現できる仕組みとして活用できる。
検証内容は以上となります。
次回は、Copilot Studio RAGのアウトプットイメージ 及び
GPT-4(OPEN AI)とCloude(Anthropic)の出力特性比較について記載予定です。
本記事をご覧いただき、ありがとうございました。