Tutorial: Indexación de metadatos de permisos de ADLS Gen2 y consulta con resultados filtrados por permisos (versión preliminar)

En este tutorial se muestra cómo indexar Azure Data Lake Storage (ADLS) Gen2 listas de control de acceso (ACL) y control de acceso basado en roles (RBAC) en el ámbito de un índice de búsqueda mediante un indexador.

También se muestra cómo estructurar una consulta que respeta los permisos de acceso de usuario. Un resultado de consulta exitoso confirma la transferencia de permisos que se produjo durante la indexación.

Para obtener más información sobre la indexación de ACL, consulte Uso de un indexador de ADLS Gen2 para ingerir metadatos de permisos.

En este tutorial, aprenderá a:

Use un cliente REST para completar este tutorial y la API REST de versión preliminar más reciente. Actualmente, no hay compatibilidad con la indexación de ACL en el portal de Azure.

Requisitos previos

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.

• Microsoft Entra ID autenticación y autorización. Los servicios y las aplicaciones deben estar en el mismo entorno. Las asignaciones de roles se usan para cada conexión autenticada. Los usuarios y grupos deben estar en el mismo inquilinato. Debe tener usuarios y grupos con los que trabajar. La creación de inquilinos y entidades de seguridad queda fuera del alcance de este tutorial.

• ADLS Gen2 con un espacio de nombres jerárquico.

• Archivos en una estructura jerárquica de carpetas. Este tutorial asume la demostración de la estructura de carpetas de ADLS Gen2 para el archivo /Oregon/Portland/Data.txt. Este tutorial le guía a través de la asignación de ACL en carpetas y archivos para que pueda completar el ejercicio correctamente.

• Búsqueda de Azure AI, cualquier región. Para tener soporte de identidades administradas, es necesario tener el nivel básico o superior.

• Visual Studio Code con la extensión REST Client.

Preparación de datos de ejemplo

Cargue los datos de ejemplo de state parks en un contenedor de ADLS Gen2. El nombre del contenedor debe ser "parques" y debe tener dos carpetas: "Oregon" y "Washington".

Comprobación de la configuración del servicio de búsqueda

El servicio de búsqueda debe configurarse para la autenticación y la autorización de Microsoft Entra ID. Revise esta lista de comprobación para asegurarse de que está preparado.

• Habilitación del acceso basado en roles

• Configure una identidad administrada asignada por el sistema.

Obtención de un token de identidad personal para las pruebas locales

En este tutorial se supone que un cliente REST en un sistema local se conecta a Azure a través de una conexión a Internet pública.

Seguir estos pasos para adquirir un token de identidad personal y configurar Visual Studio Code para las conexiones locales a los recursos de Azure.

Establecimiento de permisos en ADLS Gen2

Como procedimiento recomendado, use conjuntos Group en lugar de asignar directamente conjuntos User.

1. Conceda a la identidad del servicio de búsqueda acceso de lectura al contenedor. El indexador se conecta a Azure Storage con la identidad del servicio de búsqueda. El servicio de búsqueda debe tener permisos de lector de datos de Storage Blob para recuperar datos.

2. Conceda permisos por grupo o usuario en la jerarquía de archivos. En la jerarquía de archivos, identifique todos los Group conjuntos y User asignados a contenedores, directorios y archivos.

3. Puede usar el portal de Azure para administrar las ACL. En Explorador de almacenamiento, seleccione el directorio Oregon y, a continuación, seleccione Administrar ACL en el menú contextual.

4. Agregue nuevos principios de seguridad para usuarios y grupos.

5. Quite las entidades de seguridad existentes para los grupos propietarios, los usuarios propietarios y otros. Estas entidades de seguridad no se admiten para la indexación de ACL durante la versión preliminar.

Creación de un índice de búsqueda para los metadatos de permisos

Cree un índice que contenga campos para los metadatos de contenido y permisos.

Asegúrese de usar la API REST de la versión preliminar más reciente o un paquete de versión preliminar de SDK de Azure que proporcione una funcionalidad equivalente. Las propiedades del filtro de permisos solo están disponibles en las API de versión preliminar.

Con fines de demostración, el campo de permiso tiene retrievable habilitado para que pueda verificar los valores del índice. En un entorno de producción, debe deshabilitar retrievable para evitar la pérdida de información confidencial.

{
  "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"
}

Creación de un origen de datos

Modifique la configuración del origen de datos para especificar la ingesta de permisos del indexador y los tipos de metadatos de permisos que desea indexar.

Un origen de datos necesita indexerPermissionOptions.

En este tutorial, use una identidad administrada asignada por el sistema para la conexión autenticada.

{
    "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
    }
}

Creación y ejecución del indexador

La configuración del indexador para la ingesta de permisos consiste principalmente en definir fieldMappings a partir de metadatos de permisos.

{
  "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" }
    ]
  }
}

Después de la creación del indexador y la ejecución inmediata, el contenido del archivo junto con la información de metadatos de permisos se indexa en el índice.

Ejecución de una consulta para comprobar los resultados

Ahora que se han cargado los documentos, puede emitir consultas sobre ellos mediante Documentos - Búsqueda mediante POST (REST).

El URI se extiende para incluir una entrada de consulta, que se especifica mediante el /docs/search operador . El token de consulta se pasa en el encabezado de solicitud. Para obtener más información, consulte Aplicación de ACL y RBAC en tiempo de consulta.

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"
}

Contenido relacionado

• https://github.com/Azure-Samples/azure-search-rest-samples/tree/main/acl