Filtros de seguridad para restringir los resultados en Búsqueda de Azure AI

Note

Búsqueda de Azure AI está disponible a través del portal de Azure, las API REST y los SDK de Azure. También respalda Foundry IQ, la capa de conocimiento administrada que transforma el contenido empresarial en bases de conocimiento reutilizables y compatibles con permisos para agentes en el portal de Microsoft Foundry.

Para las soluciones de búsqueda que no pueden usar la compatibilidad integrada de la lista de control de acceso (ACL) para la autorización de nivel de documento, Búsqueda de Azure AI admite la creación de un filtro que recorta los resultados de la búsqueda en función de una cadena que contenga un grupo o una identidad de usuario.

En este artículo se describe un patrón para el filtrado de seguridad que incluye los pasos siguientes:

  • Ensamblar documentos de origen con el contenido necesario, incluida una cadena para almacenar una identidad
  • Crear un campo en el índice de búsqueda para los identificadores principales
  • Insertar los documentos en el índice de búsqueda para la indexación
  • Consultar el índice con la función de filtro search.in

Concluye con vínculos a demostraciones y ejemplos que proporcionan aprendizaje práctico. Se recomienda revisar primero este artículo para comprender el patrón.

Acerca del patrón de filtro de seguridad

El patrón de filtrado de seguridad simula la autorización a nivel de documento mediante un filtro OData estándar que incluye o excluye un resultado de búsqueda basado en una cadena que consiste en un principal de seguridad. No hay autenticación ni autorización a través de la entidad de seguridad. La principal es simplemente una cadena, utilizada en una expresión de filtro, para incluir o excluir un documento de los resultados de búsqueda.

Hay varias maneras de conseguir el filtrado de seguridad. Una forma es a través de una disyunción complicada de expresiones de igualdad: por ejemplo, Id eq 'id1' or Id eq 'id2', y así sucesivamente. Este enfoque es propenso a errores, es difícil de mantener y, en los casos en que la lista contiene cientos o miles de valores, ralentiza muchos segundos el tiempo de respuesta de consulta.

Una mejor solución es usar la función search.in para los filtros de seguridad, como se describe en este artículo. Si utiliza search.in(Id, 'id1, id2, ...') en lugar de una expresión de igualdad, puede esperar tiempos de respuesta de fracciones de segundo.

Requisitos previos

  • Campo de cadena que contiene un grupo o una identidad de usuario, como un identificador de objeto de Microsoft Entra.

  • Otros campos del mismo documento deben proporcionar un contenido accesible para ese grupo o usuario. En los siguientes documentos JSON, los campos "security_id" contienen identidades que se usan en un filtro de seguridad y el nombre, salario y estado civil se incluyen si la identidad del autor de la llamada coincide con el "security_id" del documento.

    {  
    "Employee-1": {  
        "employee_id": "100-1000-10-1-10000-1",
        "name": "Abram",   
        "salary": 75000,   
        "married": true,
        "security_id": "alphanumeric-object-id-for-employee-1"
    },
    "Employee-2": {  
        "employee_id": "200-2000-20-2-20000-2",
        "name": "Adams",   
        "salary": 75000,   
        "married": true,
        "security_id": "alphanumeric-object-id-for-employee-2"
    } 
}

Creación del campo de seguridad

En el índice de búsqueda, dentro de la colección de campos, necesita un campo que contenga la identidad de grupo o usuario, similar al campo ficticio "security_id" del ejemplo anterior.

  1. Agregue un campo de seguridad como Collection(Edm.String).

  2. Establezca el atributo filterable del campo establecido en true.

  3. Establezca el atributo del retrievable campo en false para que no se devuelva como parte de la respuesta de búsqueda.

  4. Los índices requieren una clave de documento. El campo "file_id" cumple ese requisito.

  5. Los índices también deben contener contenido que se puede buscar y recuperar. Los campos "file_name" y "file_description" representan eso en este ejemplo.

    El siguiente esquema de índice cumple los requisitos de campo. Los documentos que se indexen en Búsqueda de Azure AI deben tener valores para todos estos campos, incluido el group_ids. Una consulta devuelve el documento con file_namesecured_file_b cuando su filtro de seguridad incluye group_id1 o group_id2.

    POST https://[search service].search.windows.net/indexes/securedfiles/docs/index?api-version=2026-04-01
{
     "name": "securedfiles",  
     "fields": [
         {"name": "file_id", "type": "Edm.String", "key": true, "searchable": false },
         {"name": "file_name", "type": "Edm.String", "searchable": true },
         {"name": "file_description", "type": "Edm.String", "searchable": true },
         {"name": "group_ids", "type": "Collection(Edm.String)", "filterable": true, "retrievable": false }
     ]
 }

Note

Establecer retrievable en false impide group_ids que se devuelva como parte de un documento en los resultados de la búsqueda. No es un mecanismo de ofuscación de contenido ni de seguridad a nivel de campo. En este patrón, se aplica la autorización de nivel de documento aplicando el filtro de seguridad a cada consulta. No confíe en retrievable solo para proteger la información confidencial de todas las características de consulta o formatos de respuesta.

Inserción de datos en el índice mediante la API REST

Rellene el índice de búsqueda con documentos que proporcionen valores para cada campo de la colección de campos, incluidos los valores del campo de seguridad. La Búsqueda de Azure AI no proporciona API ni características para rellenar específicamente el campo de seguridad. Sin embargo, varios de los ejemplos enumerados al final de este artículo explican técnicas para rellenar este campo.

En la Búsqueda de Azure AI, los enfoques para cargar datos son:

  • Una sola operación de inserción o extracción (indexador) que importa documentos rellenados con todos los campos.
  • Varias operaciones de inserción o extracción. Siempre que las operaciones de importación secundarias tengan como destino el identificador de documento correcto, puede cargar campos individualmente a través de varias importaciones.

En el ejemplo siguiente se muestra una única solicitud HTTP POST a la colección de documentos del punto de conexión de la dirección URL del índice (consulte Documentos: índice). El cuerpo de la solicitud HTTP es una representación JSON de los documentos que se van a indexar:

POST https://[search service].search.windows.net/indexes/securedfiles/docs/index?api-version=2026-04-01
{
    "value": [
        {
            "@search.action": "upload",
            "file_id": "1",
            "file_name": "secured_file_a",
            "file_description": "File access is restricted to Human Resources.",
            "group_ids": ["group_id1"]
        },
        {
            "@search.action": "upload",
            "file_id": "2",
            "file_name": "secured_file_b",
            "file_description": "File access is restricted to Human Resources and Recruiting.",
            "group_ids": ["group_id1", "group_id2"]
        },
        {
            "@search.action": "upload",
            "file_id": "3",
            "file_name": "secured_file_c",
            "file_description": "File access is restricted to Operations and Logistics.",
            "group_ids": ["group_id5", "group_id6"]
        }
    ]
}

Si necesita actualizar un documento existente con la lista de grupos, puede usar la acción merge o mergeOrUpload:

{
    "value": [
        {
            "@search.action": "mergeOrUpload",
            "file_id": "3",
            "group_ids": ["group_id7", "group_id8", "group_id9"]
        }
    ]
}

Aplicación del filtro de seguridad en la consulta

Para recortar documentos basados en el acceso group_ids, debe emitir una consulta de búsqueda con un filtro group_ids/any(g:search.in(g, 'group_id1, group_id2,...')), donde "group_id1, group_id2,..." son los grupos a los que pertenece el emisor de la solicitud de búsqueda.

Este filtro coincide con todos los documentos para los que el campo group_ids contiene uno de los identificadores especificados. Para obtener detalles completos sobre cómo buscar documentos con Búsqueda de Azure AI, puede leer Búsqueda en documentos.

En este ejemplo se muestra cómo configurar la consulta mediante una solicitud POST.

Emita la solicitud HTTP POST y especifique el filtro en el cuerpo de la solicitud:

POST https://[service name].search.windows.net/indexes/securedfiles/docs/search?api-version=2026-04-01

{
   "filter":"group_ids/any(g:search.in(g, 'group_id1, group_id2'))"  
}

Deberías recuperar los documentos en los que group_ids contenga "group_id1" o "group_id2". En otras palabras, obtendrá los documentos a los que el emisor de la solicitud tiene acceso de lectura.

{
 [
   {
    "@search.score":1.0,
     "file_id":"1",
     "file_name":"secured_file_a",
   },
   {
     "@search.score":1.0,
     "file_id":"2",
     "file_name":"secured_file_b"
   }
 ]
}

Pasos siguientes

En este artículo se describe un patrón para filtrar los resultados en función de la identidad del usuario y la función search.in(). Puede utilizar esta función para pasar los identificadores principales del usuario que realiza la solicitud, a fin de compararlos con los identificadores principales asociados a cada documento objetivo. Cuando se controla una solicitud de búsqueda, la función search.in filtra los resultados de la búsqueda para los que ninguna de las entidades de seguridad del usuario tiene acceso de lectura. Los identificadores principales pueden representar cosas como grupos de seguridad, roles o incluso la identidad de un usuario.

Para obtener más ejemplos, demostraciones y vídeos:

  • Last updated on