使用SharePoint索引器根据用户访问权限引入权限元数据并筛选搜索结果（预览版）

SharePoint权限元数据引入（预览版）使用Azure AI 搜索索引器来保留权限元数据，例如访问控制列表（ACL），以及Microsoft 365中SharePoint的其他内容。 索引器将权限存储为每个索引文档的元数据。 在查询时，用户仅接收他们有权访问的文档。

先决条件

• 可计费层（任何区域中的“基本”层或更高层）上的 Azure AI 搜索。

• Microsoft 365 中的 SharePoint 网站、库、文件夹和配置了权限的文件。

• 完成 SharePoint 索引器文档中的所有配置步骤，并应用本文中所述的特定于 ACL 的要求。

• 配置 Microsoft Entra 应用程序权限以及适用于你的场景的凭据。 请参阅 ACL 方案的权限。 ACL 引入需要应用程序权限。 不支持委派的权限。 有关应用程序与委托决策，请参阅 “选择权限设置”。

• REST API 版本 2026-08-01-preview 或等效的预览版 SDK 包。

限制

• 增量 ACL 更新需要 2026-05-01-preview REST API 或更高版本。 在早期预览版 API 版本中，系统仅在每个项的第一次引入时捕获 ACL。 后续的权限更改需要显式重新建立索引。 有关迁移步骤，请参阅 “在索引内容和源内容之间同步权限”。

• 后续索引器运行时，不会自动获取父范围的权限更改。 有关刷新选项，请参阅 索引内容和源内容之间的同步权限。

• Azure门户不支持此功能。

• 此预览版不支持以下功能：

  • SharePoint信息管理策略适用于用户访问。 系统不会在查询时评估、引入或遵循这些策略。

  • 范围限定为“任何人”或“组织中的人员”的可共享链接。仅支持范围限定为“特定人员”的链接。

  • 自 2026-05-01-preview REST API 起，支持 SharePoint 组（例如所有者组、成员组和访问者组）。 请参阅 配置SharePoint组支持。 在 API 的早期预览版本中，仅支持可解析为 Microsoft Entra 组的 SharePoint 组。

• 以下索引器功能不支持源自SharePoint的索引文档中的权限继承。 如果在技能集或索引器中使用这些功能中的任何一项，则索引内容中不包含文档级权限。

  • 自定义 Web API 技能

  • 知识存储，包括 图像服务（预览版） 在代理检索中所需的资产存储。 因此，引入 SharePoint ACL 的知识源不支持图像服务。

  • 索引器扩充缓存

  • 调试会话

支持SharePoint权限模型

此预览版支持文档、列表项和新式 ASPX 网站页面的基本 ACL。

支持的组关系

Microsoft Entra 组的传递性仅在 Microsoft Entra 内部适用。 它不会扩展属于 SharePoint 组的 Microsoft Entra 组。

如何评估分层权限

SharePoint权限继承站点→库→文件夹→文件的层次结构，除非继承中断。

引入期间，索引器在每个级别收集用户和组标识符（ID），并计算每个文件的有效 ACL。

按 ACL 场景划分的权限

ACL 引入所需的 Microsoft Entra 应用程序权限和凭据类型，取决于你要索引的项类型和组类型。 在应用注册中，所有权限均在 API 权限>下添加，并且联合凭据在“证书和机密>”联合凭据下添加。 有关分步说明和屏幕截图，请参阅 Step 3：创建Microsoft Entra应用程序注册和使用托管标识配置已注册的应用程序。

联合凭据使用受信任的托管标识而不是客户端密码对应用进行身份验证。 同一联合凭据同时适用于引入（索引器）以及在查询时对 SharePoint 网站组进行评估。 有关设置步骤，请参阅 使用托管标识配置已注册的应用程序。

在启用 ACL 引入之前

在已注册Microsoft Entra应用程序上完成以下步骤：

1. 根据计划建立索引的内容（文档库文件、列表项、ASPX 站点页面）以及是否需要遵从 SharePoint 站点组权限，在上表中确定你所属的场景。
2. 在 Microsoft Entra 管理中心 中打开应用注册，转到 API 权限>添加权限。
3. 添加针对你的场景列出的 Microsoft Graph 权限。 授予管理员同意权限。
4. 如果你的方案还需要SharePoint权限，请选择再次添加权限，选择 SharePoint API，并添加 Sites.FullControl.All （或 Sites.Selected）。 授予管理员同意权限。
5. 配置凭据：
   • 对于仅使用 Microsoft Graph 的场景，可以使用客户端密码（证书和密码>客户端密码）或联合凭据。
   • 对于任何包含 SharePoint 权限的场景，请在 Certificates & secrets>联合凭据 下添加联合凭据。 请参阅 使用托管标识配置已注册的应用程序。
6. 向应用程序授予对目标SharePoint网站的访问权限（在使用 Sites.Selected 进行作用域访问时尤其重要），以便它可以读取要编制索引的内容和权限。

查找正确的Microsoft Entra标识符

每个标识符显示在Azure门户的不同位置，并映射到特定的配置字段。 使用联合凭据配置 SharePoint ACL 摄取时，请将本节用作参考。 这些标识符在 配置 SharePoint 组支持 和数据源连接字符串中被引用。

联合凭据应用程序 ID

对于数据源连接字符串中的 FederatedCredentialApplicationId 和索引定义中的 federatedCredentialId，请使用托管标识自身的应用程序（客户端）ID，而不是引入应用程序的 ID。

系统分配的托管标识：

1. 转到你的 Azure AI 搜索 服务。
2. 选择 安全和网络>身份。
3. 在 “系统分配 ”选项卡上，记下 “对象”（主体）ID。
4. 转到 Microsoft Entra ID>管理>企业应用程序。
5. 搜索搜索服务名称或将 对象（主体）ID 粘贴到搜索框中。
6. 选择结果并打开 “属性”。 复制此处显示的应用程序 ID，它是数据源中 federatedCredentialId 和索引中 FederatedCredentialApplicationId 的值。

用户分配的托管标识：

1. 转到用户分配的托管标识资源。
2. 选择设置>属性。
3. 复制客户端 ID，它是数据源中 federatedCredentialId 的值，也是索引中 FederatedCredentialApplicationId 的值。

为 ACL 引入和查询时强制实施配置搜索服务

这些步骤为搜索服务配置 ACL 引入并启用查询时 ACL 遵守。

选择填充 ACL 字段的位置

在何处映射 ACL 元数据字段取决于索引器是为每个源项写入一个文档还是每个源项的多个区块。

在所有分块场景中，每个块都必须包含 ACL 字段。 权限筛选器适用于每个文档，因此无法将缺少 ACL 字段的区块返回到正确的调用方。

1. 数据源配置

本部分是对基础步骤 4：创建数据源演练说明的增量补充。 在 indexerPermissionOptions 中设置 以允许为 SharePoint 文档中的 userIds 和 groupIds 编制索引。

{
  "name": "my-sharepoint-acl-datasource",
  "type": "sharepoint",
  "indexerPermissionOptions": ["userIds", "groupIds"],
  "credentials": {
    "connectionString": "<connection-string>;"
  },
  "container": {
    "name": "<library-name>",
    "query": "<optional-folder-path>"
  }
}

2. 向索引定义添加权限字段

将字段添加到 索引架构定义 ，以存储 ACL 并支持查询时间筛选。

{
  "fields": [
    { "name": "UserIds",  "type": "Collection(Edm.String)", "permissionFilter": "userIds",  "filterable": true, "retrievable": false },
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

仅在开发阶段将retrievable属性设置为true以验证值。 可以将可检索属性从 true 更改为 false，而无需重新生成索引。

3.在技能组中配置索引投影（如果适用）

启用分块时，当 projectionMode 为 skipIndexingParentDocuments 时，父文档不会写入索引。 通过 indexProjections.selectors[].mappings 将 ACL 元数据附加到每个块上。

如果索引器使用具有数据分块的技能集，例如启用集成向量化时的文本拆分技能，请确保使用索引投影将 ACL 属性映射到每个区块。 //以下示例中的行是说明性批注，不是有效的 JSON。 在提交请求之前删除它们。

PUT https://{service}.search.windows.net/skillsets/{skillset}?api-version=2026-08-01-preview
{
  "name": "my-skillset",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
      "name": "#split",
      "context": "/document",
      "inputs": [{ "name": "text", "source": "/document/content" }],
      "outputs": [{ "name": "textItems", "targetName": "chunks" }]
    }
    // ... (other skills such as embeddings, entity recognition, etc.)
  ],
  "indexProjections": {
    "selectors": [
      {
        "targetIndexName": "chunks-index",
        "parentKeyFieldName": "parentId",          // must exist in target index
        "sourceContext": "/document/chunks/*",     // match your split output path
        "mappings": [
          { "name": "chunkId",           "source": "/document/chunks/*/id" },     // if you create an id per chunk
          { "name": "content",           "source": "/document/chunks/*/text" },   // chunk text
          { "name": "parentId",          "source": "/document/id" },              // parent doc id
          { "name": "UserIds",  "source": "/document/metadata_user_ids" },
          { "name": "GroupIds",  "source": "/document/metadata_group_ids" },
          { "name": "SharePointSiteUrl", "source": "/document/metadata_spo_site_url" } // include when the index has sharePointConnectorAppRegistration (SharePoint groups support)
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}

UserIds、GroupIds 和 SharePointSiteUrl 映射将读取SharePoint索引器（/document/metadata_*）发出的源级元数据，并将值写入每个区块。

4. 为 ACL 配置索引器字段映射

当索引器为每个源项写入一个文档（无分块）或将单独的父索引与区块索引一起维护时，请使用索引器字段映射。 如果你的技能组将文档拆分为块并写入单个目标索引 projectionMode: skipIndexingParentDocuments，则此处显示的字段映射将由上一步中块索引的 indexProjections.mappings 取代。

除了需要的 索引器配置，请将 SharePoint 中的原始元数据 ACL 字段映射到您的索引字段。

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids",  "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" }
  ]
}

5. 运行索引器

索引器运行时会引入 ACL 元数据。 创建或更新索引器（请参阅 步骤 6：创建索引器）后，触发运行，使索引器与内容一起引入 ACL。

POST https://[service name].search.windows.net/indexers/[indexer-name]/run?api-version=2026-08-01-preview
api-key: [admin key]

如果你在已为某些项编制索引的现有索引器上启用了 ACL 引入功能，请调用 /resync 并使用 options: ["permissions"] 为这些项回填 ACL，或者调用 /resetdocs 以重新提取特定项。

6. 验证 ACL 引入

要确认 ACL 值是否已正确填充，请按以下步骤操作：

1. 在索引定义中，将 retrievable 和 true 上的 UserIds 暂时设置为 GroupIds。 更改 retrievable 不需要重新生成索引。
2. 运行一个提升读取权限的查询，选择UserIds和GroupIds，并确认这些集合不为空。 对于分块方案，请确认每个区块都包含这两个字段。
3. 验证后将retrievable返回给false。

配置SharePoint组支持

从 2026-05-01 预览版 REST API 开始，SharePoint索引器可以引入SharePoint网站组成员身份（所有者、成员、访问者和自定义网站组）。 它在查询时遵循这些组。 SharePoint 组 ID 会在 metadata_group_ids 字段中输出，并带有 spg: 前缀，以区别于 Microsoft Entra 组对象 ID。

本演练是独立完整的：请按顺序完成这些步骤，以配置索引、索引器字段映射，并在启用 SharePoint 站点组强制实施的情况下查询索引。

以下组件协同工作以启用SharePoint站点组解析：

1.先决条件

• 已为 ACL 引入配置好 SharePoint 索引器。 请参阅 ACL 的索引器字段映射配置。
• 具有联合身份凭据的 Microsoft Entra 应用注册 请参阅 使用托管标识配置已注册的应用程序。
• REST API 2026-05-01-preview 或更高版本。

2.配置索引

将sharePointConnectorAppRegistration配置和SharePointSiteUrl字段添加到UserIds和GroupIds权限筛选字段旁边，以便将完整的索引结构集中在一处。 保留 permissionFilterOption: "enabled"。

PUT https://{service}.search.windows.net/indexes/{index}?api-version=2026-08-01-preview
{
  "name": "my-sharepoint-acl-index",
  "sharePointConnectorAppRegistration": {
      "applicationId": "<ingestion-app-client-id>",
      "federatedCredentialId": "<managed-identity-application-id>",
     "tenantId": "<sharepoint-tenant-id>"
  },
  "fields": [
    { "name": "UserIds",           "type": "Collection(Edm.String)", "permissionFilter": "userIds",  "filterable": true, "retrievable": false },
    { "name": "GroupIds",          "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false },
    { "name": "SharePointSiteUrl", "type": "Edm.String", "sharepointSiteUrl": true, "filterable": false, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

3.配置索引器字段映射

将SharePoint元数据字段映射到单个组合映射块中的索引字段。 前两个映射是用于标准 ACL 引入的映射;第三个映射激活SharePoint组解析。

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids",             "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids",            "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_spo_site_url",  "targetFieldName": "SharePointSiteUrl" }
  ]
}

如果技能组会将文档拆分成多个区块（例如，使用用于集成向量化的“文本拆分”技能），请改为通过 SharePointSiteUrl 将 indexProjections.mappings 投影到每个区块上。 请参阅 “选择填充 ACL 字段的位置”。

4.查询索引

不需要客户端更改。 同一 x-ms-query-source-authorization 令牌会同时激活 Microsoft Entra 和 SharePoint 站点组强制执行。 搜索服务使用索引上的 sharePointConnectorAppRegistration 解析服务器端SharePoint 组成员身份。

有关请求结构，请参阅 常规查询示例 以及特定于 SharePoint 的包含 SharePoint 站点组强制实施的示例。

5. 验证

若要确认 SharePoint 组 ID 已进入索引，请运行一个选择 的 GroupIds，并在响应中查找带有 spg: 前缀的值。

在索引内容和源内容之间同步权限

从 2026-05-01 预览版 REST API 开始，在每次成功运行索引器时，都会检测和刷新具有唯一权限的项目的 ACL 更改。 索引器使用 SharePoint 更改令牌，以增量方式检测角色分配的新增和删除，就像它检测内容更改一样。

某些场景仍然需要显式刷新：

重置特定文档

可以将 特定文档重置 以重新完全引入内容和 ACL。

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2026-08-01-preview
{
  "documentKeys": ["doc123", "doc456"]
}

重新同步整个数据源的 ACL

可以在初始引入后 重新同步完整的数据集 ACL 内容 。 若要完全成功，此操作需要在完成后 运行索引器 。

POST https://{service}.search.windows.net/indexers/{indexer}/resync?api-version=2026-08-01-preview
{
  "options": ["permissions"]
}

为数据和 ACL 编制索引后，可以 查询索引。

故障排除

有关在为 ACL 元数据编制索引后缺失、意外或失败的查询时间结果，请参阅 SharePoint 权限筛选疑难解答。

相关内容

• 在 Azure AI 搜索（预览版）中索引 SharePoint 内容
• ACL 在查询时的执行