Indexación de listas de control de acceso de documentos (ACL) mediante las API REST de inserción (versión preliminar)

La ingesta de permisos de nivel de documento a través de las API REST de inserción (versión preliminar) permite indexar documentos junto con sus listas de control de acceso (ACL) asociadas y los roles de control de acceso basado en roles (RBAC) del contenedor. Al insertar contenido en un índice de Búsqueda de Azure AI a través de las API REST de inserción, el servicio conserva esos permisos en el contenido indexado y los aplica en el momento de la consulta.

Entre las características clave se incluyen:

• Control flexible sobre canalizaciones de ingesta.
• Esquema estandarizado para los metadatos de permisos.
• Compatibilidad con permisos jerárquicos, como ACL de nivel de carpeta.

En este artículo se explica cómo usar la API de push REST para indexar metadatos de permisos de nivel de documento en Búsqueda de Azure AI. Este proceso prepara el índice para consultar y aplicar permisos de usuario final en los resultados de búsqueda.

Requisitos previos

• Contenido con metadatos de ACL de Microsoft Entra ID u otro sistema ACL de estilo POSIX. Para los campos ACL userIds y groupIds, utilice identificadores de objeto de Microsoft Entra (GUID), no UPN ni direcciones de correo electrónico. Los identificadores de objeto estables garantizan la coincidencia de identidad confiable en el momento de la consulta, incluso si cambian los atributos de directorio.

• La API REST de la versión preliminar más reciente o un paquete de SDK de Azure en versión preliminar que proporciona características equivalentes.

• Esquema de índice con permissionFilterOption habilitado, además de atributos de campo permissionFilter que almacenan permisos de documento.

Limitaciones

• Un campo ACL con tipo userIds de filtro de permiso o groupIds puede contener como máximo 1000 valores.

• Un índice puede contener como máximo cinco valores únicos entre los campos de tipo rbacScope en todos los documentos. No hay ningún límite en el número de documentos que comparten el mismo valor de rbacScope.

• Se puede actualizar un campo existente para incluir una asignación permissionFilter para el filtrado de metadatos integrado de ACL o RBAC. Para habilitar el filtrado en un índice existente, agregue nuevos campos o actualice los campos existentes para incluir un permissionFilter valor.

• Solo un campo de cada permissionFilter tipo (uno de groupIds, userIdsy rbacScope) puede existir en un índice.

• Cada permissionFilter campo debe tener filterable establecido en true.

• La aplicación de permisos en el momento de la consulta refleja los valores de ACL escritos por última vez en el índice. Si cambian los permisos de origen, esas actualizaciones no se reflejan hasta que vuelva a usar o actualice los documentos afectados. Programe la reingesta incremental o actualizaciones parciales para mantener las ACL actualizadas.

• Esta funcionalidad no se admite actualmente en el portal de Azure.

Creación de un índice con campos de filtro de permisos

La indexación de ACL de documentos y metadatos de RBAC con la API REST requiere la configuración de un esquema de índice que habilita los filtros de permisos y tiene campos con asignaciones de filtros de permisos.

En primer lugar, agregue permissionFilterOption. Los valores válidos son enabled o disabledy debe establecerlos en enabled. Puede cambiarlo a disabled si desea desactivar la funcionalidad de filtro de permisos en el nivel de índice.

En segundo lugar, cree campos de cadena para los metadatos de permiso e incluya permissionFilter. Recuerde que puede tener uno de cada tipo de filtro de permiso.

Este es un esquema de ejemplo básico que incluye todos los permissionFilter tipos:

{  
  "fields": [  
    { "name": "UserIds", "type": "Collection(Edm.String)", "permissionFilter": "userIds", "filterable": true },  
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true },  
    { "name": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true },  
    { "name": "DocumentId", "type": "Edm.String", "key": true }  
  ],
  "permissionFilterOption": "enabled"
}

En el caso de los repositorios empresariales, como SharePoint Online, resuelva los permisos a nivel de documento o de carpeta a los ID de objetos de usuario y grupo de Microsoft Entra durante la ingesta antes de llamar a la API de envío. A continuación, debe almacenar esos identificadores en los campos de permisos correspondientes.

Ejemplo de indexación de api REST

Una vez que tenga un índice con campos de filtro de permisos, puede rellenar esos valores utilizando la API de indexación mediante push, al igual que con cualquier otro campo de un documento. Este es un ejemplo mediante el esquema de índice especificado, donde cada documento especifica la acción de indexación, el campo de clave (DocumentId) y los campos de permisos. Los documentos también deben incluir contenido, pero ese campo se omite en este ejemplo para mayor brevedad.

POST https://exampleservice.search.windows.net/indexes('indexdocumentsexample')/docs/search.index?api-version=2026-08-01-preview
{
  "value": [
    {
      "@search.action": "upload",
      "DocumentId": "1",
      "UserIds": ["00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "11bb11bb-cc22-dd33-ee44-55ff55ff55ff", "22cc22cc-dd33-ee44-ff55-66aa66aa66aa"],
      "GroupIds": ["none"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-01"
    },
    {
      "@search.action": "merge",
      "DocumentId": "2",
      "UserIds": ["all"],
      "GroupIds": ["33dd33dd-ee44-ff55-aa66-77bb77bb77bb", "44ee44ee-ff55-aa66-bb77-88cc88cc88cc"]
    },
    {
      "@search.action": "mergeOrUpload",
      "DocumentId": "3",
      "UserIds": ["1cdd8521-38cf-49ab-b483-17ddaa48f68f"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-03"
    }
  ]
}

Reglas de resolución de acceso de ACL

En esta sección se explica cómo determina el sistema el acceso a documentos de un usuario en función de los campos de permisos de cada documento. Estos campos son ACL (userIds y , donde groupIds incluye grupos de seguridad y Grupos de Microsoft 365) o un ámbito de RBAC (groupIdsrbacScope). Azure evalúa el ámbito de RBAC y las ACL en un orden definido, coherente con el modelo de permisos de ADLS Gen2.

Un usuario obtiene acceso si cumple una de las siguientes condiciones: una entrada coincidente de userIds o groupIds, o una asignación de rol de Azure válida para rbacScope. Para obtener información sobre cómo se proporcionan las identidades de los solicitantes en el momento de la consulta, consulte Aplicación de ACL y RBAC en el momento de la consulta.

Valores de ACL especiales "all" y "none"

Los campos de ACL, como userIds y groupIds, suelen contener listas de GUID (identificadores únicos globales) que identifican a los usuarios y grupos con acceso al documento. Se admiten dos valores de cadena especiales, "all" y "none" para estos tipos de campo de ACL. Estos valores actúan como filtros amplios para controlar el acceso a nivel global, como se muestra en la tabla siguiente.

Dado que un usuario debe coincidir solo con un tipo de campo, el valor especial "all" concede acceso público independientemente de cualquier otro valor de campo de ACL. Por el contrario, establecer userIds en "ninguno" o una matriz vacía significa que no se concede acceso a ningún usuario al documento en función del identificador de usuario. Es posible que todavía se les conceda acceso mediante el identificador de grupo coincidente o los metadatos de RBAC.

Ejemplo de control de acceso

En este ejemplo se muestra cómo se resuelven las reglas de acceso a documentos en función de los valores de campo de permisos de userIds, groupIdsy rbacScope. Para mejorar la legibilidad, este escenario usa alias como "user1" y "group1" en lugar de los GUID; en producción, use los identificadores de objeto (GUID) de Microsoft Entra.

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