建立遠端 SharePoint 知識來源

遠端 SharePoint 知識來源使用 Copilot Retrieval API 直接從 Microsoft 365 中的 SharePoint 查詢文字內容，並將結果回傳至代理檢索引擎，以便合併、排名及回應表述。 這個知識來源沒有使用搜尋索引，只查詢文字內容。

在查詢時，遠端 SharePoint 知識來源會代表使用者身份呼叫 Copilot Retrieval API，因此知識來源定義中不需要連結字串。 使用者可存取的所有內容均屬於知識檢索的範疇。 若要限制網站或限制搜尋，請設定 篩選表達式。 你的 Azure 租戶和 Microsoft 365 租戶必須使用同一個 Microsoft Entra ID 租戶，且來電者的身份必須被兩個租戶識別。

• 你可以使用篩選器來依據網址、日期範圍、檔案類型及其他元資料來範圍搜尋。

• SharePoint 權限與 Purview 標籤在內容請求中會被尊重。

• 使用費用透過 Microsoft 365 和 Copilot 授權來計費。

就像其他知識來源一樣，你可以在 知識庫 中指定遠端 SharePoint 知識來源，並在代理或聊天機器人在查詢時呼叫 擷取動作 時，將結果作為基礎資料。

先決條件

• Azure AI 搜尋可在任何 提供代理檢索的區域。 你必須 啟用語意排序器。

• SharePoint 在 Microsoft 365 租戶中，且與 Azure 同屬 Microsoft Entra ID 租用戶。

• 用於本地開發的個人存取權杖，或用戶端應用程式的使用者身份。

• .NET SDK 用戶端函式庫的最新預覽版Azure.Search.Documents。

• 在 Azure AI Search 上建立及使用物件的權限。 我們建議使用 基於角色的存取，但如果角色指派不可行，也可以使用 API 金鑰 。

在本地開發時，代理檢索引擎會利用你的存取權杖代你呼叫 SharePoint。 欲了解更多關於在請求中使用個人存取權杖的資訊，請參閱 「Connect to Azure AI Search」。

局限性

Copilot Retrieval API 中的以下限制適用於遠端 SharePoint 知識來源。

• 沒有支援 Copilot 連接器或 OneDrive 內容。 內容僅從 SharePoint 網站擷取。

• 每位用戶每小時最多 200 個請求。

• 查詢字元限制為 1,500 個字元。

• 混合查詢僅支援以下檔案副檔名：.doc、.docx、.pptx、.pdf、.aspx 和 .one。

• 不支援多模態檢索（非文字內容，包括表格、圖片和圖表）。

• 查詢最多可獲得25個結果。

• Copilot Retrieval 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}");
}

您也可以按名稱傳回單一知識來源以檢閱其 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 搜尋和 Azure OpenAI。 Azure AI Search 會用你的存取權杖代表你連接到 Microsoft 365 中的 SharePoint。 你只能取得你被允許存取的內容。 欲了解更多關於取得個人存取權杖及其他數值的資訊，請參閱 「Connect to 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 知識來源。

濾波器表達式範例

並非所有 SharePoint 屬性都支援於filterExpression。 有關支援屬性的清單，請參閱 API 參考文獻。 這裡有更多關於可查詢屬性的資訊，可以用來篩選： 可查詢屬性。

想了解更多關於 KQL 濾波器的 資訊，請參考語法參考。

指派到知識庫

如果你對知識來源感到滿意，就繼續下一步：在 知識庫中指定知識來源。

知識庫設定完成後，使用 擷取動作 查詢知識來源。

查詢知識庫

知識庫上的 檢索動作 提供授權存取 Microsoft 365 內容的使用者身份。

Azure AI Search 使用存取權杖來代表使用者身份呼叫 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，則會一起取篩選條件的交集。

詢問內容本身的查詢，比起詢問檔案位置或最後更新時間的查詢，更有效率。 例如，如果你問「Ignite 2024 的主題說明文件在哪裡？」可能會得到「未找到相關內容」，因為內容本身並未透露其位置。 在檔案位置或特定日期查詢時，對元資料進行篩選是更好的解決方案。

更值得提出的問題是：「Ignite 2024 的主題簡報資料是什麼？」 回應包含綜合答案、查詢活動與標記數，以及網址和其他元資料。

{
    "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 Retrieval API 直接從 Microsoft 365 中的 SharePoint 查詢文字內容，並將結果回傳至代理檢索引擎，以便合併、排名及回應表述。 這個知識來源沒有使用搜尋索引，只查詢文字內容。

在查詢時，遠端 SharePoint 知識來源會代表使用者身份呼叫 Copilot Retrieval API，因此知識來源定義中不需要連結字串。 使用者可存取的所有內容均屬於知識檢索的範疇。 若要限制網站或限制搜尋，請設定 篩選表達式。 你的 Azure 租戶和 Microsoft 365 租戶必須使用同一個 Microsoft Entra ID 租戶，且來電者的身份必須被兩個租戶識別。

• 你可以使用篩選器來依據網址、日期範圍、檔案類型及其他元資料來範圍搜尋。

• SharePoint 權限與 Purview 標籤在內容請求中會被尊重。

• 使用費用透過 Microsoft 365 和 Copilot 授權來計費。

就像其他知識來源一樣，你可以在 知識庫 中指定遠端 SharePoint 知識來源，並在代理或聊天機器人在查詢時呼叫 擷取動作 時，將結果作為基礎資料。

先決條件

• Azure AI 搜尋可在任何 提供代理檢索的區域。 你必須 啟用語意排序器。

• SharePoint 在 Microsoft 365 租戶中，且與 Azure 同屬 Microsoft Entra ID 租用戶。

• 用於本地開發的個人存取權杖，或用戶端應用程式的使用者身份。

• Python 用戶端函式庫的最新預覽版本azure-search-documents。

• 在 Azure AI Search 上建立及使用物件的權限。 我們建議使用 基於角色的存取，但如果角色指派不可行，也可以使用 API 金鑰 。

在本地開發時，代理檢索引擎會利用你的存取權杖代你呼叫 SharePoint。 欲了解更多關於在請求中使用個人存取權杖的資訊，請參閱 「Connect to Azure AI Search」。

局限性

Copilot Retrieval API 中的以下限制適用於遠端 SharePoint 知識來源。

• 沒有支援 Copilot 連接器或 OneDrive 內容。 內容僅從 SharePoint 網站擷取。

• 每位用戶每小時最多 200 個請求。

• 查詢字元限制為 1,500 個字元。

• 混合查詢僅支援以下檔案副檔名：.doc、.docx、.pptx、.pdf、.aspx 和 .one。

• 不支援多模態檢索（非文字內容，包括表格、圖片和圖表）。

• 查詢最多可獲得25個結果。

• Copilot Retrieval 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))

您也可以按名稱傳回單一知識來源以檢閱其 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 搜尋和 Azure OpenAI。 Azure AI Search 會用你的存取權杖代表你連接到 Microsoft 365 中的 SharePoint。 你只能取得你被允許存取的內容。 欲了解更多關於取得個人存取權杖及其他數值的資訊，請參閱 「Connect to 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 知識來源。

濾波器表達式範例

並非所有 SharePoint 屬性都支援於filterExpression。 有關支援屬性的清單，請參閱 API 參考文獻。 這裡有更多關於可查詢屬性的資訊，可以用來篩選： 可查詢屬性。

想了解更多關於 KQL 濾波器的 資訊，請參考語法參考。

指派到知識庫

如果你對知識來源感到滿意，就繼續下一步：在 知識庫中指定知識來源。

知識庫設定完成後，使用 擷取動作 查詢知識來源。

查詢知識庫

知識庫上的 檢索動作 提供授權存取 Microsoft 365 內容的使用者身份。

Azure AI Search 使用存取權杖來代表使用者身份呼叫 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，則會一起取篩選條件的交集。

詢問內容本身的查詢，比起詢問檔案位置或最後更新時間的查詢，更有效率。 例如，如果你問「Ignite 2024 的主題說明文件在哪裡？」可能會得到「未找到相關內容」，因為內容本身並未透露其位置。 在檔案位置或特定日期查詢時，對元資料進行篩選是更好的解決方案。

更值得提出的問題是：「Ignite 2024 的主題簡報資料是什麼？」 回應包含綜合答案、查詢活動與標記數，以及網址和其他元資料。

{
    "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 Retrieval API 直接從 Microsoft 365 中的 SharePoint 查詢文字內容，並將結果回傳至代理檢索引擎，以便合併、排名及回應表述。 這個知識來源沒有使用搜尋索引，只查詢文字內容。

在查詢時，遠端 SharePoint 知識來源會代表使用者身份呼叫 Copilot Retrieval API，因此知識來源定義中不需要連結字串。 使用者可存取的所有內容均屬於知識檢索的範疇。 若要限制網站或限制搜尋，請設定 篩選表達式。 你的 Azure 租戶和 Microsoft 365 租戶必須使用同一個 Microsoft Entra ID 租戶，且來電者的身份必須被兩個租戶識別。

• 你可以使用篩選器來依據網址、日期範圍、檔案類型及其他元資料來範圍搜尋。

• SharePoint 權限與 Purview 標籤在內容請求中會被尊重。

• 使用費用透過 Microsoft 365 和 Copilot 授權來計費。

就像其他知識來源一樣，你可以在 知識庫 中指定遠端 SharePoint 知識來源，並在代理或聊天機器人在查詢時呼叫 擷取動作 時，將結果作為基礎資料。

先決條件

• Azure AI 搜尋可在任何 提供代理檢索的區域。 你必須 啟用語意排序器。

• SharePoint 在 Microsoft 365 租戶中，且與 Azure 同屬 Microsoft Entra ID 租用戶。

• 用於本地開發的個人存取權杖，或用戶端應用程式的使用者身份。

• 搜尋服務 REST API 的 2025-11-01 預覽 版。

• 在 Azure AI Search 上建立及使用物件的權限。 我們建議使用 基於角色的存取，但如果角色指派不可行，也可以使用 API 金鑰 。

在本地開發時，代理檢索引擎會利用你的存取權杖代你呼叫 SharePoint。 欲了解更多關於在請求中使用個人存取權杖的資訊，請參閱 「Connect to Azure AI Search」。

局限性

Copilot Retrieval API 中的以下限制適用於遠端 SharePoint 知識來源。

• 沒有支援 Copilot 連接器或 OneDrive 內容。 內容僅從 SharePoint 網站擷取。

• 每位用戶每小時最多 200 個請求。

• 查詢字元限制為 1,500 個字元。

• 混合查詢僅支援以下檔案副檔名：.doc、.docx、.pptx、.pdf、.aspx 和 .one。

• 不支援多模態檢索（非文字內容，包括表格、圖片和圖表）。

• 查詢最多可獲得25個結果。

• Copilot Retrieval API 會以未排序方式回傳結果。

• 無效關鍵字查詢語言（KQL）過濾器表達式會被忽略，查詢繼續執行而無需該過濾器。

檢查現有的知識來源

知識來源是一個頂層、可重複使用的物件。 瞭解現有的知識來源有助於重複使用或命名新物件。

使用 知識來源 - 取得 （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}}

您也可以按名稱傳回單一知識來源以檢閱其 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"
    ]
  }
}

建立知識來源

使用 Knowledge Sources - Create 或 Update（REST API） 來建立遠端 SharePoint 知識來源。

API 金鑰 用於您的客戶端連接 Azure AI 搜尋和 Azure OpenAI。 Azure AI Search 會用你的存取權杖代表你連接到 Microsoft 365 中的 SharePoint。 你只能取得你被允許存取的內容。 欲了解更多關於取得個人存取權杖及其他數值的資訊，請參閱 「Connect to 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 知識來源。

濾波器表達式範例

並非所有 SharePoint 屬性都支援於filterExpression。 有關支援屬性的清單，請參閱 API 參考文獻。 這裡有更多關於可查詢屬性的資訊，可以用來篩選： 可查詢屬性。

想了解更多關於 KQL 濾波器的 資訊，請參考語法參考。

指派到知識庫

如果你對知識來源感到滿意，就繼續下一步：在 知識庫中指定知識來源。

知識庫設定完成後，使用 擷取動作 查詢知識來源。

查詢知識庫

知識庫上的 檢索動作 提供授權存取 Microsoft 365 內容的使用者身份。

Azure AI Search 使用存取權杖來代表使用者身份呼叫 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，則會一起取篩選條件的交集。

詢問內容本身的查詢，比起詢問檔案位置或最後更新時間的查詢，更有效率。 例如，如果你問「Ignite 2024 的主題說明文件在哪裡？」可能會得到「未找到相關內容」，因為內容本身並未透露其位置。 在檔案位置或特定日期查詢時，對元資料進行篩選是更好的解決方案。

更值得提出的問題是：「Ignite 2024 的主題簡報資料是什麼？」 回應包含綜合答案、查詢活動與標記數，以及網址和其他元資料。

{
    "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}}