通过

教程：从 ADLS Gen2 为权限元数据编制索引，并使用权限筛选的结果进行查询

本教程演示如何使用索引器将 Azure Data Lake Storage （ADLS） Gen2 访问控制列表（ACL） 和 基于角色的访问控制（RBAC） 范围编制索引到搜索索引中。

它还演示如何构建尊重用户访问权限的查询。 成功的查询结果确认索引期间发生的权限传输。

本教程中，您将学习如何：

  • 在 adlsgen2 数据源上配置 RBAC 范围和 ACL
  • 创建包含权限信息字段的 Azure AI 搜索索引
  • 创建并运行索引器以从数据源将权限信息引入索引
  • 搜索刚刚创建的索引

使用 REST 客户端完成本教程以及最新的预览版 REST API。 目前，Azure 门户中不支持 ACL 索引。

先决条件

  • 拥有有效订阅的 Azure 帐户。 创建试用版订阅。

  • Microsoft Entra ID 身份验证和授权。 服务和应用必须位于同一租户中。 角色分配用于每个经过身份验证的连接。 用户和组必须位于同一租户中。 应具有要使用的用户和组。 创建租户和安全主体超出了本教程的范围。

  • 具有分层命名空间的 ADLS Gen2。

  • 分层文件夹结构中的文件。 本教程假定采用文件 /Oregon/Portland/Data.txt 的文件夹结构的 ADLS Gen2 演示。 本教程指导你完成文件夹和文件的 ACL 分配，以便你能够成功完成练习。

  • Azure AI 搜索、任何区域。 托管标识支持需要基本层或更高层。

  • 具有 REST 客户端或 Python 客户端和 Jupyter 包的 Visual Studio Code。

准备示例数据

将 国家公园示例数据 上传到 ADLS Gen2 中的容器。 容器名称应为“公园”，它应有两个文件夹：“俄勒冈州”和“华盛顿”。

检查搜索服务配置

必须为搜索服务配置Microsoft Entra ID 身份验证和授权。 查看此清单，确保已准备好。

获取用于本地测试的个人标识令牌

本教程假定本地系统上的 REST 客户端通过公共 Internet 连接连接到 Azure。

按照以下步骤 获取个人标识令牌，并设置 Visual Studio Code 以便与 Azure 资源建立本地连接。

在 ADLS Gen2 中设置权限

最佳做法是使用 [Group 集，而不是直接分配 User 集。

  1. 向搜索服务标识授予对容器的读取访问权限。 索引器在搜索服务标识下连接到 Azure 存储。 搜索服务必须具有存储 Blob 数据读取者权限才能检索数据。

  2. 在文件层次结构中授予每组或用户权限。 在文件层次结构中，标识分配给容器、目录和文件的所有 Group 和 User 集。

  3. 可以使用 Azure 门户管理 ACL。 在存储浏览器中，选择俄勒冈目录，然后从上下文菜单中选择 “管理 ACL ”。

  4. 为用户和组添加新的安全主体。

  5. 移除拥有组、拥有用户和其他的现有主体。 公共预览版期间，ACL 索引不支持这些主体。

为权限元数据创建搜索索引

创建包含 内容和权限元数据字段的索引。

请务必使用最新的预览版 REST API 或提供同等功能的预发布版 Azure SDK。 权限筛选器属性仅在预览 API 中可用。

出于演示目的，权限字段已启用 retrievable ，以便你可以检查索引中的值。 在生产环境中，应禁用 retrievable 以避免泄露敏感信息。

{
  "name" : "my-adlsgen2-acl-index",
  "fields": [
    {
      "name": "name", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "description", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true    
    },
    {
      "name": "location", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "state", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "AzureSearch_DocumentKey", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
      "stored": true,
      "key": true
    },
    { 
      "name": "UserIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "userIds", 
      "searchable": true, "filterable": false, "retrievable": true
    },
    { 
      "name": "GroupIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "groupIds", 
      "searchable": true, "filterable": false, "retrievable": true
    },
    { 
      "name": "RbacScope", "type": "Edm.String", 
      "permissionFilter": "rbacScope", 
      "searchable": true, "filterable": false, "retrievable": true
    }
  ],
  "permissionFilterOption": "enabled"
}

创建数据源

修改数据源配置以指定索引器权限引入和要编制索引的权限元数据的类型。

数据源需要 indexerPermissionOptions。

在本教程中，使用系统分配的托管标识进行身份验证连接。

{
    "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": "parks",
    "query": null
    }
}

创建并运行索引器

权限引入的索引器配置主要涉及从权限元数据定义 fieldMappings 。

{
  "name" : "my-adlsgen2-acl-indexer",
  "dataSourceName" : "my-adlsgen2-acl-datasource",
  "targetIndexName" : "my-adlsgen2-acl-index",
  "parameters": {
    "batchSize": null,
    "maxFailedItems": 0,
    "maxFailedItemsPerBatch": 0,
    "configuration": {
      "dataToExtract": "contentAndMetadata",
      "parsingMode": "delimitedText",
      "firstLineContainsHeaders": true,
      "delimitedTextDelimiter": ",",
      "delimitedTextHeaders": ""
      },
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
    ]
  }
}

创建索引器并立即运行后，文件内容以及权限元数据信息将索引到索引中。

运行查询以检查结果

现在文档已经加载好，你可以使用文档 - 搜索 POST (REST) 对其发出查询。

URI 扩展为包含查询输入，该输入是使用 /docs/search 运算符指定的。 查询令牌将在请求标头中传递。 有关详细信息，请参阅查询时 ACL 和 RBAC 强制实施。

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2025-08-01-preview
Authorization: Bearer {{search-token}}
x-ms-query-source-authorization: {{search-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,location,GroupIds",
    "orderby": "name asc"
}

相关内容

  • Last updated on