你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

创建远程SharePoint知识源（预览版）

注意

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。它也是 Foundry IQ 的基础；Foundry IQ 是一个托管式知识层，可将企业内容转化为供 Microsoft Foundry 门户中的智能体使用的、可复用且具备权限感知能力的知识库。

Important

标记为“预览”的特性、功能或属性不受服务级别协议 (SLA) 保障，不建议用于生产工作负载，并且在正式发布之前可能会更改或受到限制。 Azure AI 搜索预览条款适用于所有预览功能，无论是独立功能还是正式版功能的一部分。

远程SharePoint知识源（预览版）使用Copilot检索 API（预览版）直接从Microsoft 365中的SharePoint查询文本内容。知识库是在运行时查询知识库时独立创建的、在知识库中引用的，并用作基础数据。

若要限制站点或搜索，请将筛选器表达式设置为按 URL、日期范围、文件类型和其他元数据进行限定。调用方的身份必须由Azure租户和Microsoft 365租户识别，因为检索引擎代表用户SharePoint查询。

与索引知识源不同，远程SharePoint知识源在检索时直接查询实时数据。无需搜索索引或连接字符串。

使用支持

Azure 门户	Microsoft Foundry 门户	.NET SDK	Python SDK	Java SDK	JavaScript SDK	REST API
✔️	✔️	✔️	✔️	✔️	✔️	✔️

先决条件

在任意提供代理检索功能的区域中提供的 Azure AI 搜索服务。
SharePoint 位于与 Azure 处于同一 Microsoft Entra ID 租户下的 Microsoft 365 租户中。
对于每个查询 SharePoint 内容的用户，都需要具备以下两者之一：要么是包含检索 API 使用权限的智能 Microsoft 365 Copilot 副驾驶® 附加许可证，要么为该用户启用检索 API 即用即付消耗（预览版）。

若要启用即用即付，您需要具有 Microsoft 365 管理员访问权限，以及对状态正常的 Azure 订阅具有 所有者 或 参与者 访问权限。还需要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

搜索服务 REST API 的 2026-08-01-preview 版本。
对于无密钥身份验证，请在每个 HTTP 请求的标头中包含AuthorizationMicrosoft 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知识源上运行一个查询。其他查询等待可用副本，这会增加延迟。若要增加查询吞吐量，请添加副本。
无服务器（预览版）：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}");
}

Reference：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})")

Reference：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));

Reference：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))

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

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

Reference：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 筛选器。如果在检索请求中指定了 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 筛选器。如果在检索请求中指定了 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 筛选器。如果在检索请求中指定了 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 是更好的方法。

询问内容本身的查询比有关文件所在位置或上次更新时间的问题更有效。例如，“Ignite 2024 的主旨文档在哪里”可能不返回任何结果，因为内容本身不会透露其位置。针对文件位置或特定日期查询，使用元数据上的 filter_expression 是更好的方法。

询问内容本身的查询比有关文件所在位置或上次更新时间的问题更有效。例如，“Ignite 2024 的主旨文档在哪里”可能不返回任何结果，因为内容本身不会透露其位置。针对文件位置或特定日期查询，使用元数据上的 filterExpression 是更好的方法。

一个更有效的问题是“Ignite 2024 的主题演讲文档是什么”。响应包括合成的答案、查询活动和令牌计数，以及 URL 和其他元数据。

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

Reference：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);

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

Reference：SearchIndexClient

删除知识源。

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

Reference：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}")

Reference：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)

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

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

Reference：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}}

参考：知识源 - 删除

反馈

此页面是否有帮助？

上次更新时间为 2026-10-02

创建远程SharePoint知识源（预览版）

使用支持

先决条件

限制和注意事项

Copilot 检索 API

Azure AI 搜索

检查现有知识源

创建知识源

筛选器表达式示例

分配给知识库

查询知识库

在查询时应用 KQL 筛选器

编写有效的查询

SharePoint 特定响应字段

在查询时强制实施权限

删除知识源

相关内容

反馈

其他资源