Microsoft 365 Copilot とエージェントのエクスペリエンスを追加する

適用対象: Developer

SharePoint Embedded エージェントエクスペリエンスを使用すると、アプリは SharePoint Embedded コンテナーに保存されているファイルの質問に回答できます。 2 つの別個の製品が、コンテナーコンテンツにこれらのエクスペリエンスを基盤としています。

SharePoint ナレッジソースを使用した Microsoft Foundry エージェントサービス — Foundry 上に構築するエージェント向け。 Foundry は、エージェントの一部として取得を実行します。セットアップ手順については、「 SharePoint Embedded を Foundry ナレッジソースとして設定する」を参照してください。
Microsoft 365 Copilot Retrieval API — 独自のグラウンディングステップを実行するカスタムエージェントとアプリ向け。 SharePoint ナレッジソースを使用しない Foundry エージェントを含む、任意のアプリから呼び出します。

Foundry で取得とエージェントのオーケストレーションを管理する場合は、ナレッジソースを選択します。グラウンディング手順、プロンプト、モデルを自分で制御する場合は、取得 API を選択します。

ヒント

これらのエクスペリエンスの背後にある SharePoint Embedded リソースをコーディングエージェントからプロビジョニングおよび管理するには、 SharePoint Embedded MCP サーバーを使用します。

SharePoint Embedded がエージェントを基盤とする方法

SharePoint Embedded は、エンタープライズコンテンツに基づいて AI エージェントを使用し、そのコンテンツとそのコンプライアンス制御を顧客の Microsoft 365 テナント内に維持します。外部のベクターデータベースにコンテンツをコピーしない。重要な事実:

コンテンツの検出可能性は、Microsoft 365 Copilot がコンテンツを表示できるかどうかを制御するコンテナーの種類に関する設定です。テナントガバナンスはこの設定を制御するため、アプリが独自の構成を変更してコンテンツを公開することはできません。
コンテナーの種類 ID (ContainerTypeId) で範囲指定された Microsoft Search API または Foundry SharePoint ナレッジソースを使用してコンテンツを取得します。
コンテンツは顧客の Microsoft 365 テナントに残るため、Microsoft Purview データ損失防止 (DLP)、保持、電子情報開示が適用されます。
何も自動公開されません。 SharePoint 埋め込みコンテンツは、コンテナーの種類で検出可能性が有効になるまで、Copilot で使用できません。

決定コンテキストについては、外部ベクトルデータベースのないGround AIを参照してください。

注意

以前の SharePoint 埋め込みエージェント SDK (React ChatEmbedded コントロール) は 2026 年 3 月に非推奨となり、SharePoint 埋め込み用に構成された SharePoint ナレッジソース (プレビュー) を備えた Microsoft Foundry エージェントサービスに置き換えられました。新しい作業には、この記事の 2 つのオプションのいずれかを使用します。

Retrieval API を使用する

Microsoft 365 Copilot Retrieval API は、関連するテキスト抽出を返し、アプリが基盤データとして独自のモデルに渡します。 SharePoint Embedded からコンテンツを取得するには、[ dataSource ] を [ sharePointEmbedded ] に設定します。

注:

sharePointEmbedded データソースに対する取得 API のサポートはプレビュー段階です。

取得 API の前提条件

コンテナーの種類 ID が少なくとも 1 つある SharePoint Embedded アプリ。
コンテナーの種類に対して構成された従量課金制。
テナント内に少なくとも 1 人のユーザーが Microsoft 365 Copilot ライセンスを持っているため、セマンティックインデックスが初期化されます。詳細については、「Microsoft 365 Copilot のセマンティックインデックス」を参照してください。

sharePointEmbedded データソースは従量課金制で請求されるため、検索 API をクエリする各ユーザーは個別のMicrosoft 365 Copilot ライセンスを必要としません。

コンテナー型からコンテンツを取得する

委任されたトークンを使用して POST /copilot/retrieval を呼び出します。 dataSource を sharePointEmbedded に設定し、コンテナーの種類 ID を dataSourceConfiguration に渡します。要求には FileStorageContainer.Selected 委任されたアクセス許可が必要であり、サービスはサインインしたユーザーがアクセスできるコンテンツに結果をトリミングします。

POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json

{
  "queryString": "What are the terms of the Contoso agreement?",
  "dataSource": "sharePointEmbedded",
  "dataSourceConfiguration": {
    "sharePointEmbedded": {
      "containerTypeId": "{containerTypeId}"
    }
  }
}

{containerTypeId}コンテナーの種類 ID に置き換えます。

応答は、 retrievalHits コレクションを返します。各ヒットは、webUrlを介してソースファイルを識別し、relevanceScore順に 1 つ以上のextractsを運びます。

{
  "retrievalHits": [
    {
      "webUrl": "https://contoso.com/spe/file",
      "extracts": [
        {
          "text": "The agreement renews annually unless either party gives 30 days' notice.",
          "relevanceScore": 0.8421
        }
      ]
    }
  ]
}

webUrlの形状はコンテナータイプのurlTemplate設定に依存するため、解析するのではなく、不透明なリンクとして扱ってください。ファイルの詳細を解決するには、 Get a driveItem を呼び出します。 urlTemplateの詳細については、「コンテナータイプの作成と構成」を参照してください。

ヒットするたびに title や author などの追加のフィールドを返すには、要求に resourceMetadata コレクションを追加します。各フィールドが応答のペイロードに追加されるため、アプリが使用するフィールドのみを要求します。

カスタムメタデータによる取得をフィルター処理する

filterExpression を使用して、特定のカスタムメタデータを持つファイルのみに取得を制限します。まず、インデックス付きカスタム列を作成し、ファイル値を設定し、検索インデックスの作成が完了するまで待ちます。手順については、コンテナーメタデータの保存とクエリを参照してください。

SharePoint Embedded では、ファイルのカスタム列の値は、関連付けられた listItem/fields リソースに格納されます。取得フィルターは、格納されているフィールド名ではなく、列のインデックス付き SharePoint 管理プロパティに対するものです。

たとえば、 ClientMatterCode という名前の単一行のテキスト列には、通常、次のような管理プロパティがあります。

ClientMatterCodeOWSTEXT

自動的に作成される管理プロパティは、ソース列に別のデータ型が使用されている場合でも、テキストプロパティです。サフィックスとインデックス付き値の形式は、列の種類によって異なります。ターゲットテナントで生成されたプロパティ名と値の形式を確認します。名前付けの詳細については、「 SharePoint Server で自動的に作成された管理プロパティ」を参照してください。

この要求では、候補は正確なインデックス付きメタデータ値を持つファイルに制限されます。また、一致する各ヒットの値も返します。

POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json

{
  "queryString": "What obligations are described in the client agreement?",
  "dataSource": "sharePointEmbedded",
  "dataSourceConfiguration": {
    "sharePointEmbedded": {
      "containerTypeId": "{containerTypeId}"
    }
  },
  "filterExpression": "ClientMatterCodeOWSTEXT=\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\"",
  "resourceMetadata": [
    "title",
    "containerTypeId",
    "ClientMatterCodeOWSTEXT"
  ],
  "maximumNumberOfResults": 10
}

インデックス値全体が一致する必要がある場合は、 = を使用します。

ClientMatterCodeOWSTEXT="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"

正確な境界には : 演算子を使用しないでください。コロン演算子は、用語の一致を実行し、関連する値またはプレフィックスを一致させることができます。詳細については、「キーワード照会言語構文リファレンス」を参照してください。

フィルターは、 queryString 意味的に関連する抽出をランク付けする前に、候補ファイルを制限します。一致するメタデータを持つファイルは、その内容が queryString に関連していない場合、表示されないことがあります。

抽出を独自のモデルまたは回答生成ステップに根拠データとして渡します。このスニペットはクエリを送信し、各ヒットから上位の抽出を読み取ります。

const response = await fetch("https://graph.microsoft.com/v1.0/copilot/retrieval", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    queryString: query,
    dataSource: "sharePointEmbedded",
    dataSourceConfiguration: {
      sharePointEmbedded: { containerTypeId: containerTypeId }
    }
  })
});

const data = await response.json();
const grounding = (data.retrievalHits ?? []).map(hit => ({
  url: hit.webUrl,
  text: hit.extracts?.[0]?.text?.trim(),
  score: hit.extracts?.[0]?.relevanceScore
}));

取得は、サインインしたユーザーがアクセスできるコンテナータイプのすべてのコンテナーを対象としています。要求からヒットが返されない場合は、セマンティックインデックスが初期化されていること、インデックス作成が完了していること、およびユーザーがコンテンツにアクセスできることを確認します。

Retrieval API の課金

Copilot Studio メッセージメーターで sharePointEmbedded データソース請求書を使用する取得 API 要求。料金は、コンテナーの種類に対して構成された課金モデルに従います。 Standard 課金では所有テナントの Azure サブスクリプションが課金され、パススルー課金では使用テナントのサブスクリプションが課金されます。

メーターの詳細については、「課金メーター」を参照してください。モデルを比較するには、「課金モデルの選択」を参照してください。

ユーザーエクスペリエンスをテストする

コンテナーコンテンツにアクセスできるユーザーでサインインします。サポートされているファイルをコンテナーにアップロードし、インデックス作成を待機し、チャットを開いて、ファイルコンテンツが回答できる質問をします。回答で想定されるファイルが省略された場合は、次をチェックします。

検出可能性。
サポートされているファイル形式。
アプリアクセス。
ユーザーアクセス。
スコープの選択。
インデックス作成の遅延。

次の手順

Last updated on 2026-09-18