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

通过推送 REST API将文档及其关联的访问控制列表（ACL）以及容器的基于角色的访问控制（RBAC）角色编入 Azure AI 搜索索引，可在查询时保留索引内容的文档级权限。

主要功能包括：

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

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

先决条件

• 包含 ACL 元数据的内容，来自Microsoft Entra ID或其他 POSIX 样式的 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。

• 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"
}

REST API 索引示例

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

POST https://exampleservice.search.azure.cn/indexes('indexdocumentsexample')/docs/search.index?api-version=2026-05-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 值为用户确定文档访问权限。 关键规则是 ，用户只需匹配一个 ACL 类型即可访问文档。 例如，如果文档具有字段 userIds， groupIds并且 rbacScope用户可以通过匹配其中任一 ACL 字段来访问该文档。

特殊 ACL 值“all”和“none”

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

由于用户只需匹配一个字段类型，因此，无论其他任何 ACL 字段值如何，特殊值“all”都会授予公共访问权限。 相比之下，将 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