Aplicación en tiempo de consulta de etiquetas de confidencialidad de Microsoft Purview en Búsqueda de Azure AI (versión preliminar)

En el momento de la consulta, Búsqueda de Azure AI puede aplicar directivas de etiqueta de confidencialidad definidas en Microsoft Purview. Estas directivas incluyen la evaluación de los derechos deEXTRACT uso asociados a cada documento, lo que garantiza que los usuarios solo puedan recuperar documentos a los que tienen permiso para acceder.

Esta funcionalidad amplía control de acceso a nivel de documento para alinearse con los requisitos de protección y cumplimiento de información de su organización administrados en Microsoft Purview.

Cuando se habilita la indexación de etiquetas de confidencialidad de Purview, Búsqueda de Azure AI comprueba los metadatos de etiqueta de cada documento durante el tiempo de consulta. Aplica filtros de acceso basados en directivas de Purview para devolver solo los resultados a los que puede acceder el usuario solicitante.

En este artículo se explica cómo funciona la aplicación de etiquetas de confidencialidad en tiempo de consulta y cómo emitir consultas de búsqueda seguras.

Requisitos previos

• Complete todos los pasos descritos en Uso de indizadores de Búsqueda de Azure AI para ingerir etiquetas de confidencialidad de Microsoft Purview.

• Compruebe que el servicio Búsqueda de Azure AI tiene habilitada su identidad administrada asignada por el sistema (no una identidad administrada asignada por el usuario) y que contiene las Content.SuperUser asignaciones de roles y UnifiedPolicy.Tenant.Read . La aplicación en el momento de la consulta depende de los metadatos de etiquetas que el indexador solo puede extraer cuando la identidad asignada por el sistema tiene la configuración correcta. Consulte el paso 1 del artículo de configuración del indexador.

• Tanto el servicio Búsqueda de Azure AI como el usuario que emite la consulta deben estar en el mismo inquilino Microsoft Entra.

• la versión 2025-11-01-preview o posterior de la API REST, o un paquete de SDK de versión preliminar equivalente, para consultar el índice. La funcionalidad de lectura con privilegios elevados y el registro de auditoría de Purview requieren 2026-05-01-preview o una versión posterior.

• Autentique las consultas mediante Azure control de acceso basado en rol (RBAC), no claves de API. Cuando las etiquetas de confidencialidad de Purview están habilitadas, el acceso a la clave de API está restringido a la recuperación del esquema de índice.

Limitaciones

• No se admiten las cuentas de invitado ni las consultas entre inquilinos.

• Las API de Autocompletar y Suggest no se admiten para los índices habilitados para Purview.

• Si se produce un error en la evaluación de etiquetas, el servicio devuelve un código de error HTTP específico en lugar de un conjunto de resultados parcial o sin filtrar. Para obtener la lista completa de códigos de error y causas, consulte Solución de errores de consulta.

• El sistema evalúa las etiquetas solo tal como existían en el momento de la última ejecución del indexador. Es posible que los cambios de etiqueta recientes no se reflejen hasta la siguiente reindexación programada.

Cómo funciona la aplicación de la confidencialidad de las etiquetas en tiempo de consulta

Al consultar un índice que incluye etiquetas de confidencialidad de Microsoft Purview, Búsqueda de Azure AI comprueba las directivas de Purview asociadas antes de devolver los resultados. De este modo, la consulta devuelve solo los documentos a los que se permite el acceso del token de usuario.

1. Entrada de identidad de usuario y rol de aplicación

En el momento de la consulta, Búsqueda de Azure AI valida ambas:

• El rol de RBAC de la aplicación que realizar la llamada, que se indica en el encabezado Authorization. El rol mínimo necesario es Search Index Data Reader. Para obtener más información, revise la guía Búsqueda de Azure AI RBAC.
• La identidad del usuario mediante el token, proporcionada en el x-ms-query-source-authorization del encabezado.

Ambos son necesarios para autorizar la visibilidad basada en etiquetas.

2. Evaluación de etiquetas de sensibilidad

Cuando se recibe una solicitud de consulta, Búsqueda de Azure AI evalúa:

1. Campo sensitivityLabel de cada documento indexado (extraído de Microsoft Purview durante la ingesta).
2. Los permisos efectivos de Purview del usuario, definidos por Microsoft Entra ID y la directiva de etiquetas de Purview.

Si el usuario no está autorizado para la etiqueta de confidencialidad de un documento con EXTRACT permisos, ese documento se excluye de los resultados de la consulta.

3. Filtrado seguro de resultados

Búsqueda de Azure AI aplica el filtro de seguridad después de todos los filtros definidos por el usuario y los pasos de puntuación.
Solo se incluye un documento en el conjunto de resultados final si:

• La aplicación que realiza la llamada tiene una asignación de roles válida (a través de RBAC) y
• El token de identidad de usuario representado por x-ms-query-source-authorization es válido y se permite ver el contenido con la etiqueta de confidencialidad del documento.

Si se produce un error en cualquiera de las condiciones, se omite el documento de los resultados.

Adquisición de un token de acceso de usuario

Para consultar Búsqueda de Azure AI mediante el contexto de usuario, debe adquirir un token de acceso que represente al usuario que ha iniciado sesión. El enfoque que use depende de si está probando localmente con su propio token, si tiene acceso al documento de origen o implementa el flujo de aplicación que requiere pasar el token de usuario final.

Para escenarios de prueba

Para las pruebas locales, puede recuperar un token de acceso de usuario mediante CLI de Azure:

$token = az account get-access-token `
  --resource https://search.azure.com `
  --query accessToken `
  --output tsv

Este método usa la sesión de inicio de la CLI de Azure actual, para que pueda usar el contexto de los documentos que tengan asignados permisos EXTRACT a través de etiquetas de confidencialidad. Este método está pensado solo para escenarios de desarrollo y validación.

Adquisición de tokens para escenarios de OBO

Las aplicaciones que implementan el flujo on-behalf-of (OBO) deben adquirir tokens a través de Microsoft Entra ID utilizando una biblioteca de autenticación compatible, como la Biblioteca de autenticación de Microsoft (MSAL).

En escenarios de OBO, solicite el token de acceso para la API de nivel inferior a la que llama la aplicación. Por ejemplo, al llamar a Búsqueda de Azure AI, el URI del recurso es https://search.azure.com/.default.

El .default ámbito solicita todos los permisos delegados que la aplicación ha preconsentado para el recurso especificado.

Los permisos de etiqueta de confidencialidad, incluidos EXTRACT, no se representan como ámbitos de OAuth. El servicio posterior, como Búsqueda de Azure AI, evalúa estos permisos en tiempo de ejecución en función de la identidad del usuario incluida en el token y de la directiva de etiqueta de confidencialidad aplicada.

Ejemplo de consulta

A continuación se muestra un ejemplo de una solicitud de consulta que utiliza la aplicación de etiquetas de confidencialidad de Microsoft Purview.

Pase el token de la aplicación como token de portador en el encabezado Authorization. Pase el token de usuario como valor de token sin procesar en el encabezado x-ms-query-source-authorization, sin el prefijo Bearer.

POST  {{endpoint}}/indexes/sensitivity-docs/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{app-query-token}}
x-ms-query-source-authorization: {{user-query-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "title,summary,sensitivityLabel",
    "orderby": "title asc"
}

Lectura con privilegios elevados para investigaciones administrativas (versión preliminar)

La lectura con privilegios elevados permite a un desarrollador autorizado devolver documentos etiquetados que el usuario que realiza la llamada normalmente no puede ver, al tiempo que emite una entrada de registro de auditoría de Microsoft Purview para cada documento que devuelve la solicitud. Úselo para revisiones de cumplimiento, eDiscovery, respuesta a incidentes y otras investigaciones administrativas en las que se requiere un registro auditable de acceso.

La lectura con privilegios elevados está disponible en los índices habilitados para Purview en la API REST versión 2026-05-01-preview y versiones posteriores.

Cómo funciona la lectura con privilegios elevados

1. La aplicación que realiza la llamada establece el x-ms-enable-elevated-read: true encabezado en la solicitud de búsqueda.

2. Búsqueda de Azure AI omite la comprobación de acceso basada en etiquetas por documento y devuelve documentos coincidentes, independientemente de los permisos de EXTRACT del usuario solicitante en cada etiqueta.

3. Para cada documento de la respuesta, Búsqueda de Azure AI emite una entrada al registro de auditoría Microsoft Purview en nombre del inquilino solicitante. Una única solicitud de búsqueda que devuelve N documentos genera N entradas de auditoría.

4. Las entradas de auditoría se cargan en Purview de forma asincrónica después de que se devuelva la respuesta de búsqueda.

Asignación de roles necesaria

El usuario desarrollador que realiza la llamada debe tener el rol Colaborador de datos de índice de búsqueda en el servicio de búsqueda o el ámbito de índice. El Lector de datos de índice de búsqueda no es suficiente. La lectura con privilegios elevados falla con 403 Forbidden si el rol no está asignado. Para obtener más información sobre los roles de Búsqueda de Azure AI, consulte Connect to Búsqueda de Azure AI using roles.

Cuando el encabezado x-ms-enable-elevated-read se establece en true, no se permite utilizar el encabezado x-ms-query-source-authorization.

Ejemplo de lectura con privilegios elevados

POST  {{endpoint}}/indexes/sensitivity-docs/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{contributor-token}}
x-ms-enable-elevated-read: true
Content-Type: application/json

{
    "search": "*",
    "select": "title,summary,sensitivityLabel",
    "orderby": "title asc"
}

Campos de auditoría enviados a Microsoft Purview

Cada entrada de auditoría sigue el esquema de la API de actividad de administración de Office 365 e incluye los siguientes campos.

Degradación correcta

Si Búsqueda de Azure AI no puede acceder a Microsoft Purview mientras procesa una consulta, como durante una interrupción transitoria de Purview, omite la evaluación de etiquetas para esa solicitud. El comportamiento depende de si la solicitud incluye un token de identidad de usuario:

• Solicitudes de lectura con privilegios elevados (x-ms-enable-elevated-read: true): se produce un error en la solicitud con 5xx. Búsqueda de Azure AI no devuelve documentos etiquetados sin poder emitir primero registros de auditoría.

• Solicitudes estándar impuestas por etiqueta (con x-ms-query-source-authorization): La solicitud falla con 5xx. Búsqueda de Azure AI no devuelve resultados parciales o sin filtrar cuando no puede evaluar las directivas de etiqueta.

• Las llamadas sin x-ms-query-source-authorization emitidas por una aplicación con al menos el rol Lector de datos de índice de búsqueda: la solicitud se procesa correctamente y devuelve solo los documentos que no tienen una etiqueta de confidencialidad. Los documentos etiquetados se omiten de la respuesta.

Esta ruta de acceso degradada solo está pensada para flujos de trabajo no orientados al usuario que aceptan explícitamente resultados sin etiquetar. No confíe en ella para las experiencias de búsqueda del usuario final.

Para ver la lista completa de códigos de error que se devuelven durante la evaluación de las etiquetas de confidencialidad en el momento de la consulta, consulta Solución de problemas de errores de consulta.

Buscar registros de auditoría de lectura con privilegios elevados en Microsoft Purview

Búsqueda de Azure AI carga entradas de auditoría en el registro de auditoría de Microsoft Purview del inquilino que realiza la llamada. Para investigar la actividad de lectura con privilegios elevados:

1. En el Microsoft Purview portal, seleccione Solutions>Audit.

2. Seleccione Audit Search y, a continuación, filtre por intervalo de fechas, usuario o el tipo de registro Búsqueda de Azure AI.

3. Abra una entrada para ver los campos de esquema estándar y los campos personalizados de Búsqueda de Azure AI, incluidos SensitivityLabelName, DocumentDataSourceType y DocumentDataSourceId.

Para obtener instrucciones paso a paso sobre cómo ejecutar búsquedas de auditoría, comportamiento de retención y roles necesarios de Purview, consulte Buscar el registro de auditoría en el portal de Microsoft Purview.

Control de etiquetas de confidencialidad en Búsqueda de Azure AI

Cuando Búsqueda de Azure AI indexa el contenido del documento con etiquetas de confidencialidad de orígenes como SharePoint, Azure Blob y otros, almacena tanto el contenido como los metadatos de la etiqueta. La consulta de búsqueda devuelve contenido indexado junto con el GUID que identifica la etiqueta de confidencialidad aplicada al documento, solo si el usuario tiene acceso a datos EXTRACT para ese documento asignado a través de la definición de etiqueta de confidencialidad. Este GUID identifica de forma única la etiqueta, pero no incluye propiedades legibles para personas, como el nombre de la etiqueta o los permisos asociados.

Tenga en cuenta que el GUID, por sí solo, es insuficiente para escenarios que incluyen la interfaz de usuario, ya que las etiquetas de sensibilidad suelen llevar otros controles de directiva aplicados por Microsoft Purview Information Protection, como permisos de impresión o restricciones de captura de pantalla y grabación de pantalla. Búsqueda de Azure AI no expone estas funcionalidades.

Para mostrar nombres de etiqueta o aplicar restricciones específicas de la interfaz de usuario, la aplicación debe llamar al punto de conexión de Microsoft Purview Information Protection para recuperar los metadatos de etiqueta completos y los permisos asociados.

Puede usar el GUID devuelto por Búsqueda de Azure AI para resolver las propiedades de etiqueta y llamar a las API de etiquetas de Purview Labels para capturar el nombre de etiqueta, la descripción y la configuración de directiva.

Solucionar errores de consulta

Cuando se produce un error en la evaluación de etiquetas de confidencialidad en tiempo de consulta, Búsqueda de Azure AI devuelve un código de error HTTP específico que identifica la causa. El servicio nunca devuelve un conjunto de resultados parcial o sin filtrar. Si no se pueden evaluar las directivas de etiqueta, se produce un error en la consulta en lugar de exponer contenido no etiquetado o no autorizado.

400 Solicitud incorrecta

Un error 400 indica un problema con la configuración del índice o los encabezados de solicitud. Corrija la configuración antes de reintentar.

401 No autorizado

Un error 401 indica un problema con el token de autorización o los permisos de Purview de la aplicación.

502 Error de puerta de enlace

Un error 502 indica un error de conectividad entre Búsqueda de Azure AI y Microsoft Purview. Estos errores suelen ser transitorios.

Error 504 de tiempo de espera del gateway

Un error 504 indica que Microsoft Purview no respondió en el tiempo permitido.

Configuración de pruebas de un extremo a otro

Para ayudarte a validar la configuración de las etiquetas de confidencialidad en Búsqueda de Azure AI, consulta la configuración de referencia de principio a fin.

En este repositorio se muestra cómo:

• Configurar la sincronización y el respeto de las etiquetas de confidencialidad en Búsqueda de Azure AI
• Prueba los escenarios de ingesta y de aplicación en el momento de la consulta para documentos con etiquetas de confidencialidad.
• Extrae el nombre de la etiqueta y expónlo como parte de las citas utilizadas en tus aplicaciones o agentes RAG.