建立遠端 SharePoint 知識來源（預覽）

註

Azure AI 搜尋服務可透過 Azure 入口網站、REST API 及 Azure SDK 取得。它同時也是 Foundry IQ 的基礎，這是一個管理式知識層，能將企業內容轉化為可重複使用、權限感知的知識庫，供 Microsoft Foundry 入口網站中的代理使用。

Important

標記（預覽）的功能、能力或屬性不受服務等級協議涵蓋，也不建議用於生產工作負載，且在正式上架前可能會有所變動或受限。 Azure AI 搜尋服務預覽條款適用於所有預覽功能，無論是獨立功能還是正式推出功能的一部分。

遠端 SharePoint 知識來源（預覽）使用 Copilot Retrieval API（預覽版）直接從 Microsoft 365 中的 SharePoint 查詢文字內容。知識來源獨立建立，並在知識庫中被引用，並在執行時查詢知識庫時作為基礎資料。

為了限制網站或限制搜尋，請設定篩選表達式以 URL、日期範圍、檔案類型及其他元資料為範圍。來電者的身份必須同時被 Azure 租戶與 Microsoft 365 租戶識別，因為檢索引擎會代表使用者查詢 SharePoint。

與索引知識來源不同，遠端 SharePoint 知識來源會在檢索時直接查詢即時資料。不需要搜尋索引或連線字串，使用費用會透過 Microsoft 365 和 Copilot 授權計費。

使用支援

Azure portal	Microsoft Foundry 入口	.NET SDK	Python SDK	Java 開發套件	JavaScript SDK	REST API
✔️	✔️	✔️	✔️	✔️	✔️	✔️

先決條件

任何區域內提供主動檢索的 Azure AI 搜尋服務服務。
SharePoint 在 Microsoft 365 租戶中，且與 Azure 同屬 Microsoft Entra ID 租用戶。
使用 Microsoft 365 Copilot 授權，用於查詢時存取 SharePoint 內容。
允許建立知識來源。設定無金鑰驗證，並將搜尋服務參與者角色指派給您的使用者帳戶（建議），或使用管理員 API 金鑰。

最新的 Azure.Search.Documents 預覽套件：dotnet add package Azure.Search.Documents --prerelease
對於無鑰匙認證，套件如下 Azure.Identity ： dotnet add package Azure.Identity

最新的 azure-search-documents 預覽套件：pip install --pre azure-search-documents
對於無鑰匙認證，套件如下 azure-identity ： pip install azure-identity

搜尋服務 REST API 的 2026-08-01 預覽版。
對於無金鑰認證，請在Authorization每個 HTTP 請求的標頭中加入 Microsoft Entra ID 令牌。

限制與考量

遠端 SharePoint 知識來源受 Copilot Retrieval API 及 Azure AI 搜尋服務限制。

Copilot 檢索 API

以下 Copilot Retrieval API 限制同樣適用於遠端 SharePoint 知識來源：

沒有支援 Copilot 連接器或 OneDrive 內容。內容僅從 SharePoint 網站擷取。
每位用戶每小時最多 200 個請求。
查詢字元限制為 1,500 個字元。
混合查詢僅支援以下檔案副檔名：.doc、 .docx.pptx.pdf.aspx.one及。
不支援多模態檢索（非文字內容，包括表格、圖片和圖表）。
查詢最多可獲得25個結果。
結果會由 Copilot Retrieval API 以未排序的狀態回傳。
無效關鍵字查詢語言（KQL）過濾器表達式會被忽略，查詢繼續執行，無需過濾器。

Azure AI 搜尋服務

當你查詢知識庫時，Azure AI 搜尋服務一次只能執行有限數量的遠端 SharePoint 查詢。限制取決於定價模式：

專用：每個服務複本一次只會針對擷取要求中所選的所有遠端 SharePoint 知識來源執行一個查詢。額外的查詢會等待可用的副本，這會增加延遲。為了提升查詢吞吐量，請加入副本。
Serverless（預覽版）：Azure AI 搜尋服務會一次執行一個查詢，針對擷取要求中選取的所有遠端 SharePoint 知識來源進行查詢。其他查詢仍在等待中。無伺服器會自動管理容量，所以你無法提升查詢吞吐量。

檢查現有的知識來源

知識來源是一個頂層且可重複使用的物件。了解現有的知識來源對於重用或命名新物件都很有幫助。

執行以下程式碼，依名稱和類型列出知識來源。

// 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}");
}

參考資料：SearchIndexClient

# List knowledge sources by name and type
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

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

for ks in index_client.list_knowledge_sources():
    print(f"  - {ks.name} ({ks.kind})")

參考資料：SearchIndexClient

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version={{api-version}}&$select=name,kind
Authorization: Bearer {{token}}

參考資料：知識來源列表

你也可以以名稱回傳單一知識來源，以檢視其 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));

參考資料：SearchIndexClient

# Get a knowledge source definition
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
import json

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

ks = index_client.get_knowledge_source("knowledge_source_name")
print(json.dumps(ks.as_dict(), indent = 2))

參考資料：SearchIndexClient

### Get a knowledge source definition
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
Authorization: Bearer {{token}}

參考資料：知識來源 - 取得

以下 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 知識來源。

// 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.Identity;

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

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.");

參考資料：SearchIndexClient，RemoteSharePointKnowledgeSource

# Create a remote SharePoint knowledge source
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import RemoteSharePointKnowledgeSource, RemoteSharePointKnowledgeSourceParameters

index_client = SearchIndexClient(endpoint = "<search-endpoint>", credential = DefaultAzureCredential())

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.")

參考資料：SearchIndexClient

### Create a remote SharePoint knowledge source
PUT {{search-endpoint}}/knowledgesources/my-remote-sharepoint-ks?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
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
    }
}

參考資料：知識來源 - 建立或更新

濾波器表達式範例

在 filterExpression 中並不支援所有 SharePoint 屬性。有關支援屬性的清單，請參閱 API 參考文獻。關於可查詢的屬性，請參見可查詢物件。

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

範例	濾波器表達式
依 ID 篩選至單一網站	`"filterExpression": "SiteID:\"00aa00aa-bb11-cc22-dd33-44ee44ee44ee\""`
依 ID 篩選多個網站	`"filterExpression": "SiteID:\"00aa00aa-bb11-cc22-dd33-44ee44ee44ee\" OR SiteID:\"11bb11bb-cc22-dd33-ee44-55ff55ff55ff\""`
篩選特定路徑下的檔案	`"filterExpression": "Path:\"https://my-demo.sharepoint.com/sites/mysite/Shared Documents/en/mydocs\""`
篩選到特定日期範圍	`"filterExpression": "LastModifiedTime >= 2024-07-22 AND LastModifiedTime <= 2025-01-08"`
篩選特定檔案類型的文件	`"filterExpression": "FileExtension:\"docx\" OR FileExtension:\"pdf\" OR FileExtension:\"pptx\""`
篩選具有特定資訊保護標籤的檔案	`"filterExpression": "InformationProtectionLabelId:\"f0ddcc93-d3c0-4993-b5cc-76b0a283e252\""`

指派至知識庫

如果你對知識來源感到滿意，就把它加入知識庫。

查詢知識庫

知識庫設定完成後，呼叫檢索動作或 MCP 端點查詢SharePoint內容。遠端 SharePoint 具備針對原始碼的行為，包括查詢時篩選、查詢表述、回應欄位及權限強制執行。

在查詢時套用 KQL 濾波器

您可以在擷取要求的 FilterExpressionAddOn 中傳遞 KnowledgeSourceParams，以便在查詢時套用 KQL 篩選器。如果你在 retrieve 請求中指定 FilterExpressionAddOn，而在知識來源定義中指定 FilterExpression，那麼這兩個篩選器會被進行 AND 運算。

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent("contoso product planning")
        }
    ) { Role = "user" }
);
retrievalRequest.KnowledgeSourceParams.Add(
    new RemoteSharePointKnowledgeSourceParams("my-remote-sharepoint-ks")
    {
        FilterExpressionAddOn = "filetype:docx"
    }
);

var result = await kbClient.RetrieveAsync(
    retrievalRequest, xMsQuerySourceAuthorization: token
);

參考資料：KnowledgeBaseRetrievalClient， KnowledgeBaseRetrievalRequest

您可以在擷取要求的 filter_expression_add_on 中傳遞 knowledge_source_params，以便在查詢時套用 KQL 篩選器。如果你在 retrieve 請求中指定 filter_expression_add_on，而在知識來源定義中指定 filter_expression，那麼這兩個篩選器會被進行 AND 運算。

from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseMessage,
    KnowledgeBaseMessageTextContent,
    KnowledgeBaseRetrievalRequest,
    RemoteSharePointKnowledgeSourceParams,
)

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[
                KnowledgeBaseMessageTextContent(
                    text="contoso product planning"
                )
            ],
        )
    ],
    knowledge_source_params=[
        RemoteSharePointKnowledgeSourceParams(
            knowledge_source_name="my-remote-sharepoint-ks",
            filter_expression_add_on="filetype:docx",
        )
    ],
)

result = kb_client.retrieve(
    retrieval_request=request,
    x_ms_query_source_authorization=token,
)

參考資料：KnowledgeBaseRetrievalClient， KnowledgeBaseRetrievalRequest

您可以在擷取要求的 filterExpressionAddOn 中傳遞 knowledgeSourceParams，以便在查詢時套用 KQL 篩選器。如果你在 retrieve 請求中指定 filterExpressionAddOn，而在知識來源定義中指定 filterExpression，那麼這兩個篩選器會被進行 AND 運算。

### Retrieve knowledge base content
POST {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json
x-ms-query-source-authorization: {{user-access-token}}

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "contoso product planning" }
            ]
        }
    ],
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "my-remote-sharepoint-ks",
            "kind": "remoteSharePoint",
            "filterExpressionAddOn": "filetype:docx"
        }
    ]
}

參考資料：知識檢索 - 檢索

撰寫有效的查詢

詢問內容本身的查詢比詢問檔案位置或最後更新時間更有效。例如，「Ignite 2024 的重磅演講文件在哪裡」的搜索可能沒有結果，因為內容本身並未透露其位置。 FilterExpression on metadata 是處理檔案位置或特定日期查詢的更好方法。

詢問內容本身的查詢比詢問檔案位置或最後更新時間更有效。例如，「Ignite 2024 的重磅演講文件在哪裡」的搜索可能沒有結果，因為內容本身並未透露其位置。 filter_expression on metadata 是處理檔案位置或特定日期查詢的更好方法。

詢問內容本身的查詢比詢問檔案位置或最後更新時間更有效。例如，「Ignite 2024 的重磅演講文件在哪裡」的搜索可能沒有結果，因為內容本身並未透露其位置。 filterExpression on metadata 是處理檔案位置或特定日期查詢的更好方法。

「Ignite 2024 的專題演講文件為何」是更有效的提問。回應包含綜合答案、查詢活動與標記數，以及網址和其他元資料。

SharePoint 專屬回應欄位

遠端SharePoint結果包含其他知識來源類型不會出現的欄位，如 resourceMetadata、webUrl 以及 searchSensitivityLabelInfo。

{
    "resourceMetadata": {
        "Author": "Nuwan Amarathunga;Nurul Izzati",
        "Title": "Ignite 2024 Keynote Address"
    },
    "rerankerScore": 2.489522,
    "webUrl": "https://contoso-my.sharepoint.com/keynotes/Documents/Keynote-Ignite-2024.docx",
    "searchSensitivityLabelInfo": {
        "displayName": "Confidential\\Contoso Extended",
        "sensitivityLabelId": "aaaaaaaa-0b0b-1c1c-2d2d-333333333333",
        "tooltip": "Data is classified and protected.",
        "priority": 5,
        "color": "#FF8C00",
        "isEncrypted": true
    }
}

在查詢時強制執行權限

遠端 SharePoint 知識來源可在查詢時強制執行 SharePoint 權限。要啟用此篩選功能，請在擷取請求中包含終端使用者的存取權杖。檢索引擎會將憑證傳給 Copilot Retrieval API，該 API 會查詢 SharePoint，並只回傳使用者有權限的內容。 SharePoint 權限與 Microsoft Purview 敏感度標籤皆被尊重。

由於遠端 SharePoint 不使用搜尋索引，因此不需要設定資料擷取時間的權限。唯一的要求是存取權杖。

如需了解如何傳遞權杖，請參閱查詢時強制執行權限（預覽）。

刪除知識來源

在刪除知識來源之前，必須刪除所有引用該來源的知識庫，或更新知識庫定義以移除該參考。對於產生索引與索引管線的知識來源，所有 產生的物件 也會被刪除。不過，如果你用現有的索引建立知識來源，你的索引不會被刪除。

如果你嘗試刪除正在使用的知識來源，該動作會失敗，並回傳一份受影響的知識庫清單。

刪除知識來源：

取得你搜尋服務中所有知識庫的清單。

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

參考資料：SearchIndexClient

一個範例回應可能如下：

 {
     "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
     "value": [
     {
         "name": "my-kb"
     },
     {
         "name": "my-kb-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);

參考資料：SearchIndexClient

一個範例回應可能如下：

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

要麼刪除知識庫，要麼如果你有多個知識來源，就更新知識庫來移除該來源。這個例子顯示刪除。

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.");

參考資料：SearchIndexClient

刪除知識來源。

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

參考資料：SearchIndexClient

取得你搜尋服務中所有知識庫的清單。

# Get knowledge bases
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

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

print("Knowledge Bases:")
for kb in index_client.list_knowledge_bases():
    print(f"  - {kb.name}")

參考資料：SearchIndexClient

一個範例回應可能如下：

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

取得一個獨立的知識庫定義，以檢查是否有知識來源的參考。

# Get a knowledge base definition
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
kb = index_client.get_knowledge_base("knowledge_base_name")
print(kb)

參考資料：SearchIndexClient

一個範例回應可能如下：

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

要麼刪除知識庫，要麼如果你有多個知識來源，就更新知識庫來移除該來源。這個例子顯示刪除。

# 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.")

參考資料：SearchIndexClient

刪除知識來源。

# 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.")

參考資料：SearchIndexClient

取得你搜尋服務中所有知識庫的清單。

### Get knowledge bases
GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name
Authorization: Bearer {{token}}

參考資料：知識庫列表

一個範例回應可能如下：

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

取得一個獨立的知識庫定義，以檢查是否有知識來源的參考。

### Get a knowledge base definition
GET {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
Authorization: Bearer {{token}}

參考資料：知識庫 - 取得

一個範例回應可能如下：

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

要麼刪除知識庫，要麼如果你有多個知識來源，就更新知識庫來移除該來源。這個例子顯示刪除。
```
### Delete a knowledge base
DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
Authorization: Bearer {{token}}
```
參考資料：知識庫 - 刪除

刪除知識來源。

### Delete a knowledge source
DELETE {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
Authorization: Bearer {{token}}

參考資料：知識來源 - 刪除

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-17

建立遠端 SharePoint 知識來源（預覽）

使用支援

先決條件

限制與考量

Copilot 檢索 API

Azure AI 搜尋服務

檢查現有的知識來源

建立知識來源

濾波器表達式範例

指派至知識庫

查詢知識庫

在查詢時套用 KQL 濾波器

撰寫有效的查詢

SharePoint 專屬回應欄位

在查詢時強制執行權限

刪除知識來源

相關內容

意見反應

其他資源