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

通过推送 REST API（预览版）引入文档级权限信息后，您可以同时为文档及其关联的 访问控制列表（ACL） 和容器 基于角色的访问控制（RBAC）角色编制索引。 通过推送 REST API 将内容推送到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。

• 查询时的权限强制实施反映的是最后写入索引的 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"
}

REST API 索引示例

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

POST https://exampleservice.search.azure.cn/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”。 这些值充当广泛的过滤器，用于在全局层面控制访问，如下表所示。

由于用户只需匹配一个字段类型，因此，无论其他任何 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