Microsoft 365のコンテンツをAIクエリのコンテキストとして活用する「Copilot Retrieval API」が、Microsoft Graph PowerShell SDKから利用できるようになっている。このAPIはRAG（Retrieval Augmented Generation）の仕組みでSharePoint OnlineやOneDrive for Businessを検索し、生成AI処理前のグラウンディングを担う。単なる検索ではなく、アプリケーションがどのようにCopilotと連携しているかを理解する上でも重要なAPIだ。

Copilot Retrieval APIとは何か

Microsoft Graph上に公開されているCopilot Retrieval APIは、アプリケーションがユーザーのプロンプトを送信する前に、M365上の関連情報を取得してコンテキストを補完するための仕組みだ。このプロセスが「グラウンディング」と呼ばれる。

よく似た名前のCopilot Search APIも存在するが、両者には明確な違いがある。

API 検索方式 用途

Copilot Search API セマンティック検索 キーワード・意味的類似性

Copilot Retrieval API RAG検索 AIプロンプトのグラウンディング

WordやExcel、PowerPointにCopilotが統合されている際に裏側で行っている処理がまさにこのRetrieval APIを通じた情報取得だ。APIを触ることで、Copilotの統合がどのように機能しているかを実感できる。

利用条件と認証の仕組み

利用にはM365 Copilotライセンスが必要だが、従量課金（Pay-as-you-go）モデルでも利用可能だ。重要なのは、このAPIが委任アクセス許可（Delegated Permissions）のみをサポートしている点で、アプリケーション権限（App-only）では動作しない。

必要なスコープは以下の通り：

  • Files.Read.All — OneDrive for Businessのファイルアクセス
  • Sites.Read.All — SharePoint Onlineのサイトアクセス
  • ExternalItem.Read.All — Copilotコネクタ経由の外部データ（オプション）

サインインしているユーザーの権限範囲でのみ検索できる設計は、情報漏洩リスクを最小化するという観点で適切な設計だ。

PowerShellでの実装

Graph PowerShell SDK v2.35.1を使った基本的な実装は以下の通りだ。

出典: この記事は Running Copilot Retrieval Searches with the Microsoft Graph PowerShell SDK の内容をもとに、筆者の見解を加えて独自に執筆したものです。