你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 ADLS Gen2 索引器引入权限元数据并根据用户访问权限筛选搜索结果

2025-09-18

Note

此功能目前处于公开预览状态。此预览版未随附服务级别协议，建议不要用于生产工作负载。某些功能可能不受支持或者受限。有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。

Azure Data Lake Storage （ADLS） Gen2 中的权限模型可用于对特定目录或文件的按用户访问。从 2025-05-01-preview 开始，现在可以在 Azure AI 搜索中包含用户权限以及文档引入，并使用这些权限来控制对搜索结果的访问。如果用户在 ADLS Gen2 中缺少特定目录或文件的权限，则该用户无权访问 Azure AI 搜索结果中的相应文档。

可以使用推送 API 手动上传和索引内容和权限元数据，也可以使用索引器自动执行数据引入。本文重点介绍索引器方法。

索引器方法基于以下基础构建：

ADLS Gen2 访问控制模型，提供访问控制列表（ACL）和基于角色的访问控制（Azure RBAC）。不支持基于属性的访问控制（Azure ABAC）。
ADLS Gen2 的 Azure AI 搜索索引器，用于检索和引入数据和元数据，包括权限筛选器。若要获取权限筛选器支持，请使用支持该功能的最新预览版 REST API 或 Azure SDK 的预发行包。
在 Azure AI 搜索中的索引包含引入的文档和相应的权限。权限元数据作为字段存储在索引中。若要设置符合权限筛选器的查询，请使用支持该功能的最新预览版 REST API 或 Azure SDK 的预发行包。

此功能有助于将搜索索引中的文档级权限与 ADLS Gen2 中定义的访问控制保持一致，允许用户以反映其现有权限的方式检索内容。

本文补充了 ADLS Gen2 中的索引数据，提供了关于如何将权限和文档内容一起导入到 Azure AI 搜索索引的特定信息。

Prerequisites

Microsoft Entra ID 身份验证和授权。服务和应用必须位于同一租户中。只要所有租户都是 Microsoft Entra ID，用户就可以位于不同的租户中。角色分配用于每个经过身份验证的连接。
Azure AI 搜索（任何区域），但必须具有计费层（基本层和更高层）才能获得托管标识支持。搜索服务必须配置为基于角色的访问，并且必须具有托管标识（系统或用户）。
分层命名空间中的 ADLS Gen2 blob，其用户权限通过 ACL 或角色授予。

Limitations

ADLS Gen2 中对 Azure 角色分配和 ACL 条目的限制施加了最大数目的角色分配和 ACL 条目。
公共预览版期间不支持 owning users、owning groups 和 OtherACL 标识类别。请改用 named users 和 named groups 赋值。
以下索引器功能不支持源自 ADLS Gen2 的索引文档中的权限继承。如果在技能集或索引器中使用这些功能中的任何一项，则索引内容中不会显示文档级权限：
Azure 门户中当前不支持此功能。

支持权限模型

本部分比较 ADLS Gen2 与 Azure AI 搜索之间的文档级访问控制功能。它突出显示了与 AI 搜索集成时支持或映射哪些 ADLS Gen2 访问控制机制，帮助你了解如何在文档级别强制执行权限。

ADLS Gen2 功能	Description	Supported	Notes
RBAC	容器级别的粗粒度访问	Yes	AI 搜索遵从 RBAC 策略来访问整个容器中的所有文档。
ABAC	基于属性的条件（基于 RBAC）	No	AI 搜索不会评估文档级访问的 ABAC 条件。
ACL	目录/文件（文档）级别的细化权限	Yes	AI 搜索将文档级 ACL 用于权限筛选器。
安全组	基于组的权限分配	Yes	只要安全组在文档级 ACL 中映射即可获得支持。

关于 ACL 分层权限

索引器可以通过遵循 ADLS Gen2 分层访问评估流，从指定的容器以及通往每个文件的所有目录中检索 ACL 分配。计算每个文件的最终有效访问列表，并将不同的访问类别编入相应的索引字段。

例如，在 ADLS Gen2 中，常见的与权限相关的场景包括文件路径 /俄勒冈/波特兰/Data.txt。

Operation	/	Oregon/	Portland/	Data.txt
Read Data.txt	--X	--X	--X	R--

索引器从每个容器和目录中提取 ACL，将其解析为较低级别的保留有效访问，并继续此过程，直到确定每个文件的有效访问。

/ assigned access vs Oregon/ assigned access
  => Oregon/ effective access vs Portland/ assigned access
    => Portland/ effective access vs Data.txt assigned access
      => Data.txt effective access

配置 ADLS Gen2

如果满足以下条件，索引器可以在存储帐户上检索 ACL。有关 ACL 分配的详细信息，请参阅 ADLS Gen2 ACL 分配。

Authorization

对于索引器执行，搜索服务标识必须具有“存储 Blob 数据读者”权限。

如果在本地进行测试，则还应进行“存储 Blob 数据读者”角色分配。有关详细信息，请参阅使用托管标识连接到 Azure 存储。

根容器权限：

在具有Group和User权限的根容器/上分配所有Read和Execute设置（安全主体）。
确保将Read和Execute都添加为“默认权限”，以便它们自动应用于新创建的文件和目录。

在文件层次结构中向下传播权限

虽然新目录和文件继承权限，但现有目录和文件不会自动继承这些分配。

使用 ADLS Gen2 工具以递归方式应用 ACL 来对现有内容进行分配传播。此工具将根容器的 ACL 分配传播到所有基础目录和文件。

删除多余的权限

以递归方式应用 ACL 后，查看每个目录和文件的权限。

删除不应有权访问特定目录或文件的任何 Group 或 User 集。例如，在文件夹User2上删除Portland/；在文件夹Idaho中，从其分配中删除Group2和User2，等等。

示例 ACL 分配结构

下面是 ADLS Gen2 文档中虚构目录层次结构的 ACL 分配结构图。

随时间推移更新 ACL 分配

随着时间的推移，在添加或修改任何新的 ACL 分配时，请重复上述步骤，以确保正确传播和权限对齐。使用索引器重新引入内容时，ADLS Gen2 中的更新权限在搜索索引中更新。

配置 Azure AI 搜索

回想一下，搜索服务必须具有：

Authorization

对于索引器执行，发出 API 调用的客户端必须具有 搜索服务参与者 权限才能创建对象、 搜索索引数据参与者 权限来执行数据导入，以及 搜索索引数据读取器 来查询索引。

如果在本地进行测试，则应具有相同的角色分配。有关详细信息，请参阅使用角色连接到 Azure AI 搜索。

配置索引

在 Azure AI 搜索中，配置索引器、数据源和索引，以便从 ADLS Gen2 Blob 拉取权限元数据。

创建数据源

本部分补充了为 ADLS Gen2 中的数据编制索引，增加了有关将权限与文档内容一起引入 Azure AI 搜索索引的特定信息。

数据源类型必须是 adlsgen2。
数据源必须具有indexerPermissionOptions和userIds、groupIds和/或rbacScope。
- 对于 rbacScope，请使用托管标识格式配置连接字符串。
- 对于使用用户分配的托管标识的连接字符串，还必须指定 identity 属性。

系统管理标识的 JSON 示例：

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    }
}

连接字符串中具有用户托管标识的 JSON 架构示例：

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    },
    "identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
    }
}

在索引中创建权限字段

在 Azure AI 搜索中，确保索引包含权限元数据的字段定义。可以在数据源定义中指定indexerPermissionOptions时对权限元数据进行索引。

ACL（UserIds、GroupIds）和 RBAC 作用域的建议架构属性：

具有 userIds permissionFilter 值的用户 ID 字段。
使用 groupIds permissionFilter 值提交的组 ID。
具有 rbacScope permissionFilter 值的 RBAC 范围字段。
用于在查询时启用筛选的属性 permissionFilterOption 。
使用字符串字段作为权限元数据
在所有字段上将 filterable 设置为 true。

请注意，retrievable 是 false。可以在开发过程中将其设置为 true，以验证权限是否存在，但请记住在部署到生产环境之前将其设置回 false。

JSON 架构示例：

{
  ...
  "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": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

配置索引器

索引器中的字段映射将数据路径设置为索引中的字段。名称或数据类型不同的目标字段和目的地字段需要显式字段映射。如果更改字段名称，ADLS Gen2 中的以下元数据字段可能需要字段映射：

metadata_user_ids （Collection(Edm.String)） - ACL 用户 ID 列表。
metadata_group_ids （Collection(Edm.String)） - ACL 组 ID 列表。
metadata_rbac_scope （Edm.String） - 容器 RBAC 范围。

在索引器中指定 fieldMappings ，以便在编制索引期间将权限元数据路由到目标字段。

JSON 架构示例：

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

建议和最佳做法

在创建任何文件夹之前，请仔细规划 ADLS Gen2 文件夹结构。
分组整理标识并尽可能使用组，而不是直接向单个用户授予访问权限。不断地添加单个用户而不是采用组，这会增加必须跟踪和评估的访问控制条目的数量。不遵循此最佳做法可能会导致索引所需的更频繁的安全元数据更新，因为此元数据发生更改，从而导致刷新过程中延迟和效率低下。

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

在索引器上启用 ACL 或 RBAC 扩充仅在两种情况下自动工作：

第一个完整索引器运行/数据爬网：捕获在该时刻存在的每个文档的所有权限元数据。
启用 ACL/RBAC 支持后添加的全新文档： 它们的 ACL/RBAC 信息与内容一起被导入。

在对文档编制索引后所做的任何权限更改（例如，将用户添加到 ACL 或更改角色分配）将不会显示在搜索索引中，除非显式指向索引器再次爬网文档权限元数据。

根据更改的项数，选择以下机制之一：

更改的范围	最佳触发器	下一次运行时刷新的内容
单个 blob 或少量 blob	更新存储中的 blob 的 `Last-Modified` 时间戳（触摸文件）	文档内容和 ACL/RBAC 元数据
数十到数千个 blob	调用 /resetdocs （预览版）并列出受影响的文档键。	文档内容和 ACL/RBAC 元数据
整个数据源	使用权限选项调用 /resync（预览版）。	只 ACL/RBAC 元数据（内容保持不变）

Resetdocs （预览版） API 示例：

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

重新同步（预览版）API 示例：

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

Important

如果更改对已编制索引的文档的权限，并且不触发上述机制之一，搜索索引将保留过时的 ACL/RBAC 数据。新文档将继续被自动索引，无需手动触发。

删除跟踪

若要有效管理 Blob 删除，请确保在索引器首次运行时已启用删除跟踪。此功能允许系统检测源中删除的 blob，并从索引中删除它们。

另请参阅

反馈

此页面是否有帮助？

通过

使用 ADLS Gen2 索引器引入权限元数据并根据用户访问权限筛选搜索结果

Prerequisites

Limitations

支持权限模型

关于 ACL 分层权限

配置 ADLS Gen2

Authorization

根容器权限：

在文件层次结构中向下传播权限

删除多余的权限

示例 ACL 分配结构

随时间推移更新 ACL 分配

配置 Azure AI 搜索

Authorization

配置索引

创建数据源

在索引中创建权限字段

配置索引器

建议和最佳做法

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

删除跟踪

另请参阅

反馈

其他资源