Microsoft 365 Copilot Retrieval APIは、SharePoint、OneDrive、Copilot connectorsにある社内データを、独自AIアプリやカスタムエージェントの回答根拠として安全に使うためのAPIです。結論から言うと、社内RAGを作るために文書を別のベクトルDBへ複製し、権限管理やインデックス更新を自前で作り込む負担を減らせる一方で、ライセンス、Microsoft Graph権限、KQLフィルター、検索対象の制限を理解せずに導入すると「結果が返らない」「想定外の範囲を検索する」「従量課金が膨らむ」といった問題が起きやすくなります。(Microsoft Learn)
本記事では、2026年5月末時点で確認できるMicrosoft公式情報をもとに、Microsoft 365 Copilot Retrieval APIの変更点、影響範囲、管理者と開発者が確認すべき設定、移行・展開時の注意点を整理します。Microsoft Learnの該当Overviewページ自体は最終更新日として2026年1月23日が表示されており、Microsoft 365 Copilot拡張機能のWhat’s Newページは2026年5月28日更新です。導入時は、必ず公式ページの最新の更新日、プレビュー表記、価格、利用条件を確認してください。(Microsoft Learn)
Microsoft 365 Copilot Retrieval APIで何が変わるのか
Microsoft 365 Copilot Retrieval APIの本質は、「Microsoft 365内の業務データを、AI回答の根拠として取り出すレイヤー」をMicrosoft Graph経由で使えるようにすることです。APIは、Microsoft 365 Copilotを支えるハイブリッドインデックスから関連するテキストチャンクを返し、生成AIソリューションの回答をSharePoint、OneDrive、Copilot connectorsのデータでグラウンディングできます。(Microsoft Learn)
従来の社内RAGでは、SharePointやファイルサーバーのデータを収集し、分割し、ベクトル化し、権限情報を同期し、検索インデックスを維持する必要がありました。Retrieval APIを使うと、このうち「検索・取得・権限を考慮した根拠データの取り出し」をMicrosoft 365側の仕組みに寄せられます。
| 観点 | 従来の社内RAGで発生しがちな作業 | Retrieval APIを使う場合の考え方 |
|---|---|---|
| データ収集 | SharePointや外部システムからデータを定期取得する | Microsoft 365 Copilotのインデックスから関連テキストを取得する |
| インデックス | 文書分割、埋め込み生成、再インデックスを自前で管理する | 別インデックスを作らず、Microsoft 365側の検索基盤を活用する |
| 権限管理 | ユーザーごとのアクセス権を検索結果に反映する実装が必要 | Microsoft 365のアクセス制御やガバナンスを尊重して結果を返す |
| 鮮度 | 同期遅延やクローラー失敗で古い情報が混ざる | データを複製せず、より新しい根拠を取得しやすい |
| 開発負荷 | 検索基盤、パーサー、ストレージ、セキュリティ設計が重い | API呼び出しとオーケストレーション設計に集中できる |
| 注意点 | 自由度は高いが運用負荷も高い | API制限、ライセンス、フィルター、検索対象の制約を理解する必要がある |
重要なのは、Retrieval APIが「AIの回答そのものを生成するAPI」ではない点です。返ってくるのは、回答生成に使うための関連テキスト、URL、メタデータなどです。アプリ側では、それらをLLMやオーケストレーターに渡し、回答文、引用表示、権限に応じたUI制御を設計する必要があります。(Microsoft Learn)
対象データソースはSharePoint、OneDrive、Copilot connectors
Retrieval APIで取得対象にできる主なデータソースは、SharePoint、OneDrive、Copilot connectorsです。リクエスト時にはdataSourceを指定し、sharePoint、oneDriveBusiness、externalItemのいずれかを使います。1回のリクエストで取得できるデータソースは1種類のみで、複数ソースを同時に混在取得する設計ではありません。(Microsoft Learn)
| dataSource | 対象 | 向いている用途 | 注意点 |
|---|---|---|---|
sharePoint | SharePointサイト、ドキュメントライブラリ、ページなど | 社内規程、業務マニュアル、プロジェクト資料、FAQ | サイトやライブラリの検索可否、共有権限、機密情報の混在に注意 |
oneDriveBusiness | ユーザーのOneDrive for Business上のファイル | 個人作業ファイルを含む文脈検索、個人業務支援 | 従量課金プレビューではOneDriveのようなユーザーレベルデータソースは対象外 |
externalItem | Copilot connectors経由の外部データ | サービスデスク、ナレッジベース、業務システム由来の情報検索 | コネクターのスキーマ、queryable属性、接続IDの設計が重要 |
たとえば、ITヘルプデスク向けのAIアシスタントなら、SharePoint上の社内手順書と、Copilot connectors経由で取り込んだ外部ナレッジを別々に検索し、アプリ側で結果を統合して回答を作る構成が現実的です。複数のデータソースを扱う場合は、Microsoft Graphのバッチリクエストを使って複数リクエストをまとめる設計も検討できます。公式例では、Retrieval APIのバッチリクエストは最大20リクエストまでサポートされています。(Microsoft Learn)
管理者がまず確認すべき影響範囲
Microsoft 365 Copilot Retrieval APIの導入で、管理者が最初に見るべきポイントは「ライセンス」「権限」「検索可能性」「情報保護」「課金」の5つです。APIがMicrosoft 365の既存のアクセス制御を尊重するとはいえ、共有設定が広すぎるサイトや、検索対象にすべきでない文書が残っている環境では、その状態がAI検索にも影響します。
| 確認項目 | 管理者が見るべき内容 | 放置した場合のリスク |
|---|---|---|
| ライセンス | Microsoft 365 Copilotアドオンライセンスの有無、従量課金の利用可否 | 想定したユーザーでAPIが使えない、または課金設計が曖昧になる |
| Graph権限 | Files.Read.All、Sites.Read.All、ExternalItem.Read.Allの同意範囲 | 過剰な同意、監査不足、アプリの利用範囲拡大 |
| 検索可能性 | SharePointサイトやライブラリが検索対象になっているか | 存在する文書がRetrieval APIで返らない |
| 共有設定 | 「組織内の全員」リンク、広すぎるグループ、継承権限 | ユーザーが見られる範囲が広がり、AI回答にも反映される |
| 情報保護 | Purview DLP、秘密度ラベル、保持・削除ポリシー | 古い機密文書や不要なデータが検索対象に残る |
| 従量課金 | Pay-as-you-goの有効化、Azureサブスクリプション、利用量監視 | 予期しないAPI利用料が発生する |
Retrieval APIは、Microsoft 365 Copilotアドオンライセンスを持つユーザーには追加料金なしで利用可能とされています。一方、Copilotアドオンライセンスを持たないユーザー向けには、SharePointやCopilot connectorsなどのテナントレベルデータソースを対象にしたPay-as-you-go消費モデルがプレビューとして提供されています。Pay-as-you-goを使うには、Azureサブスクリプション、Azureリソースグループ、Microsoft 365管理者権限、テナント内の少なくとも1つのMicrosoft 365 Copilotライセンスなどが必要です。(Microsoft Learn)
Pay-as-you-goは、Microsoft 365管理センターの「Copilot > Billing & usage > Pay-as-you-go > Microsoft 365 Copilot Retrieval API」から有効化・無効化します。公式ドキュメントでは、有効化または無効化の反映に約2時間かかる場合があり、反映後の最初のAPI呼び出しが失敗する、または無効化直後に最初の呼び出しが課金対象になる可能性があると説明されています。価格もプレビュー時点の表記であるため、本番利用前に最新の価格と条件を確認してください。(Microsoft Learn)
Microsoft Graph権限と認証で注意すべきこと
Retrieval APIはMicrosoft Graphの/copilot/retrievalとして提供され、v1.0とbetaのエンドポイントが記載されています。ただし、/beta配下のAPIは変更される可能性があり、本番アプリケーションでの利用はサポートされないと明記されています。本番設計では、まずv1.0で要件を満たせるか確認するのが基本です。(Microsoft Learn)
権限は委任権限が前提です。SharePointとOneDriveの取得にはFiles.Read.AllとSites.Read.Allの両方が必要で、Copilot connectorsの取得にはExternalItem.Read.Allが必要です。個人用Microsoftアカウントとアプリケーション権限はサポートされていません。(Microsoft Learn)
実務では、次のように設計すると監査しやすくなります。
| 設計ポイント | 推奨する確認 |
|---|---|
| 同意の範囲 | どのアプリに、誰が、どの権限を管理者同意したかを記録する |
| 条件付きアクセス | 対象アプリ、対象ユーザー、ネットワーク、デバイス条件を整理する |
| 利用ユーザー | CopilotライセンスユーザーとPay-as-you-go対象ユーザーを分けて管理する |
| 監査 | API利用ログ、アプリ登録、同意履歴、課金メトリックを定期確認する |
| マルチテナントアプリ | 外部アプリを許可する場合、同意プロセスと責任分界を明確にする |
特に、Pay-as-you-goを有効にした後は、必要なRetrieval API権限を持つテナント内のアプリが、対象ユーザーの代わりにAPIを呼び出せる状態になります。単一テナントアプリだけでなく、顧客テナント内のマルチテナントアプリも対象になり得るため、アプリ同意の棚卸しは必須です。(Microsoft Learn)
開発者が押さえるべきAPI仕様
Retrieval APIの基本リクエストは、自然言語のqueryString、検索対象を指定するdataSource、必要に応じたfilterExpressionやresourceMetadata、取得件数を制御するmaximumNumberOfResultsで構成します。queryStringは最大1,500文字で、単一の文にすること、文脈のあるキーワードのスペルミスを避けることがベストプラクティスとして示されています。(Microsoft Learn)
POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json
Authorization: Bearer {token}
{
"queryString": "2026年度の社内VPN申請手順を教えてください。",
"dataSource": "sharePoint",
"filterExpression": "path:\"https://contoso.sharepoint.com/sites/IT/\" AND FileExtension:\"docx\"",
"resourceMetadata": [
"title",
"author"
],
"maximumNumberOfResults": 10
}上記は、SharePointの特定サイト配下にあるWord文書を対象に、VPN申請手順に関係するテキストを取得する例です。実際のURL、サイト、ファイル形式、メタデータは自社環境に合わせて調整します。
| パラメーター | 役割 | 実装時の注意 |
|---|---|---|
queryString | 取得したい情報を自然言語で指定する | 汎用的な質問より、業務文脈を含む1文にする |
dataSource | sharePoint、oneDriveBusiness、externalItemを指定する | 1回のリクエストで1データソースのみ |
filterExpression | KQLで検索範囲を絞り込む | 構文ミスがあるとスコープなしで実行される点に注意 |
resourceMetadata | レスポンスに含めるメタデータを指定する | UIで出典や作成者を表示する場合に有効 |
maximumNumberOfResults | 返す結果数を指定する | 最大25件。厳しい理由がなければ絞り込みすぎない |
filterExpressionでは、SharePointやOneDriveに対してAuthor、FileExtension、Filename、FileType、InformationProtectionLabelId、LastModifiedTime、ModifiedBy、Path、SiteID、Titleなどのプロパティを利用できます。Copilot connectorsでは、コネクタースキーマでqueryableに設定されたプロパティを利用します。(Microsoft Learn)
KQLフィルターは「安全装置」として設計する
Retrieval APIのfilterExpressionは、検索精度だけでなく安全性にも影響します。たとえば法務部門向けのAIアシスタントであれば、全社SharePointを広く検索するのではなく、承認済みの法務ナレッジサイト、特定のドキュメントライブラリ、特定のファイル形式、必要に応じて秘密度ラベルで絞るほうが安全です。
{
"queryString": "取引基本契約の反社条項レビューで確認すべき観点を教えてください。",
"dataSource": "sharePoint",
"filterExpression": "path:\"https://contoso.sharepoint.com/sites/Legal/\" AND (FileType:\"docx\" OR FileType:\"pdf\")",
"resourceMetadata": [
"title",
"author"
],
"maximumNumberOfResults": 15
}失敗しやすいのは、KQLを「検索精度を上げるための任意設定」と軽く扱うことです。公式ドキュメントでは、filterExpressionのKQL構文が正しくない場合、クエリは成功するもののスコープなしで実行されると説明されています。つまり、フィルターのミスがエラーとして検出されず、意図より広い範囲を検索してしまう可能性があります。(Microsoft Learn)
実装時は、次の対策を入れてください。
| リスク | 対策 |
|---|---|
| KQL構文ミスでスコープなし検索になる | フィルター文字列をテンプレート化し、単体テストを用意する |
| サイトURLの指定ミス | 共有リンクやブラウザーのアドレスバーではなく、SharePoint/OneDriveの詳細ペインからパスを確認する |
| ファイル形式の絞り込み漏れ | FileExtensionまたはFileTypeで対象形式を明示する |
| 部門外文書の混入 | path、SiteID、秘密度ラベル、承認済みライブラリで範囲を限定する |
| Copilot connectorsの検索漏れ | コネクターの接続IDとqueryable属性を管理者・開発者で確認する |
既存RAGから移行する場合の進め方
既存の社内RAGやAzure AI Searchベースの検索基盤からRetrieval APIへ移行する場合、いきなり全面置換するのはおすすめしません。最初は「検索基盤の置き換え」ではなく、「Microsoft 365データの根拠取得レイヤーをRetrieval APIに差し替える」位置づけで進めると失敗しにくくなります。
| フェーズ | やること | 成功判定 |
|---|---|---|
| 対象業務の選定 | 社内規程、IT手順、営業資料など、根拠文書が明確な領域を選ぶ | 正解となる文書と回答例を用意できる |
| データ棚卸し | SharePointサイト、ライブラリ、OneDrive、Copilot connectorsの対象を整理する | 検索してよい範囲と除外範囲が明文化されている |
| 権限確認 | 対象ユーザーが文書にアクセスできるか確認する | 同じ質問でも権限に応じた結果差分を説明できる |
| API検証 | Graph Explorerや検証アプリでクエリを試す | retrievalHits、URL、抽出テキスト、メタデータを確認できる |
| 回答生成 | 返却されたextractをLLMに渡し、出典付き回答を生成する | 回答が根拠文書と矛盾しない |
| パイロット | 部門限定で利用し、空振りクエリや誤回答を記録する | よくある失敗パターンと改善策が見える |
| 本番展開 | 監査、課金、エラー処理、レート制限、プロンプト運用を整える | 運用担当者が障害・費用・品質を追跡できる |
既存のRAGで、すでにERPやCRMなどMicrosoft 365外の構造化データを独自インデックス化している場合は、すべてをRetrieval APIに寄せる必要はありません。Microsoft 365内の文書検索はRetrieval API、業務DBや高頻度更新の構造化データは既存検索基盤、というハイブリッド構成が現実的です。
展開前に確認したい制限事項
Retrieval APIは便利ですが、万能な検索APIではありません。特に、画像、グラフ、表、巨大ファイル、複数データソース検索、リクエスト数には制限があります。公式ドキュメントでは、現在のスロットリングや制限として、1ユーザーあたり1時間最大200リクエスト、maximumNumberOfResults最大25、非テキストコンテンツの取得非対応などが示されています。(Microsoft Learn)
| 制限・仕様 | 内容 | 実務上の注意 |
|---|---|---|
| クエリ長 | queryStringは最大1,500文字 | 長いプロンプトをそのまま渡さず、検索用クエリに要約する |
| 取得件数 | maximumNumberOfResultsは最大25 | 少なすぎると根拠不足になりやすい |
| リクエスト数 | 最大200リクエスト/ユーザー/時間 | チャットの連続質問、バッチ処理、再試行で上限に近づく |
| データソース | 1回の取得は1データソース | 複数ソースはバッチやアプリ側統合で扱う |
| 画像・グラフ | 非テキストコンテンツは非対応 | 図表の読み取りや画像内テキストには別手段が必要 |
| 表内テキスト | OneDrive/SharePointでは.doc、.docx、.pptxに限定 | ExcelやPDF内の表を前提にした検索は検証が必要 |
| 大容量ファイル | .docx、.pptx、.pdfは512MB超が非対応。その他拡張子は150MB超が非対応 | 大容量マニュアルは分割や形式見直しを検討する |
| semantic/hybrid retrieval | SharePoint/OneDriveでは.doc、.docx、.pptx、.pdf、.aspx、.oneなどが対象 | その他形式ではlexical retrievalのみになる |
| 結果なし | retrievalHitsが空なら関連結果なし | 権限、検索対象、フィルター、文書形式、インデックス状態を確認する |
なお、返却される結果やextractは順序付きではないとされており、公式ベストプラクティスでは、LLMが消費できるトークン数に厳しい要件がない限りmaximumNumberOfResultsを制限しすぎないこと、返ってきたextractをLLMまたはオーケストレーターへ送ることが推奨されています。(Microsoft Learn)
「結果が返らない」ときの確認ポイント
Retrieval API導入時に最も多いトラブルは、HTTPステータスとしては成功しているのにretrievalHitsが空になるケースです。これはAPI障害とは限りません。公式仕様上、空のretrievalHitsは関連する結果が見つからなかったことを意味します。(Microsoft Learn)
| 症状 | 確認すること |
|---|---|
| SharePoint検索では見つかるのにAPIで返らない | 呼び出しユーザーに対象文書への権限があるか、サイトが検索対象かを確認する |
| フィルターを付けると結果が消える | path、FileType、日付、秘密度ラベルIDの指定を1つずつ外して検証する |
| Copilot connectorsだけ返らない | dataSourceがexternalItemか、接続IDやqueryableプロパティが正しいか確認する |
| クエリによって結果が不安定 | 汎用的な質問を避け、業務名、文書種別、対象部門などの文脈を含める |
| 期待するPDFが返らない | ファイルサイズ、検索可能なテキストPDFか、権限、インデックス状況を確認する |
| あるユーザーだけ結果が少ない | Microsoft 365の権限トリミングが効いている可能性を確認する |
この切り分けでは、最初から複雑なフィルターを使わないことが重要です。まずdataSourceと短い業務クエリだけで取得し、次にpath、ファイル形式、日付、メタデータの順に絞り込みます。APIの問題か、権限の問題か、フィルターの問題かを分けられるように、検証ログにはリクエスト本文、呼び出しユーザー、対象サイト、レスポンス件数を残してください。
セマンティックインデックスと検索可能性の関係
Retrieval APIを正しく評価するには、Microsoft 365 Copilotのセマンティックインデックスの考え方も理解しておく必要があります。Microsoft 365 Copilotは、Microsoft Graphを利用して組織データを語彙的・意味的なインデックスにマッピングし、ユーザーの文脈に沿った情報取得を行います。セマンティックインデックスはMicrosoftによって自動的に有効化され、管理者が無効化する仕組みではありません。(Microsoft Learn)
一方で、SharePointサイトが検索対象でなければ、CopilotやRetrieval APIの検索対象として期待どおりに使えません。公式ドキュメントでは、SharePointサイトやライブラリが検索可能な状態であること、必要に応じてMicrosoft Purview DLPやSharePointサイトの検索除外を検討することが説明されています。ただし、SharePoint Onlineサイトを検索結果から除外すると、Microsoft Searchとセマンティックインデックスの両方から除外されます。片方だけを除外する選択肢ではない点に注意してください。(Microsoft Learn)
管理者は、Retrieval APIの導入前に次の順序で点検すると効率的です。
| 順序 | 点検内容 |
|---|---|
| 1 | AIに使わせたいSharePointサイトと、使わせたくないサイトを分類する |
| 2 | 検索対象にするサイトの「Search and offline availability」を確認する |
| 3 | 広すぎる共有リンク、不要な全社公開、古いグループ権限を整理する |
| 4 | 秘密度ラベル、DLP、保持・削除ポリシーの適用状況を確認する |
| 5 | 除外が必要なサイトは、Microsoft Searchとセマンティックインデックスの両方から外れる影響を確認して判断する |
利用シーン別の設計例
社内規程・人事FAQエージェント
就業規則、経費精算、休暇、リモートワーク規程などをSharePointの承認済みライブラリに集約し、pathで検索対象を限定します。回答には、規程名、更新日、URLを表示すると、利用者が原文に戻って確認できます。
失敗しやすいポイントは、古い規程やドラフト文書が同じサイトに残っていることです。ファイル名やライブラリを整理し、「公開済み」「最新版」などのメタデータ運用を決めてからAPI化すると精度が安定します。
ITヘルプデスク支援
VPN、MFA、端末交換、Microsoft Teams、Outlookなどの問い合わせに対して、SharePointの手順書とCopilot connectors経由のナレッジを検索します。SharePointとexternalItemは1回のリクエストで混在できないため、アプリ側で複数リクエストを実行し、出典ごとに統合します。
この用途では、回答の末尾に「参照した手順書」と「最終更新日」を表示する設計が有効です。利用者が古い手順で操作してしまうリスクを下げられます。
法務・監査・コンプライアンス支援
契約書レビュー、監査手順、社内ポリシー確認では、検索対象を特定サイトや特定ライブラリに絞るだけでなく、秘密度ラベルやファイル形式でも範囲を制御します。InformationProtectionLabelIdによるフィルターは、特定の情報保護ラベルを持つ文書に絞りたい場合に検討できます。(Microsoft Learn)
注意すべきなのは、Retrieval APIが権限を尊重しても、取得後のextractをどのLLMや外部サービスに渡すかはアプリ設計の責任になる点です。Microsoft 365の境界内で取得した情報を外部モデルに送る場合は、データ処理契約、ログ保存、学習利用の有無、データ保持期間を必ず確認してください。
営業・提案書作成支援
顧客別サイトや提案書テンプレートをSharePointで管理している場合、顧客名や製品名、業界、提案フェーズを含むクエリで関連文書を取得できます。競合顧客を扱う組織では、顧客別サイトの権限設計が特に重要です。Retrieval APIはMicrosoft 365の権限モデルを尊重しますが、元のSharePoint共有が広すぎれば、その範囲が回答根拠にも影響します。(Microsoft Learn)
本番展開前のチェックリスト
本番導入前には、技術検証だけでなく、管理・運用・利用者体験まで含めて確認してください。
| 役割 | チェック項目 |
|---|---|
| Microsoft 365管理者 | Copilotライセンス、Pay-as-you-go有効化、アプリ同意、共有権限、検索除外を確認したか |
| セキュリティ担当 | 秘密度ラベル、DLP、外部LLM利用、ログ保存、監査要件を確認したか |
| SharePoint管理者 | 対象サイト、ライブラリ、メタデータ、検索可能性、古い文書の整理を確認したか |
| 開発者 | dataSource、KQL、再試行、レート制限、空結果、出典表示を実装したか |
| 業務部門 | 正解文書、想定質問、誤回答時のフィードバック方法を用意したか |
| 運用担当 | API利用量、課金、エラー率、回答品質、問い合わせ窓口を監視できるか |
特に、AIエージェントを先に作り、あとからSharePointの情報整理を始めると、回答品質の改善に時間がかかります。順序としては、対象業務の文書整理、検索範囲の設計、Graph権限の確認、API検証、エージェント実装、部門パイロットの流れが安全です。
まとめ：Retrieval APIは「安全な社内RAG」の近道だが、設計なしでは効果が出ない
Microsoft 365 Copilot Retrieval APIは、SharePoint、OneDrive、Copilot connectorsの情報をAIソリューションの根拠として使いたい企業にとって、強力な選択肢です。別の検索基盤に文書を複製せず、Microsoft 365のアクセス制御やガバナンスを活かしながら、カスタムエージェントや独自アプリの回答精度を高められます。(Microsoft Learn)
一方で、導入成功の鍵はAPIそのものではなく、検索対象の設計です。まずは対象業務を1つに絞り、承認済みSharePointライブラリを決め、Graph Explorerや小さな検証アプリでqueryString、dataSource、filterExpressionの動きを確認しましょう。そのうえで、ライセンス、Pay-as-you-go、権限、Purview、出典表示、コスト監視を整えてから本番展開するのが現実的です。
次に取るべき行動は明確です。自社で最も効果が出やすい「文書根拠が明確な問い合わせ業務」を1つ選び、検索対象サイトを限定し、10〜20個の実質問でRetrieval APIの返却結果を確認してください。その検証結果をもとに、AIエージェント化すべきか、既存RAGと併用すべきか、本番展開に進めるべきかを判断できます。
コメント