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

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

主要功能包括：

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

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

Prerequisites

• 包含 ACL 元数据的内容，来自Microsoft Entra ID或其他 POSIX 样式的 ACL 系统。

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

• 启用了 permissionFilterOption 的索引架构，加上 permissionFilter 字段属性，这些属性存储与文档关联的权限。

Limitations

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

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

• 可以将预先存在的字段转换为用于内置 ACL 或 RBAC 元数据筛选的 permissionFilter 字段类型。 若要对现有索引启用筛选，请创建新字段或修改现有字段以包含一个 permissionFilter。

• 只能在索引中存在一个每种permissionFilter类型的字段（每种groupIds、usersIds和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.windows.net/indexes('indexdocumentsexample')/docs/search.index?api-version=2025-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 值为用户确定文档访问权限。 关键规则是 ，用户只需匹配一个 ACL 类型即可访问文档。 例如，如果文档具有字段 userIds， groupIds并且 rbacScope用户可以通过匹配其中任一 ACL 字段来访问该文档。

特殊 ACL 值“all”和“none”

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

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

访问控制示例

此示例说明如何根据特定的文档 ACL 字段值解析文档访问规则。 为了便于阅读，此方案使用 ACL 别名，例如“user1”、“group1”而不是 GUID。

另请参阅

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