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

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

注释

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。 它也是 Foundry IQ 的基础；Foundry IQ 是一个托管式知识层，可将企业内容转化为供 Microsoft Foundry 门户中的智能体使用的、可复用且具备权限感知能力的知识库。

Important

标记为“预览”的特性、功能或属性不受服务级别协议 (SLA) 保障，不建议用于生产工作负载，并且在正式发布之前可能会更改或受到限制。 Azure AI 搜索预览条款适用于所有预览功能，无论是独立功能还是正式版功能的一部分。

本教程演示Azure Data Lake Storage（ADLS） Gen2 权限元数据引入（预览），其中Azure AI 搜索索引器将访问控制列表（ACL）和基于角色的访问控制（RBAC）范围添加到搜索索引。

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

有关索引 ACL 的详细信息，请参阅 使用 ADLS Gen2 索引器引入权限元数据。

本教程介绍如何：

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

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

先决条件

  • 具有活动订阅的Azure帐户。 免费创建帐户。

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

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

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

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

  • 带有 REST 客户端扩展的 Visual Studio Code。

准备示例数据

将 state parks 示例数据上传到 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" }
    ]
  }
}

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

运行查询以检查结果

加载文档后，可以使用 文档 - 搜索帖子（REST）对其发出查询。

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

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2026-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