使用推送 REST API 为文档访问控制列表（ACL）编制索引（预览版）

通过推送 REST API（预览版）引入文档级权限信息后，您可以同时为文档及其关联的 访问控制列表（ACL） 和容器 基于角色的访问控制（RBAC）角色编制索引。 通过推送 REST API 将内容推送到Azure AI 搜索索引时，服务将保留对这些索引内容的权限，并在查询时强制执行这些权限。

主要功能包括：

• 灵活控制数据流入流程。
• 权限元数据的标准化架构。
• 支持分层权限，例如文件夹级 ACL。

本文介绍如何使用推送 REST API 为Azure AI 搜索中的文档级权限元数据编制索引。 该过程将准备索引，以便查询并执行对搜索结果的最终用户权限。

先决条件

• 包含来自 Microsoft Entra ID 或其他 POSIX 样式 ACL 系统的 ACL 元数据内容。 对于userIds和 groupIds ACL 字段，请使用Microsoft Entra对象 ID（GUID），而不是 UPN 或电子邮件地址。 稳定对象 ID 可确保在查询时进行可靠的标识匹配，即使目录属性发生更改。

• 提供等效功能的最新预览版 REST API 或预览版 Azure SDK 包。

• 启用了 permissionFilterOption 的索引架构，以及存储文档权限的 permissionFilter 字段属性。

限制

• 具有权限筛选器类型的 userIds ACL 字段，或者 groupIds 最多可以保留 1000 个值。

• 索引在所有文档的类型 rbacScope 字段中最多可以保留五个唯一值。 共享相同值 rbacScope的文档数没有限制。

• 可以更新现有字段，以包含用于内置 ACL 或 RBAC 元数据筛选的permissionFilter设置。 若要对现有索引启用筛选，请添加新字段或更新现有字段以包含值 permissionFilter 。

• 在一个索引中，每种permissionFilter类型只能各有一个字段（即groupIds、userIds和rbacScope各一个）。

• 每个 permissionFilter 字段都应将 filterable 设置为 true。

• 查询时的权限强制实施反映的是最后写入索引的 ACL 值。 如果源权限发生更改，则在重新引入或更新受影响的文档之前，不会反映这些更新。 计划增量重新引入或部分更新，使 ACL 保持最新状态。

• Azure门户中当前不支持此功能。

使用权限筛选器字段创建索引

使用 REST API 为文档 ACL 和 RBAC 元数据编制索引需要设置索引架构，以便启用权限筛选器，并具有具有权限筛选器分配的字段。

首先，添加 permissionFilterOption。 有效值为 enabled 或 disabled，应将其设置为 enabled。 如果您想在索引级别关闭权限筛选功能，可以将其切换为 disabled 。

其次，为权限元数据创建字符串字段，并包括 permissionFilter。 请注意，你可以使用各类权限筛选器中的一种。

下面是包含所有 permissionFilter 类型的基本示例架构：

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

对于企业存储库，如 SharePoint Online，在调用推送 API 之前，在引入期间将文档级或文件夹级权限解析为 Microsoft Entra 用户和组对象 ID。 然后，应将这些 ID 存储在相应的权限字段中。

REST API 索引示例

拥有具有权限筛选器字段的索引后，可以使用推送索引 API 填充这些值，就像任何其他文档字段一样。 下面是使用指定索引架构的示例，其中每个文档指定索引操作、键字段（DocumentId）和权限字段。 文档还应包含内容，但在此示例中省略该字段是为了简洁起见。

POST https://exampleservice.search.windows.net/indexes('indexdocumentsexample')/docs/search.index?api-version=2026-08-01-preview
{
  "value": [
    {
      "@search.action": "upload",
      "DocumentId": "1",
      "UserIds": ["00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "11bb11bb-cc22-dd33-ee44-55ff55ff55ff", "22cc22cc-dd33-ee44-ff55-66aa66aa66aa"],
      "GroupIds": ["none"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-01"
    },
    {
      "@search.action": "merge",
      "DocumentId": "2",
      "UserIds": ["all"],
      "GroupIds": ["33dd33dd-ee44-ff55-aa66-77bb77bb77bb", "44ee44ee-ff55-aa66-bb77-88cc88cc88cc"]
    },
    {
      "@search.action": "mergeOrUpload",
      "DocumentId": "3",
      "UserIds": ["1cdd8521-38cf-49ab-b483-17ddaa48f68f"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-03"
    }
  ]
}

ACL 访问解析规则

本部分说明系统如何根据每个文档的权限字段确定用户的文档访问权限。 这些字段要么是 ACL（userIds 和 groupIds，其中 groupIds 包括安全组和 Microsoft 365 组），要么是 RBAC 范围（rbacScope）。 Azure按定义的顺序评估 RBAC 范围和 ACL，这与 ADLS Gen2 权限模型一致。

用户通过满足以下字段之一获得访问权限：匹配的 userIds 或 groupIds 条目，或针对 rbacScope 的符合条件的 Azure 角色分配。 有关如何在查询时提供调用者身份的信息，请参阅查询时 ACL 和 RBAC 的实施。

特殊 ACL 值“all”和“none”

ACL 字段（例如 userIds 和 groupIds）通常包含 GUID 列表（全局唯一标识符），用于标识有权访问文档的用户和组。 这些 ACL 字段类型支持两个特殊字符串值“all”和“none”。 这些值充当广泛的筛选器，用于控制全局级别的访问，如下表所示。

由于用户只需要匹配一个字段类型，因此特殊值“all”将授予公共访问权限，而不考虑任何其他 ACL 字段值。 相比之下，设置为 userIds “none”或空数组意味着不会根据用户 ID 授予任何用户对文档的访问权限。 他们仍然可能通过匹配组 ID 或 RBAC 元数据被授予访问权限。

访问控制示例

此示例说明了如何根据 userIds、groupIds 和 rbacScope 中的权限字段值解析文档访问规则。 为了便于阅读，此场景使用“user1”和“group1”等别名，而非 GUID；在生产环境中，请使用 Microsoft Entra 对象 ID（GUID）。

相关内容

• 使用角色连接到Azure AI 搜索
• 查询时的 ACL 和 RBAC 执行
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API