次の方法で共有

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

注释

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

Azure Data Lake Storage （ADLS） Gen2 中的权限模型允许每个用户访问特定目录或文件。 Azure AI 搜索中的预览 API 现在支持引入用户权限以及文档引入，以便使用这些权限来控制对搜索结果的访问。 如果用户在 ADLS Gen2 中缺少特定目录或文件的权限，则该用户无权访问 Azure AI 搜索结果中的相应文档。

可以使用推送 API 手动上传和索引内容和权限元数据，也可以使用索引器或知识源自动执行数据引入。

本文重点介绍基于以下基础构建的索引自动化方法：

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

本文补充 ADLS Gen2 和 ADLS Gen2 blob 知识源 中的索引数据，其中包含特定于将权限与文档内容一起引入 Azure AI 搜索索引的信息。

先决条件

局限性

支持权限模型

本部分比较 ADLS Gen2 与 Azure AI 搜索之间的文档级访问控制功能。 该文档解释了 AI 搜索支持或映射的 Azure Data Lake Storage（ADLS）Gen2 访问控制机制。 这有助于了解如何在文档级别强制实施权限。

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

关于 ACL 分层权限

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

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

操作 / Oregon/ Portland/ Data.txt
读取 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 存储。

根容器权限：

  1. 在具有Group和User权限的根容器/上分配所有Read和Execute设置（安全主体）。

  2. 确保将Read和Execute都添加为“默认权限”，以便它们自动应用于新创建的文件和目录。

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

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

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

删除多余的权限

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

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

示例 ACL 分配结构

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

ACL 分配结构的示意图。

随时间推移更新 ACL 分配

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

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

Authorization

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

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

配置知识源

如果使用知识源，则知识源中的定义用于生成完整的索引管道（索引器、数据源和索引）。 检测到 ACL 分配并将其自动包含在生成的索引中。 如果希望在索引内容中继承权限，则无需修改任何生成的对象。

有关使它适用于此方案的配置的要点：

  • isADLSGen2 设置为 true，满足此方案的数据源要求。
  • ingestionPermissionOptions 指定用户和组 ID。
  • disableImageVerbalization 设置为 true，因为支持此体验的 GenAI 提示技能当前在 ADLS Gen2 权限继承中不受支持。
# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2025-11-01-preview
api-key: {{key}}
Content-Type: application/json

{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source",
    "azureBlobParameters": {
        "connectionString": "{{blob-connection-string}}",
        "containerName": "blobcontainer",
        "folderPath": null,
        "isADLSGen2": true,
        "ingestionParameters": {
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": true,
            "ingestionSchedule": null,
             "ingestionPermissionOptions": [
                "userIds","groupIds"
                           ],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}
###

配置基于索引器的索引编制

如果使用索引器，请对其进行配置、数据源和索引，以便从 ADLS Gen2 Blob 拉取权限元数据。

创建数据源

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

  • 数据源类型必须是 adlsgen2。

  • 数据源必须具有indexerPermissionOptions和userIds、groupIds和/或rbacScope。

系统管理标识的 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.azure.cn/indexers/{indexer}/resetdocs?api-version=2025-11-01-preview 
{ 
  "documentKeys": [ 
    "1001", 
    "4452" 
  ]
}

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

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

重要

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

删除跟踪

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

另请参阅

  • Last updated on