Compartir a través de

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

En este tutorial se muestra cómo indexar las listas de control de acceso (ACL) de Azure Data Lake Storage (ADLS) Gen2 y el ámbito de control de acceso basado en roles (RBAC) en un índice de búsqueda utilizando 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:

  • Configuración del ámbito y las ACL de RBAC en un adlsgen2 origen de datos
  • Creación de un índice de Azure AI Search que contenga campos de información de permisos
  • Creación y ejecución de un indexador para ingerir información de permisos en un índice desde un origen de datos
  • Buscar el índice que acaba de crear.

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

Prerrequisitos

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

  • Autenticación y autorización de Microsoft Entra ID. Los servicios y las apps deben estar en el mismo tenant. Las asignaciones de roles se usan para cada conexión autenticada. Los usuarios y grupos deben estar en el mismo inquilino. Debe tener usuarios y grupos con los que trabajar. La creación de inquilinos y entidades de seguridad está fuera del ámbito de este tutorial.

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

  • Archivos en una estructura jerárquica de carpetas. Este tutorial parte de la demostración de ADLS Gen2 sobre la estructura de carpetas 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.

  • Azure AI Search, cualquier región. Se requiere el nivel básico o superior para el soporte de identidades administradas.

  • Visual Studio Code con un cliente REST o un cliente de Python y un paquete de Jupyter.

Preparación de datos de ejemplo

Cargue los datos de ejemplo de parques de estado 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 autorización del identificador de Entra de Microsoft. Revise esta lista de comprobación para asegurarse de que está preparado.

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.

Siga 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 Group conjuntos en lugar de User asignar conjuntos directamente.

  1. Conceda a la identidad del servicio de búsqueda acceso de lectura al contenedor. El indexador se conecta a Azure Storage utilizando 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 Azure Portal 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 nuevas entidades 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 pública.

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 versión preliminar más reciente o un paquete de Azure SDK en versión preliminar 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 se ha retrievable habilitado para que pueda comprobar 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 en ellos mediante Documentación: Search 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=2025-11-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

  • Last updated on