Use un indexador de SharePoint 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)

La ingesta de metadatos de permisos de SharePoint (versión preliminar) utiliza un indexador de Búsqueda de Azure AI para conservar los metadatos de permisos, como las listas de control de acceso (ACL), junto con otros contenidos de SharePoint en Microsoft 365. El indexador almacena los permisos como metadatos en cada documento indexado. En el momento de la consulta, los usuarios solo reciben documentos a los que tienen permiso para acceder.

diagrama de arquitectura

Requisitos previos

• Búsqueda de Azure AI en un nivel facturable (Básico o superior) en cualquier región.

• SharePoint en sitios, bibliotecas, carpetas y archivos de Microsoft 365 con permisos configurados.

• Complete todos los pasos de configuración de la documentación del indexador SharePoint, aplicando los requisitos específicos de la ACL descritos en este artículo.

• Configure los permisos de aplicación de Microsoft Entra y una credencial adecuada para su caso. Consulte Permisos por escenario de ACL. La ingesta de ACL requiere permisos de la aplicación. No se admiten permisos delegados. Para decidir entre permisos de aplicación y permisos delegados, consulte Elegir la configuración de permisos.

• API REST versión 2026-08-01-preview o un paquete de SDK de versión preliminar equivalente.

Limitaciones

• Las actualizaciones incrementales de ACL requieren la API REST 2026-05-01-preview o posterior. En versiones anteriores de la API en versión preliminar, el sistema captura las ACL solo en la primera ingesta de cada elemento. Los cambios de permisos posteriores requieren reindexación explícita. Para conocer los pasos de migración, consulte Sincronización de permisos entre contenido indexado y de origen.

• Los cambios de permisos del ámbito principal no se detectan automáticamente en las ejecuciones posteriores del indexador. Para ver las opciones de actualización, consulte Sincronizar permisos entre contenido indexado y de origen.

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

• En esta versión preliminar no se admiten las siguientes características:

  • Directivas de gestión de la información de SharePoint aplicables al acceso de usuario. El sistema no evalúa, ingiere ni respeta estas directivas en el momento de la consulta.

  • Enlaces que se pueden compartir con el ámbito configurado en "Cualquiera" o "Personas de su organización". Solo se admiten enlaces con el ámbito configurado en "Personas específicas".

  • Grupos de SharePoint (como los grupos Propietarios, Miembros y Visitantes) son compatibles a partir de la versión 2026-05-01-preview de la API REST. Consulte Configure SharePoint groups support. En versiones preliminares anteriores de la API, solo se admiten grupos de SharePoint que se corresponden con grupos de Microsoft Entra.

• Las siguientes características del indexador no admiten la herencia de permisos en documentos indexados que se originan en SharePoint. 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, la publicación de imágenes no es compatible con los orígenes de conocimiento que incorporan las ACL de SharePoint.

  • Caché de enriquecimiento del indexador

  • Sesiones de depuración

Compatibilidad con el modelo de permisos de SharePoint

Esta versión preliminar admite ACL básicas para documentos, elementos de lista y páginas de sitio ASPX modernas.

Relaciones de grupo compatibles

La transitividad de grupos de Microsoft Entra se aplica dentro de Microsoft Entra. No expande los grupos de Microsoft Entra que sean miembros de grupos de SharePoint.

Cómo se evalúan los permisos jerárquicos

Los permisos de SharePoint heredan la jerarquía de Sitio → Biblioteca → Carpeta → Archivo, a menos que se interrumpa la herencia.

Durante la ingesta, el indexador recopila identificadores de usuario y grupo (ID) en cada nivel y calcula la ACL efectiva para cada archivo.

Permisos según el escenario de ACL

Los permisos de aplicación de Microsoft Entra y el tipo de credencial necesarios para la ingesta de ACL dependen de los tipos de elementos y de grupos que indexe. En el registro de aplicaciones, todos los permisos se agregan en permisos> de APIAgregar un permiso y la credencial federada se agrega en Certificados y secretos>Credenciales federadas. Para obtener instrucciones y capturas de pantalla paso a paso, consulte Step 3: Crear un registro de aplicación de Microsoft Entra y Configurar la aplicación registrada con una identidad administrada.

Una credencial federada autentica la aplicación mediante una identidad administrada de confianza en lugar de un secreto de cliente. La misma credencial federada se utiliza tanto para la ingesta (indexador) como para la evaluación en tiempo de consulta de los grupos de sitios de SharePoint. Para conocer los pasos de configuración, consulte Configuración de la aplicación registrada con una identidad administrada.

Antes de habilitar la ingesta de ACL

Complete estos pasos en la aplicación de Microsoft Entra registrada:

1. Identifique su escenario en la tabla anterior en función de lo que planea indexar (archivos de biblioteca de documentos, elementos de lista, páginas de sitio ASPX) y si se deben respetar los grupos de sitios SharePoint.
2. Abra el registro de la aplicación en el Centro de administración Microsoft Entra y vaya a permisos API>Agregar un permiso.
3. Agregue los permisos Microsoft Graph enumerados para su escenario. Conceda el consentimiento del administrador.
4. Si el escenario también requiere permisos SharePoint, seleccione Agregar un permiso de nuevo, elija la API SharePoint y agregue Sites.FullControl.All (o Sites.Selected). Conceda el consentimiento del administrador.
5. Configure la credencial:
   • Para escenarios solo de Microsoft Graph, puede utilizar un secreto de cliente (Certificados y secretos>Secretos de cliente) o una credencial federada.
   • Para cualquier escenario que incluya permisos de SharePoint, agregue una credencial federada en Certificados y secretos>Credenciales federadas. Consulte Configuración de la aplicación registrada con una identidad administrada.
6. Conceda a la aplicación acceso a los sitios de destino SharePoint (especialmente importante al usar Sites.Selected para el acceso con ámbito) para que pueda leer el contenido y los permisos que desea indexar.

Búsqueda de los identificadores de Microsoft Entra correctos

Cada identificador aparece en una ubicación diferente en el portal de Azure y se asigna a un campo de configuración específico. Utilice esta sección como referencia al configurar la ingestión de ACL de SharePoint con una credencial federada. Se hace referencia a estos identificadores en Configurar la compatibilidad con grupos de SharePoint y en la cadena de conexión del origen de datos.

Identificador de aplicación de credenciales federadas

Para FederatedCredentialApplicationId en la cadena de conexión de la fuente de datos y federatedCredentialId en la definición del índice, utilice el propio ID de aplicación (cliente) de la identidad administrada, no el ID de la aplicación de ingesta.

Identidad administrada asignada por el sistema:

1. Vaya al servicio Búsqueda de Azure AI.
2. Seleccione Seguridad y identidad de red>.
3. En la pestaña Asignado por el sistema, anote el Id. de objeto (entidad de seguridad).
4. Vaya a Microsoft Entra ID>Administrar>Aplicaciones empresariales.
5. Busque el nombre del servicio de búsqueda o pegue el identificador de objeto (principal) en el cuadro de búsqueda.
6. Seleccione el resultado y abra Propiedades. Copie el identificador de aplicación que se muestra aquí, que es el valor de FederatedCredentialApplicationId en el origen de datos y federatedCredentialId en el índice.

Identidad administrada asignada por el usuario:

1. Vaya al recurso de identidad administrada asignada por el usuario.
2. Haga clic en Configuración>Propiedades.
3. Copie el identificador de cliente, que es el valor de FederatedCredentialApplicationId en el origen de datos y federatedCredentialId en el índice.

Configurar el servicio de búsqueda para la ingesta de ACL y la aplicación en tiempo de consulta

Estos pasos configuran su servicio de búsqueda para la ingesta de ACL y habilitan el respeto de ACL durante la consulta.

Elegir dónde rellenar los campos de ACL

La ubicación en la que asigna los campos de metadatos de ACL depende de si el indexador escribe un documento por elemento de origen o varios fragmentos por elemento de origen.

En todos los escenarios con fragmentación, cada fragmento debe incluir los campos de ACL. Los filtros de permisos se aplican a cada documento, por lo que un fragmento sin campos de ACL no puede devolverse al llamador correcto.

1. Configuración del origen de datos

Esta sección es un delta que acompaña al tutorial básico Paso 4: Crear origen de datos. Establezca indexerPermissionOptions en la definición de origen data para permitir la indexación de userIds y groupIds desde documentos de SharePoint.

{
  "name": "my-sharepoint-acl-datasource",
  "type": "sharepoint",
  "indexerPermissionOptions": ["userIds", "groupIds"],
  "credentials": {
    "connectionString": "<connection-string>;"
  },
  "container": {
    "name": "<library-name>",
    "query": "<optional-folder-path>"
  }
}

2. Agregar campos de permiso a la definición de índice

Agregue campos a la definición del esquema de índice para almacenar las ACL y admitir el filtrado en tiempo de consulta.

{
  "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 }
  ],
  "permissionFilterOption": "enabled"
}

Establezca el atributo retrievable en true solo durante el desarrollo para comprobar los valores. Puede cambiar el estado de recuperable de true a false sin necesidad de volver a compilar los índices.

3. Configurar proyecciones de índice en el conjunto de habilidades (si procede)

Cuando la fragmentación está habilitada, el documento primario no se escribe en el índice cuando projectionMode es skipIndexingParentDocuments. Traslade los metadatos ACL a cada fragmento mediante indexProjections.selectors[].mappings.

Si el indexador usa un conjunto de aptitudes con fragmentación de datos, como la aptitud División de texto al habilitar la vectorización integrada, asegúrese de asignar propiedades de ACL a cada fragmento mediante proyecciones de índice. Las // líneas del ejemplo siguiente son anotaciones ilustrativas y no son JSON válidos. Quítelos antes de enviar la solicitud.

PUT https://{service}.search.windows.net/skillsets/{skillset}?api-version=2026-08-01-preview
{
  "name": "my-skillset",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
      "name": "#split",
      "context": "/document",
      "inputs": [{ "name": "text", "source": "/document/content" }],
      "outputs": [{ "name": "textItems", "targetName": "chunks" }]
    }
    // ... (other skills such as embeddings, entity recognition, etc.)
  ],
  "indexProjections": {
    "selectors": [
      {
        "targetIndexName": "chunks-index",
        "parentKeyFieldName": "parentId",          // must exist in target index
        "sourceContext": "/document/chunks/*",     // match your split output path
        "mappings": [
          { "name": "chunkId",           "source": "/document/chunks/*/id" },     // if you create an id per chunk
          { "name": "content",           "source": "/document/chunks/*/text" },   // chunk text
          { "name": "parentId",          "source": "/document/id" },              // parent doc id
          { "name": "UserIds",  "source": "/document/metadata_user_ids" },
          { "name": "GroupIds",  "source": "/document/metadata_group_ids" },
          { "name": "SharePointSiteUrl", "source": "/document/metadata_spo_site_url" } // include when the index has sharePointConnectorAppRegistration (SharePoint groups support)
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}

Las asignaciones de UserIds, GroupIds y SharePointSiteUrl leen metadatos de nivel de origen emitidos por el indexador de SharePoint (/document/metadata_*) y escriben esos valores en cada fragmento.

4. Configurar las asignaciones de campos del indexador para las ACL

Use asignaciones de campos del indexador cuando el indexador escriba un documento por elemento de origen (sin fragmentación) o cuando mantenga un índice primario independiente junto con un índice de fragmentos. Si el conjunto de habilidades fragmenta documentos en un único índice de destino con projectionMode: skipIndexingParentDocuments, las asignaciones de campos que se muestran aquí quedan sustituidas por las indexProjections.mappings del paso anterior para el índice de fragmentos.

Además de la configuración del indexador necesaria, asigne campos de ACL de metadatos sin procesar de SharePoint a los campos de índice.

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

5. Ejecutar el indexador

Los metadatos de ACL se ingieren cuando se ejecuta el indexador. Después de crear o actualizar el indexador (consulte Paso 6: Crear un indexador), desencadene una ejecución para que el indexador ingiere ACL junto con el contenido.

POST https://[service name].search.windows.net/indexers/[indexer-name]/run?api-version=2026-08-01-preview
api-key: [admin key]

Si ha habilitado la ingesta de ACL en un indexador existente que ya ha indexado elementos, llame a /resync con options: ["permissions"] para rellenar de forma retroactiva las ACL de esos elementos, o /resetdocs para volver a extraer elementos específicos.

6. Comprobar la ingesta de ACL

Para confirmar que los valores de ACL se hayan rellenado correctamente:

1. Establezca temporalmente retrievable en true en UserIds y GroupIds de la definición del índice. El cambio retrievable no requiere una recompilación de índices.
2. Ejecute una consulta de lectura elevada que seleccione UserIds y GroupIds, y confirme que las colecciones no estén vacías. En escenarios fragmentados, confirme que cada fragmento contiene ambos campos.
3. Vuelva retrievable a false después de la comprobación.

Configuración de la compatibilidad con grupos de SharePoint

A partir de la versión preliminar 2026-05-01 de la API REST, el indexador de SharePoint puede incorporar las pertenencias a grupos de sitios de SharePoint (Propietarios, Miembros, Visitantes y grupos de sitios personalizados). Aplica estos grupos al realizar la consulta. Los identificadores de grupo de SharePoint se muestran en el campo metadata_group_ids con el prefijo spg: para distinguirlos de los identificadores de objeto de los grupos de Microsoft Entra.

Este tutorial es independiente: complete los pasos en orden para configurar el índice, las asignaciones de campos del indexador y consulte el índice con la aplicación de grupos de sitios de SharePoint.

Los siguientes componentes funcionan conjuntamente para habilitar la resolución de grupos de sitios de SharePoint:

1. Prerrequisitos

• Indizador de SharePoint ya configurado para la ingesta de ACL. Consulte Configuración de las asignaciones de campos del indexador para las ACL.
• Registro de aplicaciones de Microsoft Entra con credencial de identidad federada. Consulte Configuración de la aplicación registrada con una identidad administrada.
• API REST 2026-05-01-preview o una versión posterior.

2. Configurar el índice

Añada la configuración sharePointConnectorAppRegistration y el campo SharePointSiteUrl junto a los campos de filtro de permisos UserIds y GroupIds, para que la estructura completa del índice esté en un solo lugar. Mantenga permissionFilterOption: "enabled".

PUT https://{service}.search.windows.net/indexes/{index}?api-version=2026-08-01-preview
{
  "name": "my-sharepoint-acl-index",
  "sharePointConnectorAppRegistration": {
      "applicationId": "<ingestion-app-client-id>",
      "federatedCredentialId": "<managed-identity-application-id>",
     "tenantId": "<sharepoint-tenant-id>"
  },
  "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": "SharePointSiteUrl", "type": "Edm.String", "sharepointSiteUrl": true, "filterable": false, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

3. Configurar las asignaciones de campos del indexador

Asigne los campos de metadatos de SharePoint a los campos de índice en un único bloque de asignación combinado. Las dos primeras asignaciones son las mismas que se utilizan para la ingesta estándar de ACL; la tercera asignación activa la resolución de grupos de SharePoint.

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids",             "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids",            "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_spo_site_url",  "targetFieldName": "SharePointSiteUrl" }
  ]
}

Si su conjunto de aptitudes fragmenta los documentos (por ejemplo, con la aptitud Dividir texto para vectorización integrada), proyecte SharePointSiteUrl en cada fragmento a través de indexProjections.mappings en su lugar. Consulte Elegir dónde rellenar los campos de ACL.

4. Consulta del índice

No se requiere ningún cambio en el lado cliente. El mismo token x-ms-query-source-authorization activa tanto la aplicación de Microsoft Entra como la de los grupos de sitios de SharePoint. El servicio de búsqueda resuelve en el servidor la pertenencia a grupos de SharePoint mediante sharePointConnectorAppRegistration en el índice.

Para conocer la estructura de la solicitud, consulte el ejemplo de consulta general y el ejemplo específico de SharePoint con aplicación de grupos de sitios de SharePoint.

5. Comprobar

Para confirmar que los identificadores de grupo de SharePoint se han incorporado al índice, ejecute una consulta de lectura con privilegios elevados que seleccione GroupIds y busque valores con el prefijo spg: en la respuesta.

Sincronización de permisos entre contenido indexado y de origen

A partir de la API REST 2026-05-01-preview, los cambios de ACL de los elementos con permisos únicos se detectan y actualizan en cada ejecución correcta del indexador. El indexador usa tokens de cambio de SharePoint para detectar de forma incremental las adiciones y eliminaciones de asignaciones de roles, del mismo modo que detecta los cambios de contenido.

Algunos escenarios todavía requieren una actualización explícita:

Restablecer documentos específicos

Puede restablecer documentos específicos para volver a ingerir completamente el contenido y las ACLs.

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

Resincronizar las ACL en todo el origen de datos

Puede resincronizar el contenido completo de la ACL del conjunto de datos después de la importación inicial. Para que se realice correctamente, esta operación requiere una ejecución del indexador después de la finalización.

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

Después de indexar los datos y las ACL, puede consultar el índice.

Solución de problemas

Si faltan resultados, estos son inesperados o se producen errores en el momento de la consulta después de indexar los metadatos de la ACL, consulte Solución de problemas del filtrado de permisos de SharePoint.

Contenido relacionado

• Indexar contenido de SharePoint en Búsqueda de Azure AI (versión preliminar)
• Aplicación de ACL durante la consulta