リモート SharePoint ナレッジ ソースを作成する

リモート SharePoint ナレッジ ソースは、Copilot 取得 API を使用して、Microsoft 365 の SharePoint からテキスト コンテンツに直接クエリを実行し、マージ、ランク付け、応答の定式化のためにエージェント検索エンジンに結果を返します。 このナレッジ ソースで使用される検索インデックスはなく、テキスト コンテンツのみがクエリされます。

クエリ時に、リモート SharePoint ナレッジ ソースは、ユーザー ID に代わって Copilot 取得 API を呼び出します。そのため、ナレッジ ソース定義に接続文字列は必要ありません。 ユーザーがアクセス権を持つすべてのコンテンツは、ナレッジ取得のスコープ内にあります。 サイトを制限したり、検索を制限したりするには、 フィルター式を設定します。 Azure テナントと Microsoft 365 テナントは同じ Microsoft Entra ID テナントを使用する必要があり、呼び出し元の ID は両方のテナントで認識される必要があります。

• フィルターを使用して、URL、日付範囲、ファイルの種類、およびその他のメタデータで検索の範囲を指定できます。

• SharePoint のアクセス許可と Purview ラベルは、コンテンツの要求で受け入れられます。

• 使用量は、Microsoft 365 と Copilot ライセンスを通じて課金されます。

他のナレッジ ソースと同様に、ナレッジ ベース でリモート SharePoint ナレッジ ソースを指定し、エージェントまたはチャットボットがクエリ時に 取得アクション を呼び出すときに、その結果をグラウンド データとして使用します。

[前提条件]

• Azure AI Search はエージェント型情報検索を提供する任意のリージョンで利用可能です。 セマンティック ランカーを有効にする必要があります。

• Azure と同じ Microsoft Entra ID テナントの下にある Microsoft 365 テナント内の SharePoint。

• ローカル開発用の個人用アクセス トークン、またはクライアント アプリケーションからのユーザーの ID。

• .NET SDK 用の Azure.Search.Documents クライアント ライブラリ の最新のプレビュー バージョン。

• Azure AI Search でオブジェクトを作成して使用するためのアクセス許可。 ロールベースのアクセスをお勧めしますが、ロールの割り当てが不可能な場合は API キーを使用できます。

ローカル開発の場合、エージェント検索エンジンはアクセス トークンを使用して、ユーザーに代わって SharePoint を呼び出します。 要求で個人用アクセス トークンを使用する方法の詳細については、「 Azure AI Search への接続」を参照してください。

制限事項

Copilot 取得 API の次の制限は、リモートの SharePoint ナレッジ ソースに適用されます。

• Copilot コネクタや OneDrive コンテンツはサポートされません。 コンテンツは SharePoint サイトからのみ取得されます。

• 1 時間あたりユーザーあたり 200 要求の制限。

• クエリ文字の制限は 1,500 文字です。

• ハイブリッド クエリは、.doc、.docx、.pptx、.pdf、.aspx、.one というファイル拡張子でのみサポートされます。

• マルチモーダル取得 (表、画像、グラフを含む非テキスト コンテンツ) はサポートされていません。

• クエリからの結果は最大 25 個です。

• 結果は、順序なしとして Copilot 取得 API によって返されます。

• 無効なキーワード クエリ言語 (KQL) フィルター式は無視され、クエリはフィルターなしで引き続き実行されます。

既存のナレッジ ソースを確認する

ナレッジ ソースは、最上位の再利用可能なオブジェクトです。 既存のナレッジ ソースについて知ることは、新しいオブジェクトを再利用または名前付けする場合に役立ちます。

次のコードを実行して、名前と種類でナレッジ ソースを一覧表示します。

// List knowledge sources by name and type
using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeSources = indexClient.GetKnowledgeSourcesAsync();

Console.WriteLine("Knowledge Sources:");

await foreach (var ks in knowledgeSources)
{
    Console.WriteLine($"  Name: {ks.Name}, Type: {ks.GetType().Name}");
}

名前で 1 つのナレッジ ソースを取得し、その JSON 定義を確認することもできます。

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge source name to retrieve
string ksNameToGet = "earth-knowledge-source";

// Get its definition
var knowledgeSourceResponse = await indexClient.GetKnowledgeSourceAsync(ksNameToGet);
var ks = knowledgeSourceResponse.Value;

// Serialize to JSON for display
var jsonOptions = new JsonSerializerOptions 
{ 
    WriteIndented = true,
    DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(ks, ks.GetType(), jsonOptions));

次の JSON は、リモートの SharePoint ナレッジ ソースに対する応答の例です。

{
  "name": "my-sharepoint-ks",
  "kind": "remoteSharePoint",
  "description": "A sample remote SharePoint knowledge source",
  "encryptionKey": null,
  "remoteSharePointParameters": {
    "filterExpression": "filetype:docx",
    "containerTypeId": null,
    "resourceMetadata": [
      "Author",
      "Title"
    ]
  }
}

ナレッジ ソースを作成する

次のコードを実行して、リモート SharePoint ナレッジ ソースを作成します。

API キー は、Azure AI Search と Azure OpenAI へのクライアント接続に使用されます。 アクセス トークンは、Azure AI Search によって、ユーザーの代わりに Microsoft 365 の SharePoint に接続するために使用されます。 取得できるのは、アクセスが許可されているコンテンツのみです。 個人用アクセス トークンとその他の値の取得の詳細については、「 Azure AI Search への接続」を参照してください。

// Create a remote SharePoint knowledge source
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;
using Azure;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

var knowledgeSource = new RemoteSharePointKnowledgeSource(name: "my-remote-sharepoint-ks")
{
    Description = "This knowledge source queries .docx files in a trusted Microsoft 365 tenant.",
    RemoteSharePointParameters = new RemoteSharePointKnowledgeSourceParameters()
    {
        FilterExpression = "filetype:docx",
        ResourceMetadata = { "Author", "Title" }
    }
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSource.Name}' created or updated successfully.");

ソース固有のプロパティ

次のプロパティを渡して、リモート SharePoint ナレッジ ソースを作成できます。

フィルター式の例

filterExpressionでは、すべての SharePoint プロパティがサポートされているわけではありません。 サポートされているプロパティの一覧については、「API リファレンス」を参照してください。 フィルターで使用できるクエリ可能なプロパティの詳細については、 クエリ可能なプロパティを示します。

KQL フィルターの詳細については、構文リファレンスを参照してください。

ナレッジ ベースに割り当てる

ナレッジ ソースに問題がない場合は、次の手順に進 みます。ナレッジ ベースでナレッジ ソースを指定します。

ナレッジ ベースを構成したら、 取得アクション を使用してナレッジ ソースにクエリを実行します。

ナレッジ ベースにクエリを実行する

ナレッジ ベースの 取得アクション は、Microsoft 365 のコンテンツへのアクセスを承認するユーザー ID を提供します。

Azure AI Search では、アクセス トークンを使用して、ユーザー ID に代わって Copilot 取得 API を呼び出します。 アクセス トークンは、 xMsQuerySourceAuthorization HTTP ヘッダーとして取得エンドポイントで提供されます。

using Azure;
using Azure.Search.Documents.KnowledgeBases;
using Azure.Search.Documents.KnowledgeBases.Models;

// Get access token
var credential = new DefaultAzureCredential();
var tokenRequestContext = new Azure.Core.TokenRequestContext(new[] { "https://search.azure.com/.default" });
var accessToken = await credential.GetTokenAsync(tokenRequestContext);
string token = accessToken.Token;

// Create knowledge base retrieval client
var baseClient = new KnowledgeBaseRetrievalClient(
    endpoint: new Uri(searchEndpoint),
    knowledgeBaseName: knowledgeBaseName,
    credential: new AzureKeyCredential()
);

var spMessages = new List<Dictionary<string, string>>
{
    new Dictionary<string, string>
    {
        { "role", "user" },
        { "content", @"contoso product planning" }
    }
};

// Create retrieval request
var retrievalRequest = new KnowledgeBaseRetrievalRequest();
foreach (Dictionary<string, string> message in spMessages) {
    if (message["role"] != "system") {
        retrievalRequest.Messages.Add(new KnowledgeBaseMessage(content: new[] { new KnowledgeBaseMessageTextContent(message["content"]) }) { Role = message["role"] });
    }
}
retrievalRequest.RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort();
var retrievalResult = await baseClient.RetrieveAsync(retrievalRequest, xMsQuerySourceAuthorization: token);

Console.WriteLine((retrievalResult.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent).Text);

応答は次のようになります。

Contoso's product planning for the NextGen Camera includes a 2019 launch with a core package design and minor modifications for three product versions, featuring Wi-Fi enabled technology and a new mobile app for photo organization and sharing, aiming for 100,000 users within six months [ref_id:0][ref_id:1]. Research and forecasting are central to their planning, with phase two research focusing on feedback from a diverse user group to shape deliverables and milestones [ref_id:0][ref_id:1].

クエリ時に制約を適用する場合、取得要求は KQL フィルター (filterExpressionAddOn) も受け取ります。 ナレッジ ソースとナレッジ ベースの取得アクションの両方で filterExpressionAddOn を指定すると、フィルターは一緒に AND になります。

コンテンツ自体に関する質問をするクエリは、ファイルが配置されている場所や最後に更新された日時に関する質問よりも効果的です。 たとえば、"Ignite 2024 のキーノート ドキュメントはどこにありますか" と尋ねると、コンテンツ自体がその場所を開示していないため、"No relevant content was found for your query" が表示されることがあります。 メタデータに対するフィルターは、ファイルの場所または日付固有のクエリに適したソリューションです。

より良い質問は、「Ignite 2024のキーノートドキュメントは何ですか」です。 応答には、合成された回答、クエリ アクティビティとトークンの数、および URL とその他のメタデータが含まれます。

{
    "resourceMetadata": {
        "Author": "Nuwan Amarathunga;Nurul Izzati",
        "Title": "Ignite 2024 Keynote Address"
    }
},
"rerankerScore": 2.489522,
"webUrl": "https://contoso-my.sharepoint.com/keynotes/nuamarth_contoso_com/Documents/Keynote-Ignite-2024.docx",
"searchSensitivityLabelInfo": {
        "displayName": "Confidential\\Contoso Extended",
        "sensitivityLabelId": "aaaaaaaa-0b0b-1c1c-2d2d-333333333333",
        "tooltip": "Data is classified and protected. Contoso Full Time Employees (FTE) and non-employees can edit, reply, forward and print. Recipient can unprotect content with the right justification.",
        "priority": 5,
        "color": "#FF8C00",
        "isEncrypted": true
    }

ナレッジ ソースを削除する

ナレッジ ソースを削除する前に、ナレッジ ソースを参照するすべてのナレッジ ベースを削除するか、ナレッジ ベース定義を更新して参照を削除する必要があります。 インデックスとインデクサー パイプラインを生成するナレッジ ソースの場合、 生成されたすべてのオブジェクト も削除されます。 ただし、既存のインデックスを使用してナレッジ ソースを作成した場合、インデックスは削除されません。

使用中のナレッジ ソースを削除しようとすると、アクションは失敗し、影響を受けるナレッジ ベースの一覧が返されます。

ナレッジ ソースを削除するには:

1. 検索サービスのすべてのナレッジ ベースの一覧を取得します。

   using Azure.Search.Documents.Indexes;
   
   var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
   var knowledgeBases = indexClient.GetKnowledgeBasesAsync();
   
   Console.WriteLine("Knowledge Bases:");
   
   await foreach (var kb in knowledgeBases)
   {
       Console.WriteLine($"  - {kb.Name}");
   }
   

   応答の例は次のようになります。

    Knowledge Bases:
      - earth-knowledge-base
      - hotels-sample-knowledge-base
      - my-demo-knowledge-base
   

2. 個々のナレッジベース定義を取得して、ナレッジソースの参照を確認します。

   using Azure.Search.Documents.Indexes;
   using System.Text.Json;
   
   var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
   
   // Specify the knowledge base name to retrieve
   string kbNameToGet = "earth-knowledge-base";
   
   // Get a specific knowledge base definition
   var knowledgeBaseResponse = await indexClient.GetKnowledgeBaseAsync(kbNameToGet);
   var kb = knowledgeBaseResponse.Value;
   
   // Serialize to JSON for display
   string json = JsonSerializer.Serialize(kb, new JsonSerializerOptions { WriteIndented = true });
   Console.WriteLine(json);
   

   応答の例は次のようになります。

    {
      "Name": "earth-knowledge-base",
      "KnowledgeSources": [
        {
          "Name": "earth-knowledge-source"
        }
      ],
      "Models": [
        {}
      ],
      "RetrievalReasoningEffort": {},
      "OutputMode": {},
      "ETag": "\u00220x8DE278629D782B3\u0022",
      "EncryptionKey": null,
      "Description": null,
      "RetrievalInstructions": null,
      "AnswerInstructions": null
    }
   

3. ナレッジ ベースを削除するか、ナレッジ ベースを更新 して、複数のソースがある場合はナレッジ ソースを削除します。 この例では、削除を示します。

   using Azure.Search.Documents.Indexes;
   var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
   
   await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName);
   System.Console.WriteLine($"Knowledge base '{knowledgeBaseName}' deleted successfully.");
   

4. ナレッジ ソースを削除します。

   await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName);
   System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");
   

リモート SharePoint ナレッジ ソースは、Copilot 取得 API を使用して、Microsoft 365 の SharePoint からテキスト コンテンツに直接クエリを実行し、マージ、ランク付け、応答の定式化のためにエージェント検索エンジンに結果を返します。 このナレッジ ソースで使用される検索インデックスはなく、テキスト コンテンツのみがクエリされます。

クエリ時に、リモート SharePoint ナレッジ ソースは、ユーザー ID に代わって Copilot 取得 API を呼び出します。そのため、ナレッジ ソース定義に接続文字列は必要ありません。 ユーザーがアクセス権を持つすべてのコンテンツは、ナレッジ取得のスコープ内にあります。 サイトを制限したり、検索を制限したりするには、 フィルター式を設定します。 Azure テナントと Microsoft 365 テナントは同じ Microsoft Entra ID テナントを使用する必要があり、呼び出し元の ID は両方のテナントで認識される必要があります。

• フィルターを使用して、URL、日付範囲、ファイルの種類、およびその他のメタデータで検索の範囲を指定できます。

• SharePoint のアクセス許可と Purview ラベルは、コンテンツの要求で受け入れられます。

• 使用量は、Microsoft 365 と Copilot ライセンスを通じて課金されます。

他のナレッジ ソースと同様に、ナレッジ ベース でリモート SharePoint ナレッジ ソースを指定し、エージェントまたはチャットボットがクエリ時に 取得アクション を呼び出すときに、その結果をグラウンド データとして使用します。

[前提条件]

• Azure AI Search はエージェント型情報検索を提供する任意のリージョンで利用可能です。 セマンティック ランカーを有効にする必要があります。

• Azure と同じ Microsoft Entra ID テナントの下にある Microsoft 365 テナント内の SharePoint。

• ローカル開発用の個人用アクセス トークン、またはクライアント アプリケーションからのユーザーの ID。

• Python 用 azure-search-documents クライアント ライブラリ の最新のプレビュー バージョン。

• Azure AI Search でオブジェクトを作成して使用するためのアクセス許可。 ロールベースのアクセスをお勧めしますが、ロールの割り当てが不可能な場合は API キーを使用できます。

ローカル開発の場合、エージェント検索エンジンはアクセス トークンを使用して、ユーザーに代わって SharePoint を呼び出します。 要求で個人用アクセス トークンを使用する方法の詳細については、「 Azure AI Search への接続」を参照してください。

制限事項

Copilot 取得 API の次の制限は、リモートの SharePoint ナレッジ ソースに適用されます。

• Copilot コネクタや OneDrive コンテンツはサポートされません。 コンテンツは SharePoint サイトからのみ取得されます。

• 1 時間あたりユーザーあたり 200 要求の制限。

• クエリ文字の制限は 1,500 文字です。

• ハイブリッド クエリは、.doc、.docx、.pptx、.pdf、.aspx、.one というファイル拡張子でのみサポートされます。

• マルチモーダル取得 (表、画像、グラフを含む非テキスト コンテンツ) はサポートされていません。

• クエリからの結果は最大 25 個です。

• 結果は、順序なしとして Copilot 取得 API によって返されます。

• 無効なキーワード クエリ言語 (KQL) フィルター式は無視され、クエリはフィルターなしで引き続き実行されます。

既存のナレッジ ソースを確認する

ナレッジ ソースは、最上位の再利用可能なオブジェクトです。 既存のナレッジ ソースについて知ることは、新しいオブジェクトを再利用または名前付けする場合に役立ちます。

次のコードを実行して、名前と種類でナレッジ ソースを一覧表示します。

# List knowledge sources by name and type
import requests
import json

endpoint = "{search_url}/knowledgesources"
params = {"api-version": "2025-11-01-preview", "$select": "name, kind"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

名前で 1 つのナレッジ ソースを取得し、その JSON 定義を確認することもできます。

# Get a knowledge source definition
import requests
import json

endpoint = "{search_url}/knowledgesources/{knowledge_source_name}"
params = {"api-version": "2025-11-01-preview"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

次の JSON は、リモートの SharePoint ナレッジ ソースに対する応答の例です。

{
  "name": "my-sharepoint-ks",
  "kind": "remoteSharePoint",
  "description": "A sample remote SharePoint knowledge source",
  "encryptionKey": null,
  "remoteSharePointParameters": {
    "filterExpression": "filetype:docx",
    "containerTypeId": null,
    "resourceMetadata": [
      "Author",
      "Title"
    ]
  }
}

ナレッジ ソースを作成する

次のコードを実行して、リモート SharePoint ナレッジ ソースを作成します。

API キー は、Azure AI Search と Azure OpenAI へのクライアント接続に使用されます。 アクセス トークンは、Azure AI Search によって、ユーザーの代わりに Microsoft 365 の SharePoint に接続するために使用されます。 取得できるのは、アクセスが許可されているコンテンツのみです。 個人用アクセス トークンとその他の値の取得の詳細については、「 Azure AI Search への接続」を参照してください。

# Create a remote SharePoint knowledge source
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import RemoteSharePointKnowledgeSource, RemoteSharePointKnowledgeSourceParameters

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

knowledge_source = RemoteSharePointKnowledgeSource(
    name = "my-remote-sharepoint-ks",
    description= "This knowledge source queries .docx files in a trusted Microsoft 365 tenant.",
    encryption_key = None,
    remote_share_point_parameters = RemoteSharePointKnowledgeSourceParameters(
        filter_expression = "filetype:docx",
        resource_metadata = ["Author", "Title"],
        container_type_id = None
    )
)

index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")

ソース固有のプロパティ

次のプロパティを渡して、リモート SharePoint ナレッジ ソースを作成できます。

フィルター式の例

filterExpressionでは、すべての SharePoint プロパティがサポートされているわけではありません。 サポートされているプロパティの一覧については、「API リファレンス」を参照してください。 フィルターで使用できるクエリ可能なプロパティの詳細については、 クエリ可能なプロパティを示します。

KQL フィルターの詳細については、構文リファレンスを参照してください。

ナレッジ ベースに割り当てる

ナレッジ ソースに問題がない場合は、次の手順に進 みます。ナレッジ ベースでナレッジ ソースを指定します。

ナレッジ ベースを構成したら、 取得アクション を使用してナレッジ ソースにクエリを実行します。

ナレッジ ベースにクエリを実行する

ナレッジ ベースの 取得アクション は、Microsoft 365 のコンテンツへのアクセスを承認するユーザー ID を提供します。

Azure AI Search では、アクセス トークンを使用して、ユーザー ID に代わって Copilot 取得 API を呼び出します。 アクセス トークンは、 x-ms-query-source-authorization HTTP ヘッダーとして取得エンドポイントで提供されます。

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import KnowledgeBaseMessage, KnowledgeBaseMessageTextContent, KnowledgeBaseRetrievalRequest, RemoteSharePointKnowledgeSourceParams

# Get access token
identity_token_provider = get_bearer_token_provider(DefaultAzureCredential(), "https://search.azure.com/.default")
token = identity_token_provider()

# Create knowledge base retrieval client
kb_client = KnowledgeBaseRetrievalClient(endpoint = "search_url", knowledge_base_name = "knowledge_base_name", credential = AzureKeyCredential("api_key"))

# Create retrieval request
request = KnowledgeBaseRetrievalRequest(
    include_activity = True,
    messages = [
        KnowledgeBaseMessage(role = "user", content = [KnowledgeBaseMessageTextContent(text = "What was covered in the keynote doc for Ignite 2024?")])
    ],
    knowledge_source_params = [
        RemoteSharePointKnowledgeSourceParams(
            knowledge_source_name = "my-remote-sharepoint-ks",
            filter_expression_add_on = "ModifiedBy:\"Adele Vance\"",
            include_references = True,
            include_reference_source_data = True
        )
    ]
)

# Pass access token to retrieve from knowledge base
result = kb_client.retrieve(retrieval_request = request, x_ms_query_source_authorization = token)
print(result.response[0].content[0].text)

クエリ時に制約を適用する場合、取得要求は KQL フィルター (filter_expression_add_on) も受け取ります。 ナレッジ ソースとナレッジ ベースの取得アクションの両方で filter_expression_add_on を指定すると、フィルターは一緒に AND になります。

コンテンツ自体に関する質問をするクエリは、ファイルが配置されている場所や最後に更新された日時に関する質問よりも効果的です。 たとえば、"Ignite 2024 のキーノート ドキュメントはどこにありますか" と尋ねると、コンテンツ自体がその場所を開示していないため、"No relevant content was found for your query" が表示されることがあります。 メタデータに対するフィルターは、ファイルの場所または日付固有のクエリに適したソリューションです。

より良い質問は、「Ignite 2024のキーノートドキュメントは何ですか」です。 応答には、合成された回答、クエリ アクティビティとトークンの数、および URL とその他のメタデータが含まれます。

{
    "resourceMetadata": {
        "Author": "Nuwan Amarathunga;Nurul Izzati",
        "Title": "Ignite 2024 Keynote Address"
    }
},
"rerankerScore": 2.489522,
"webUrl": "https://contoso-my.sharepoint.com/keynotes/nuamarth_contoso_com/Documents/Keynote-Ignite-2024.docx",
"searchSensitivityLabelInfo": {
        "displayName": "Confidential\\Contoso Extended",
        "sensitivityLabelId": "aaaaaaaa-0b0b-1c1c-2d2d-333333333333",
        "tooltip": "Data is classified and protected. Contoso Full Time Employees (FTE) and non-employees can edit, reply, forward and print. Recipient can unprotect content with the right justification.",
        "priority": 5,
        "color": "#FF8C00",
        "isEncrypted": true
    }

ナレッジ ソースを削除する

ナレッジ ソースを削除する前に、ナレッジ ソースを参照するすべてのナレッジ ベースを削除するか、ナレッジ ベース定義を更新して参照を削除する必要があります。 インデックスとインデクサー パイプラインを生成するナレッジ ソースの場合、 生成されたすべてのオブジェクト も削除されます。 ただし、既存のインデックスを使用してナレッジ ソースを作成した場合、インデックスは削除されません。

使用中のナレッジ ソースを削除しようとすると、アクションは失敗し、影響を受けるナレッジ ベースの一覧が返されます。

ナレッジ ソースを削除するには:

1. 検索サービスのすべてのナレッジ ベースの一覧を取得します。

   # Get knowledge bases
   import requests
   import json
   
   endpoint = "{search_url}/knowledgebases"
   params = {"api-version": "2025-11-01-preview", "$select": "name"}
   headers = {"api-key": "{api_key}"}
   
   response = requests.get(endpoint, params = params, headers = headers)
   print(json.dumps(response.json(), indent = 2))
   

   応答の例は次のようになります。

    {
        "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
        "value": [
        {
            "name": "my-kb"
        },
        {
            "name": "my-kb-2"
        }
        ]
    }
   

2. 個々のナレッジベース定義を取得して、ナレッジソースの参照を確認します。

   # Get a knowledge base definition
   import requests
   import json
   
   endpoint = "{search_url}/knowledgebases/{knowledge_base_name}"
   params = {"api-version": "2025-11-01-preview"}
   headers = {"api-key": "{api_key}"}
   
   response = requests.get(endpoint, params = params, headers = headers)
   print(json.dumps(response.json(), indent = 2))
   

   応答の例は次のようになります。

    {
      "name": "my-kb",
      "description": null,
      "retrievalInstructions": null,
      "answerInstructions": null,
      "outputMode": null,
      "knowledgeSources": [
        {
          "name": "my-blob-ks",
        }
      ],
      "models": [],
      "encryptionKey": null,
      "retrievalReasoningEffort": {
        "kind": "low"
      }
    }
   

3. ナレッジ ベースを削除するか、ナレッジ ベースを更新 して、複数のソースがある場合はナレッジ ソースを削除します。 この例では、削除を示します。

   # Delete a knowledge base
   from azure.core.credentials import AzureKeyCredential 
   from azure.search.documents.indexes import SearchIndexClient
   
   index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
   index_client.delete_knowledge_base("knowledge_base_name")
   print(f"Knowledge base deleted successfully.")
   

4. ナレッジ ソースを削除します。

   # Delete a knowledge source
   from azure.core.credentials import AzureKeyCredential 
   from azure.search.documents.indexes import SearchIndexClient
   
   index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
   index_client.delete_knowledge_source("knowledge_source_name")
   print(f"Knowledge source deleted successfully.")
   

リモート SharePoint ナレッジ ソースは、Copilot 取得 API を使用して、Microsoft 365 の SharePoint からテキスト コンテンツに直接クエリを実行し、マージ、ランク付け、応答の定式化のためにエージェント検索エンジンに結果を返します。 このナレッジ ソースで使用される検索インデックスはなく、テキスト コンテンツのみがクエリされます。

クエリ時に、リモート SharePoint ナレッジ ソースは、ユーザー ID に代わって Copilot 取得 API を呼び出します。そのため、ナレッジ ソース定義に接続文字列は必要ありません。 ユーザーがアクセス権を持つすべてのコンテンツは、ナレッジ取得のスコープ内にあります。 サイトを制限したり、検索を制限したりするには、 フィルター式を設定します。 Azure テナントと Microsoft 365 テナントは同じ Microsoft Entra ID テナントを使用する必要があり、呼び出し元の ID は両方のテナントで認識される必要があります。

• フィルターを使用して、URL、日付範囲、ファイルの種類、およびその他のメタデータで検索の範囲を指定できます。

• SharePoint のアクセス許可と Purview ラベルは、コンテンツの要求で受け入れられます。

• 使用量は、Microsoft 365 と Copilot ライセンスを通じて課金されます。

他のナレッジ ソースと同様に、ナレッジ ベース でリモート SharePoint ナレッジ ソースを指定し、エージェントまたはチャットボットがクエリ時に 取得アクション を呼び出すときに、その結果をグラウンド データとして使用します。

[前提条件]

• Azure AI Search はエージェント型情報検索を提供する任意のリージョンで利用可能です。 セマンティック ランカーを有効にする必要があります。

• Azure と同じ Microsoft Entra ID テナントの下にある Microsoft 365 テナント内の SharePoint。

• ローカル開発用の個人用アクセス トークン、またはクライアント アプリケーションからのユーザーの ID。

• Search Service REST API の 2025-11-01-preview バージョン。

• Azure AI Search でオブジェクトを作成して使用するためのアクセス許可。 ロールベースのアクセスをお勧めしますが、ロールの割り当てが不可能な場合は API キーを使用できます。

ローカル開発の場合、エージェント検索エンジンはアクセス トークンを使用して、ユーザーに代わって SharePoint を呼び出します。 要求で個人用アクセス トークンを使用する方法の詳細については、「 Azure AI Search への接続」を参照してください。

制限事項

Copilot 取得 API の次の制限は、リモートの SharePoint ナレッジ ソースに適用されます。

• Copilot コネクタや OneDrive コンテンツはサポートされません。 コンテンツは SharePoint サイトからのみ取得されます。

• 1 時間あたりユーザーあたり 200 要求の制限。

• クエリ文字の制限は 1,500 文字です。

• ハイブリッド クエリは、.doc、.docx、.pptx、.pdf、.aspx、.one というファイル拡張子でのみサポートされます。

• マルチモーダル取得 (表、画像、グラフを含む非テキスト コンテンツ) はサポートされていません。

• クエリからの結果は最大 25 個です。

• 結果は、順序なしとして Copilot 取得 API によって返されます。

• 無効なキーワード クエリ言語 (KQL) フィルター式は無視され、クエリはフィルターなしで引き続き実行されます。

既存のナレッジ ソースを確認する

ナレッジ ソースは、最上位の再利用可能なオブジェクトです。 既存のナレッジ ソースについて知ることは、新しいオブジェクトを再利用または名前付けする場合に役立ちます。

ナレッジ ソース - Get (REST API) を使用して、名前と種類でナレッジ ソースを一覧表示します。

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version=2025-11-01-preview&$select=name,kind
api-key: {{api-key}}

名前で 1 つのナレッジ ソースを取得し、その JSON 定義を確認することもできます。

### Get a knowledge source definition
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

次の JSON は、リモートの SharePoint ナレッジ ソースに対する応答の例です。

{
  "name": "my-sharepoint-ks",
  "kind": "remoteSharePoint",
  "description": "A sample remote SharePoint knowledge source",
  "encryptionKey": null,
  "remoteSharePointParameters": {
    "filterExpression": "filetype:docx",
    "containerTypeId": null,
    "resourceMetadata": [
      "Author",
      "Title"
    ]
  }
}

ナレッジ ソースを作成する

ナレッジ ソース - 作成または更新 (REST API) を使用して、リモート SharePoint ナレッジ ソースを作成します。

API キー は、Azure AI Search と Azure OpenAI へのクライアント接続に使用されます。 アクセス トークンは、Azure AI Search によって、ユーザーの代わりに Microsoft 365 の SharePoint に接続するために使用されます。 取得できるのは、アクセスが許可されているコンテンツのみです。 個人用アクセス トークンとその他の値の取得の詳細については、「 Azure AI Search への接続」を参照してください。

POST {{search-url}}/knowledgesources/my-remote-sharepoint-ks?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json

{
    "name": "my-remote-sharepoint-ks",
    "kind": "remoteSharePoint",
    "description": "This knowledge source queries .docx files in a trusted Microsoft 365 tenant.",
    "encryptionKey": null,
    "remoteSharePointParameters": {
        "filterExpression": "filetype:docx",
        "resourceMetadata": [ "Author", "Title" ],
        "containerTypeId": null
    }
}

ソース固有のプロパティ

次のプロパティを渡して、リモート SharePoint ナレッジ ソースを作成できます。

フィルター式の例

filterExpressionでは、すべての SharePoint プロパティがサポートされているわけではありません。 サポートされているプロパティの一覧については、「API リファレンス」を参照してください。 フィルターで使用できるクエリ可能なプロパティの詳細については、 クエリ可能なプロパティを示します。

KQL フィルターの詳細については、構文リファレンスを参照してください。

ナレッジ ベースに割り当てる

ナレッジ ソースに問題がない場合は、次の手順に進 みます。ナレッジ ベースでナレッジ ソースを指定します。

ナレッジ ベースを構成したら、 取得アクション を使用してナレッジ ソースにクエリを実行します。

ナレッジ ベースにクエリを実行する

ナレッジ ベースの 取得アクション は、Microsoft 365 のコンテンツへのアクセスを承認するユーザー ID を提供します。

Azure AI Search では、アクセス トークンを使用して、ユーザー ID に代わって Copilot 取得 API を呼び出します。 アクセス トークンは、 x-ms-query-source-authorization HTTP ヘッダーとして取得エンドポイントで提供されます。

検索サービスを持つテナントの アクセス トークンを必ず生成 してください。

POST {{search-url}}/knowledgebases/remote-sp-kb/retrieve?api-version={{api-version}}
api-key: {{api-key}}
Content-Type: application/json
x-ms-query-source-authorization: {{access-token}}

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What was covered in the keynote doc for Ignite 2024?" }
            ]
        }
    ],
    "includeActivity": true,
    "knowledgeSourceParams": [
        {
            "filterExpressionAddOn": "ModifiedBy:\"Adele Vance\"",
            "knowledgeSourceName": "my-remote-sharepoint-ks",
            "kind": "remoteSharePoint",
            "includeReferences": true,
            "includeReferenceSourceData": true
        }
    ]
}

クエリ時に制約を適用する場合、取得要求は KQL フィルター (filterExpressionAddOn) も受け取ります。 ナレッジ ソースとナレッジ ベースの取得アクションの両方で filterExpressionAddOn を指定すると、フィルターは一緒に AND になります。

コンテンツ自体に関する質問をするクエリは、ファイルが配置されている場所や最後に更新された日時に関する質問よりも効果的です。 たとえば、"Ignite 2024 のキーノート ドキュメントはどこにありますか" と尋ねると、コンテンツ自体がその場所を開示していないため、"No relevant content was found for your query" が表示されることがあります。 メタデータに対するフィルターは、ファイルの場所または日付固有のクエリに適したソリューションです。

より良い質問は、「Ignite 2024のキーノートドキュメントは何ですか」です。 応答には、合成された回答、クエリ アクティビティとトークンの数、および URL とその他のメタデータが含まれます。

{
    "resourceMetadata": {
        "Author": "Nuwan Amarathunga;Nurul Izzati",
        "Title": "Ignite 2024 Keynote Address"
    }
},
"rerankerScore": 2.489522,
"webUrl": "https://contoso-my.sharepoint.com/keynotes/nuamarth_contoso_com/Documents/Keynote-Ignite-2024.docx",
"searchSensitivityLabelInfo": {
        "displayName": "Confidential\\Contoso Extended",
        "sensitivityLabelId": "aaaaaaaa-0b0b-1c1c-2d2d-333333333333",
        "tooltip": "Data is classified and protected. Contoso Full Time Employees (FTE) and non-employees can edit, reply, forward and print. Recipient can unprotect content with the right justification.",
        "priority": 5,
        "color": "#FF8C00",
        "isEncrypted": true
    }

ナレッジ ソースを削除する

ナレッジ ソースを削除する前に、ナレッジ ソースを参照するすべてのナレッジ ベースを削除するか、ナレッジ ベース定義を更新して参照を削除する必要があります。 インデックスとインデクサー パイプラインを生成するナレッジ ソースの場合、 生成されたすべてのオブジェクト も削除されます。 ただし、既存のインデックスを使用してナレッジ ソースを作成した場合、インデックスは削除されません。

使用中のナレッジ ソースを削除しようとすると、アクションは失敗し、影響を受けるナレッジ ベースの一覧が返されます。

ナレッジ ソースを削除するには:

1. 検索サービスのすべてのナレッジ ベースの一覧を取得します。

   ### Get knowledge bases
   GET {{search-endpoint}}/knowledgebases?api-version=2025-11-01-preview&$select=name
   api-key: {{api-key}}
   

   応答の例は次のようになります。

    {
        "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
        "value": [
        {
            "name": "my-kb"
        },
        {
            "name": "my-kb-2"
        }
        ]
    }
   

2. 個々のナレッジベース定義を取得して、ナレッジソースの参照を確認します。

   ### Get a knowledge base definition
   GET {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
   api-key: {{api-key}}
   

   応答の例は次のようになります。

    {
      "name": "my-kb",
      "description": null,
      "retrievalInstructions": null,
      "answerInstructions": null,
      "outputMode": null,
      "knowledgeSources": [
        {
          "name": "my-blob-ks",
        }
      ],
      "models": [],
      "encryptionKey": null,
      "retrievalReasoningEffort": {
        "kind": "low"
      }
    }
   

3. ナレッジ ベースを削除するか、複数のソースがある場合はナレッジ ソースを削除してナレッジ ベースを更新 します。 この例では、削除を示します。

   ### Delete a knowledge base
   DELETE {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
   api-key: {{api-key}}
   

4. ナレッジ ソースを削除します。

   ### Delete a knowledge source
   DELETE {{search-endpoint}}/knowledgesources/{{knowledge-source-name}}?api-version=2025-11-01-preview
   api-key: {{api-key}}