Uso de un indexador de ADLS Gen2 para ingerir metadatos de permisos y filtrar los resultados de búsqueda en función de los derechos de acceso de los usuarios (versión preliminar)

Azure Data Lake Storage (ADLS) Gen2 admite el acceso por usuario a directorios y archivos a través de listas de control de acceso (ACLs) y control de acceso basado en roles (Azure RBAC). no se admite el control de acceso basado en Attribute (Azure ABAC).

Búsqueda de Azure AI puede ingerir estos metadatos de permisos (versión preliminar) junto con el contenido del documento mediante una API REST en versión preliminar. Los usuarios que carecen de acceso a un directorio o archivo en el almacenamiento no ven los documentos correspondientes en los resultados de búsqueda. Se trata de una de varias estrategias para control de acceso de nivel de documento en Búsqueda de Azure AI.

En este artículo se explica cómo configurar un indexador de ADLS Gen2 o un origen de conocimiento de blobs de ADLS Gen2 para extraer automáticamente los metadatos de permisos en un índice de búsqueda. Complementa a Datos de índice de ADLS Gen2 y Crear un origen de conocimiento de blobs para ADLS Gen2 con información específica de la ingesta de permisos. Para insertar manualmente metadatos de permisos, consulte Indexación de listas de control de acceso (ACL) de documentos mediante la API de inserción.

Requisitos previos

• Microsoft Entra ID autenticación y autorización. Los servicios y las aplicaciones deben estar en el mismo entorno. Los usuarios pueden estar en inquilinos diferentes siempre que todos los inquilinos usen Microsoft Entra ID. Las asignaciones de roles se usan para cada conexión autenticada.

• Búsqueda de Azure AI en un nivel facturable (Básico o superior) en cualquier región. El servicio de búsqueda debe tener habilitado el acceso basado en rol y una identidad administrada asignada por el sistema o asignada por el usuario.

• Blobs de ADLS Gen2 en un espacio de nombres jerárquico, con permisos de usuario otorgados a través de ACL o roles.

• API REST versión 2025-05-01-preview o posterior para la incorporación de permisos del indexador. API REST versión 2025-11-01-preview o posterior para compatibilidad con fuentes de conocimientos. Use la API REST de versión preliminar más reciente o un paquete del SDK de versión preliminar que admita filtros de permisos.

Limitaciones

• El portal de Azure no admite esta característica.

• Se aplican los límites de ADLS Gen2 en las asignaciones de roles y las entradas de ACL .

• Las owning usersowning groups , Othery all () no se admiten durante la versión preliminar. En su lugar, use las asignaciones named users y named groups.

• Las siguientes características del indexador no admiten la herencia de permisos en documentos indexados procedentes de ADLS Gen2. Si usa cualquiera de estas características en un conjunto de aptitudes o indexador, los permisos de nivel de documento no se incluyen en el contenido indizado.

  • Aptitud de API web personalizada

  • Almacén de conocimientos, incluido el almacén de activos necesario para el servicio de imágenes (vista previa) en la recuperación agencial. Por lo tanto, el servicio de imágenes no es compatible con fuentes de conocimiento que incorporen ACL o ámbitos RBAC.

  • Caché de enriquecimiento del indexador

  • Sesiones de depuración

Compatibilidad con el modelo de permisos

En esta sección se comparan las características de control de acceso de nivel de documento entre ADLS Gen2 y Búsqueda de Azure AI. Explica qué mecanismos de control de acceso de Azure Data Lake Storage (ADLS) Gen2 soporta o mapea AI Search. Esto le ayuda a comprender cómo se aplican los permisos en el nivel de documento.

En el momento de la consulta, Búsqueda de Azure AI evalúa primero RBAC de nivel de contenedor y, a continuación, comprueba las entradas de ACL de nivel de documento. Se concede acceso si algún mecanismo lo permite.

Acerca de los permisos jerárquicos de ACL

Los indexadores y los orígenes de conocimiento pueden recuperar asignaciones de ACL del contenedor especificado y todos los directorios que conducen a cada archivo siguiendo el flujo de evaluación de acceso jerárquico de ADLS Gen2. Las listas de acceso efectivas finales para cada archivo se calculan y las diferentes categorías de acceso se indexan en los campos de índice correspondientes.

Por ejemplo, en escenarios comunes de ADLS Gen2 relacionados con los permisos como la ruta del archivo /Oregon/Portland/Data.txt.

El indexador o el origen de conocimiento recopila ACL de cada contenedor y directorio. A continuación, determina el acceso efectivo en niveles inferiores y continúa hasta que resuelve los permisos de cada archivo.

/ 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

Configuración de ADLS Gen2

Un indexador o origen de conocimiento puede recuperar ACL en una cuenta de almacenamiento si se cumplen los siguientes criterios. Para obtener más información sobre las asignaciones de ACL, consulte Asignaciones de ACL de ADLS Gen2.

Autorización

Para indexar, la identidad del servicio de búsqueda debe poseer el permiso Lector de datos de Storage Blob.

Si está probando localmente, también debe tener la asignación de un rol de Lector de datos de Storage Blob. Para obtener más información, consulte Connect to Azure Storage using a managed identity.

Permisos de contenedor raíz:

1. Asigne todos los conjuntos Group y User (entidades de seguridad) en el contenedor raíz / con permisos Read y Execute.

2. Asegúrese de que tanto Read como Execute se agreguen como "permisos predeterminados" para que se propaguen automáticamente a los archivos y directorios recién creados.

Propagación de permisos hacia abajo en la jerarquía de archivos

Aunque los nuevos directorios y archivos heredan permisos, los directorios y archivos existentes no heredan automáticamente estas asignaciones.

Use la herramienta ADLS Gen2 para aplicar ACL de forma recursiva para la propagación de asignaciones en el contenido existente. Esta herramienta propaga las asignaciones de ACL del contenedor raíz a todos los directorios y archivos subyacentes.

Eliminación de permisos excesivos

Después de aplicar las ACL de forma recursiva, revise los permisos de cada directorio y archivo.

Quite cualquier conjunto Group o User que no deba tener acceso a directorios o archivos específicos. Por ejemplo, elimine User2 en la carpeta Portland/, y para la carpeta Idaho retire Group2 y User2 de sus asignaciones, y así sucesivamente.

Estructura de asignaciones de ACL de ejemplo

Este es un diagrama de la estructura de asignación de ACL para la jerarquía de directorios ficticia en la documentación de ADLS Gen2.

Actualización de asignaciones de ACL a lo largo del tiempo

Con el tiempo, a medida que se agregan o modifican nuevas asignaciones de ACL, repita los pasos anteriores para garantizar la correcta propagación y alineación de permisos. Los permisos actualizados en ADLS Gen2 se actualizan en el índice de búsqueda al volver a ingerir el contenido mediante el indexador o el origen de conocimiento.

Configuración de Búsqueda de Azure AI

Recuerde que el servicio de búsqueda debe tener:

• Acceso habilitado por roles
• Identidad administrada configurada

Autorización

Para la indexación, el cliente que emite la llamada API debe tener permiso de colaborador del servicio de búsqueda para crear objetos, el permiso Colaborador de datos de índice de búsqueda para realizar la importación de datos y el Lector de datos de índice de búsqueda para consultar un índice.

Si está realizando pruebas localmente, debe tener las mismas asignaciones de funciones. Para obtener más información, consulte Conectarse a Búsqueda de Azure AI usando roles.

Configuración de un origen de conocimiento

Si usa un origen de conocimiento, las definiciones del origen de conocimiento se usan para generar una canalización de indexación completa (indexador, origen de datos e índice). Las asignaciones de ACL se detectan y se incluyen automáticamente en el índice generado. No es necesario modificar ninguno de los objetos generados si desea la herencia de permisos en el contenido indizado.

Puntos clave sobre la configuración que hacen que funcione en este escenario:

• isADLSGen2 se establece en true, cumpliendo el requisito del origen de datos para este escenario.
• ingestionPermissionOptions especifica identificadores de usuario y grupo.

# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2026-08-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}}"
            }
        }
    }
}
###

Configuración de la indexación basada en indexadores

Si está utilizando un indexador, configure el indexador, el origen de datos y el índice para extraer los metadatos de permisos de los blobs de ADLS Gen2.

Creación del origen de datos

Esta sección complementa los datos de índice de ADLS Gen2 con información específica de la ingesta de permisos junto con el contenido del documento en un índice de Búsqueda de Azure AI.

• El tipo de origen de datos debe ser adlsgen2.

• El origen de datos debe tener indexerPermissionOptions con userIds, groupIdsy/o rbacScope.

  • Para rbacScope, configure la cadena de conexión con el formato de identidad administrada.

  • Para las cadenas de conexión que usan una identidad administrada asignada por el usuario, también debe especificar la identity propiedad .

Ejemplo de JSON con la identidad administrada del sistema:

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

Ejemplo de esquema JSON con una identidad administrada por el usuario en el cadena de conexión:

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

Creación de campos de permisos en el índice

En Búsqueda de Azure AI, asegúrese de que el índice contiene definiciones de campo para los metadatos de permiso. Los metadatos de permisos se pueden indexar cuando indexerPermissionOptions se especifican en la definición del origen de datos.

Atributos de esquema recomendados para ACL (UserIds, GroupIds) y Ámbito de RBAC:

• Campo Identificador de usuario (ID) con el valor de permissionFilter userIds.
• Campo de identificadores de grupo con el groupIdsvalor permissionFilter.
• Campo Ámbito de RBAC con el valor de permissionFilter rbacScope.
• Propiedad permissionFilterOption para habilitar el filtrado en tiempo de consulta.
• Uso de campos de cadena para metadatos de permisos
• Establezca filterable en verdadero en todos los campos.

Observe que retrievable es false. Puede establecerlo en true durante el desarrollo para comprobar que los permisos están presentes, pero recuerde volver a establecerlo en false antes de realizar la implementación en un entorno de producción.

Ejemplo de esquema 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"
}

Configuración del indexador

Las asignaciones de campos dentro de un indexador establecen la ruta de acceso de datos a los campos de un índice. Los campos objetivo y de destino que varían por nombre o tipo de datos requieren una asignación explícita de campos. Es posible que los siguientes campos de metadatos de ADLS Gen2 necesiten asignaciones de campos si cambia el nombre del campo:

• metadata_user_ids (Collection(Edm.String)): la lista de identificadores de usuario de ACL.
• metadata_group_ids (Collection(Edm.String)): la lista de identificadores de grupo de ACL.
• metadata_rbac_scope (Edm.String): el ámbito RBAC del contenedor.

Especifique fieldMappings en el indexador para enrutar los metadatos de permiso a los campos de destino durante la indexación.

Ejemplo de esquema JSON:

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

Recomendaciones y procedimientos recomendados

• Planee cuidadosamente la estructura de carpetas de ADLS Gen2 antes de crear las carpetas.

• Organice las identidades en grupos y use grupos siempre que sea posible, en lugar de conceder acceso directamente a usuarios individuales. Agregar continuamente usuarios individuales en lugar de aplicar grupos aumenta el número de entradas de control de acceso que se deben rastrear y evaluar. No seguir este procedimiento recomendado puede provocar actualizaciones de metadatos de seguridad más frecuentes necesarias para el índice a medida que cambian estos metadatos, lo que provoca mayores retrasos e ineficiencias en el proceso de actualización.

Sincronización de permisos entre contenido indexado y de origen

Habilitar el enriquecimiento de ACL o RBAC en un indexador solo funciona automáticamente en dos situaciones:

• El primer recorrido completo del indexador o rastreo de datos: se capturan todos los metadatos de permisos existentes en ese momento para cada documento.

• Documentos completamente nuevos agregados después de habilitar la compatibilidad con ACL/RBAC: su información de ACL/RBAC se incorpora junto con su contenido.

Si cambia los permisos de documento, como agregar un usuario a una ACL o actualizar una asignación de roles, el cambio no aparece en el índice de búsqueda a menos que indique al indexador que rastree de nuevo los metadatos de permisos del documento.

Elija uno de los siguientes mecanismos, en función del número de elementos modificados:

Ejemplo de API resetdocs (versión preliminar):

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

Ejemplo de API de resincronización (versión preliminar):

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

Seguimiento de eliminación

Para administrar la eliminación de blobs de forma eficaz, asegúrese de que el seguimiento de eliminación está habilitado antes de que el indexador se ejecute por primera vez. Esta funcionalidad permite al sistema detectar blobs eliminados en tu fuente y quitarlos del índice.

Contenido relacionado

• Conéctate a Búsqueda de Azure AI utilizando roles
• Aplicación de ACL y RBAC durante la consulta
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API