註
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
Important
遠端 SharePoint 知識來源目前處於公開預覽階段,並受 Microsoft Azure 預覽補充使用條款的約束。
有關此功能專屬的預覽條款,請參閱 預覽功能。
有關連接外部資料來源時適用的術語,請參閱「外部資料來源」。
遠端 SharePoint 知識來源(預覽版)使用 Copilot Retrieval API(預覽版)從 Microsoft 365 混合索引擷取 SharePoint 文字。 知識來源 會獨立建立,並在 知識庫中被引用,並在 執行時查詢知識庫時作為基礎資料。
為了限制網站或限制搜尋,請設定 篩選表達 式以 URL、日期範圍、檔案類型及其他元資料為範圍。 來電者的身份必須同時被 Azure 租戶與 Microsoft 365 租戶識別,因為檢索引擎會代表使用者查詢 SharePoint。
與索引式知識來源不同,從遠端 SharePoint 擷取會使用 SharePoint 的權限模型和 Microsoft 365 治理控管,無需另外建立搜尋索引,也不需對內容和 ACL 進行排程同步。 這種方式避免了額外的跨平台同步延遲。 新鮮度仍依賴 Microsoft 365 處理。 你不需要 連接字串。
關於授權、新鮮度與操作權衡,請參閱 「比較遠端、索引及客戶管理推播擷取」。
使用支援
| Azure portal | Microsoft Foundry 入口網站 | .NET SDK | Python SDK | Java SDK | JavaScript SDK | REST API |
|---|---|---|---|---|---|---|
| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
先決條件
在任何提供 agentic retrieval 的區域中的 Foundry IQ(Azure AI 搜尋服務)服務。
SharePoint 在 Microsoft 365 租戶中,且與 Azure 同屬 Microsoft Entra ID 租用戶。
每位查詢 SharePoint 內容的使用者,都需啟用包含 Retrieval API 使用的 Microsoft 365 Copilot 附加授權,或為該使用者啟用 Retrieval API 隨用隨付使用量(預覽版)。
要啟用隨用隨付,您需要 Microsoft 365 管理員存取權,以及對狀態良好的 Azure 訂閱具有Owner或Contributor存取權。 你還需要一個 Azure 資源群組。 您的租戶在啟用前及按使用量付費期間,必須至少持有一個 Microsoft 365 Copilot 授權。
對於沒有 Copilot 附加授權的使用者,請啟用隨用付費,並在 Microsoft 365 系統管理中心 使用該 Azure 訂閱設定帳單。 兩種付款方式都使用相同的遠端 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
Search Service REST API 的 2026-11-01-preview 版本。
對於無金鑰認證,請在
Authorization每個 HTTP 請求的標頭中加入 Microsoft Entra ID 令牌。
限制與考量
遠端 SharePoint 知識來源受 Copilot Retrieval API 與 Foundry IQ 的限制。
Copilot 檢索 API
以下 Copilot Retrieval API 限制同樣適用於遠端 SharePoint 知識來源:
沒有支援 Copilot 連接器或 OneDrive 內容。 內容僅從 SharePoint 網站擷取。
每位用戶每小時最多 200 個請求。
查詢字元限制為 1,500 個字元。
混合查詢僅支援以下檔案副檔名:
.doc、.docx.pptx.pdf.aspx.one及 。不支援多模態檢索(非文字內容,包括表格、圖片和圖表)。
查詢最多可獲得25個結果。
結果會由 Copilot Retrieval API 以未排序的狀態回傳。
無效關鍵字查詢語言(KQL)過濾器表達式會被忽略,查詢繼續執行,無需過濾器。
Foundry IQ
當您查詢知識庫時,Foundry IQ 一次只能執行有限數量的遠端 SharePoint 查詢。 限制取決於定價模式:
專用:每個服務複本會一次對所有選取的遠端 SharePoint 知識來源執行查詢。 額外的查詢會等待可用的副本,這會增加延遲。 為了提升查詢吞吐量,請加入副本。
無伺服器:Foundry IQ 會一次對所有為擷取請求所選取的遠端 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}");
}
# 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})")
### 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));
# 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))
### 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.");
# 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.")
### Create a remote SharePoint knowledge source
PUT {{search-endpoint}}/knowledgesources/my-remote-sharepoint-ks?api-version=2026-11-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-11-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 不使用獨立的 Foundry IQ 索引,因此您不需要設定匯入時間權限。 完成 先決條件 ,並在每次取回請求中包含使用者的權杖。
如需了解如何傳遞權杖,請參閱 查詢時強制執行權限(預覽)。
刪除知識來源
在刪除知識來源之前,必須刪除所有引用該來源的知識庫,或更新知識庫定義以移除該參考。 對於產生索引與索引管線的知識來源,所有 產生的物件 也會被刪除。 不過,如果你用現有的索引建立知識來源,你的索引不會被刪除。
如果你嘗試刪除正在使用的知識來源,該動作會失敗,並回傳一份受影響的知識庫清單。
刪除知識來源:
取得您 Foundry IQ 服務中所有知識庫的清單。
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}"); }一個範例回應可能如下:
{ "@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);一個範例回應可能如下:
{ "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.");刪除知識來源。
await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName); System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");
取得您 Foundry IQ 服務中所有知識庫的清單。
# 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}")一個範例回應可能如下:
{ "@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)一個範例回應可能如下:
{ "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.")刪除知識來源。
# 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.")
取得您 Foundry IQ 服務中所有知識庫的清單。
### 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}}參考資料:知識來源 - 刪除