Use um indexador SharePoint para ingerir metadados de permissões e filtrar os resultados da pesquisa com base nos direitos de acesso dos utilizadores (pré-visualização)

A ingestão de metadados de permissões do SharePoint (pré-visualização) utiliza um indexador Pesquisa de IA do Azure para preservar metadados de permissões, como listas de controlo de acesso (ACLs), juntamente com outro conteúdo do SharePoint no Microsoft 365. O indexador armazena as permissões como metadados em cada documento indexado. No momento da consulta, os utilizadores recebem apenas documentos a que têm permissão para aceder.

Diagrama mostrando uma arquitetura de solução RAG com segurança reduzida onde um indexador do SharePoint ingere documentos e metadados de permissões ACL de um site SharePoint, armazenando-os numa Pesquisa de IA do Azure index, e um orquestrador RAG filtra os resultados das pesquisas para que cada utilizador possa recuperar apenas os documentos que está autorizado a aceder.

Pré-requisitos

• Pesquisa de IA do Azure num nível faturável (Básico ou superior) em todas as regiões.

• SharePoint em sites, bibliotecas, pastas e ficheiros do Microsoft 365 com permissões configuradas.

• Complete todos os passos de configuração na documentação do indexador SharePoint, aplicando os requisitos específicos da ACL descritos neste artigo.

• Configure permissões de aplicação Microsoft Entra e uma credencial adequada ao seu cenário. Veja o cenário de permissões por ACL. A ingestão de ACL requer permissões de aplicação. Permissões delegadas não são suportadas. Para decidir entre permissões de aplicação e permissões delegadas, consulte Escolha a configuração das suas permissões.

• versão da API REST 2026-08-01-preview ou um pacote SDK de pré-visualização equivalente.

Limitações

• As atualizações incrementais de ACL requerem a API REST de pré-visualização 2026-05-01 ou posterior. Nas versões anteriores da API de pré-visualização, o sistema captura ACLs apenas na primeira ingestão de cada item. Alterações posteriores de permissões requerem reindexação explícita. Para os passos de migração, veja Sincronizar permissões entre conteúdo indexado e de origem.

• As alterações de permissões do âmbito pai não são detetadas automaticamente em execuções subsequentes do indexador. Para as opções de atualização, consulte Sincronizar permissões entre conteúdo indexado e fonte.

• O portal do Azure não suporta esta funcionalidade.

• Os seguintes recursos não são suportados nesta visualização:

  • SharePoint Políticas de Gestão da Informação aplicáveis ao acesso dos utilizadores. O sistema não avalia, processa nem aplica estas políticas durante a consulta.

  • Links partilháveis com escopo para "Qualquer um" ou "Pessoas na sua organização." Apenas são suportados links com escopo para "Pessoas específicas".

  • grupos do SharePoint (como os grupos Proprietários, Membros e Visitantes) são suportados a partir da API REST 2026-05-01-preview. Veja Configurar o suporte para grupos do SharePoint. Nas versões de pré-visualização anteriores da API, apenas são suportados os grupos do SharePoint que correspondem a grupos do Microsoft Entra.

• As seguintes funcionalidades do indexador não suportam herança de permissões em documentos indexados originados no SharePoint. Se usar alguma destas funcionalidades num conjunto de competências ou indexador, as permissões ao nível do documento não estão incluídas no conteúdo indexado.

  • Funcionalidade de API Web Personalizada

  • Repositório de conhecimento, incluindo o armazenamento de ativos necessário para a disponibilização de imagens (pré-visualização) na recuperação agentiva. Por isso, a disponibilização de imagens não é suportada para fontes de conhecimento que importam ACLs do SharePoint.

  • Cache de enriquecimento do indexador

  • Sessões de depuração

Suporte ao modelo de permissões do SharePoint

Esta versão de pré-visualização suporta ACLs básicas para documentos, itens de lista e páginas modernas de site ASPX.

Relações de grupo apoiadas

A transitividade de grupos do Microsoft Entra aplica-se no Microsoft Entra. Não expande os grupos Microsoft Entra que são membros de grupos SharePoint.

Como as permissões hierárquicas são avaliadas

As permissões do SharePoint herdam a hierarquia de Site → Biblioteca → Pasta → Ficheiro, a menos que a herança seja interrompida.

Durante a ingestão, o indexador recolhe identificadores de utilizador e de grupo (ID) em cada nível e calcula a ACL efetiva para cada ficheiro.

Permissões por cenário de ACL

As permissões da aplicação Microsoft Entra e o tipo de credencial necessários para a ingestão de ACL dependem dos tipos de itens e grupos que indexa. No registo da aplicação, todas as permissões são adicionadas sob permissões da API.>Adicionar uma permissão, e a credencial federada é adicionada em credenciais federadas de Certificados & Segredos>. Para instruções passo a passo e capturas de ecrã, veja Passo 3: Criar um registo de Microsoft Entra aplicação e Configurar a aplicação registada com uma identidade gerida.

Uma credencial federada autentica a aplicação usando uma identidade gerida de confiança em vez de um segredo do cliente. A mesma credencial federada abrange tanto a ingestão (indexador) como a avaliação, no momento da consulta, dos grupos de sites do SharePoint. Para os passos de configuração, consulte Configurar a aplicação registada com uma identidade gerida.

Antes de ativar a ingestão de ACL

Complete estes passos na sua aplicação Microsoft Entra registada:

1. Identifique o seu cenário na tabela anterior com base no que planeia indexar (ficheiros da biblioteca de documentos, itens da lista, páginas ASPX do site) e se os grupos de sites do SharePoint têm de ser respeitados.
2. Abra o registo da sua aplicação no centro de administração Microsoft Entra e vá a APIs permissões>Adicionar uma permissão.
3. Adicione as permissões do Microsoft Graph listadas para o seu cenário. Conceda o consentimento do administrador.
4. Se o seu cenário também exigir permissões SharePoint, selecione novamente Adicionar uma permissão, escolha a API SharePoint e adicione Sites.FullControl.All (ou Sites.Selected). Conceda o consentimento do administrador.
5. Configurar a credencial:
   • Para cenários exclusivos do Microsoft Graph, pode utilizar um segredo do cliente (Certificados & segredos>Segredos do cliente) ou uma credencial federada.
   • Para qualquer cenário que inclua permissões de SharePoint, adicione uma credencial federada em Certificados & Segredoscredenciais federadas. Veja Configurar a aplicação registada com uma identidade gerida.
6. Conceda à aplicação acesso aos sites SharePoint alvo (especialmente importante quando usa Sites.Selected para acesso com âmbito definido) para que possa ler o conteúdo e as permissões que pretende indexar.

Encontre os identificadores corretos da Microsoft Entra

Cada identificador aparece numa localização diferente no portal do Azure e corresponde a um campo de configuração específico. Use esta secção como referência ao configurar a ingestão de ACL do SharePoint com uma credencial federada. Estes identificadores são referidos em Configurar o suporte para grupos do SharePoint e na cadeia de ligação da fonte de dados.

ID da aplicação da credencial federada

Para FederatedCredentialApplicationId na cadeia de ligação da fonte de dados e federatedCredentialId na definição do índice, utilize o ID da própria aplicação (cliente) da identidade gerida, e não o ID da aplicação de ingestão.

Identidade gerenciada atribuída ao sistema:

1. Aceda ao seu serviço Pesquisa de IA do Azure.
2. Selecione Segurança + redes>Identidade.
3. No separador Atribuído pelo sistema, anote o ID do objeto (principal).
4. Aceda a Microsoft Entra ID>Gerenciar>aplicações empresariais.
5. Procure o nome do seu serviço de pesquisa ou cole o ID do Objeto (principal) na caixa de pesquisa.
6. Selecione o resultado e abra Propriedades. Copie o ID da Aplicação mostrado aqui, que é o valor de FederatedCredentialApplicationId na fonte de dados e federatedCredentialId no índice.

Identidade gerenciada atribuída pelo usuário:

1. Vai ao recurso de identidade gerida atribuído pelo utilizador.
2. Selecione Configurações>Propriedades.
3. Copie o ID do Cliente, que é o valor para FederatedCredentialApplicationId na fonte de dados e federatedCredentialId no índice.

Configure o seu serviço de pesquisa para a ingestão da ACL e a aplicação no momento da consulta

Estes passos configuram o seu serviço de pesquisa para a ingestão de ACL e ativam o ACL honoring no momento da consulta.

Escolha onde preencher os campos ACL

O local onde mapear os campos de metadados ACL depende se o indexador escreve um documento por item de origem ou vários blocos por item de origem.

Em todos os cenários segmentados, cada bloco deve incluir os campos ACL. Os filtros de permissões são aplicados por documento, pelo que um bloco sem campos ACL não pode ser devolvido ao chamador correto.

1. Configuração da fonte de dados

Esta secção é um delta em relação à base Passo 4: Guia para criar fonte de dados . Defina indexerPermissionOptions na definição fonte de dados para permitir a indexação de userIds e groupIds dos documentos do SharePoint.

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

2. Adicionar campos de permissão à definição do índice

Adicione campos à definição do seu esquema de índice para armazenar ACLs e suportar filtragem em tempo 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"
}

Atribua retrievable o valor true apenas durante o desenvolvimento para verificar os valores. Podes mudar o recuperável de verdadeiro para falso sem necessidade de reconstruir o índice.

3. Configure projeções de índice no seu conjunto de competências (se aplicável)

Quando a fragmentação está ativada, o documento principal não é gravado no índice quando projectionMode é skipIndexingParentDocuments. Transportar os metadados ACL para cada bloco através de indexProjections.selectors[].mappings.

Se o seu indexador usar um conjunto de competências com fragmentação de dados, como a competência Text Split ao ativar vetorização integrada, certifique-se de mapear propriedades ACL para cada bloco usando projeções de índice. As // linhas no exemplo seguinte são anotações ilustrativas e não são JSON válidas. Remova-os antes de submeteres o pedido.

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"
    }
  }
}

Os mapeamentos UserIds, GroupIds e SharePointSiteUrl leem os metadados ao nível da fonte emitidos pelo indexador SharePoint (/document/metadata_*) e escrevem os valores em cada bloco.

4. Configurar os mapeamentos de campos do indexador para ACLs

Use mapeamentos de campos do indexador quando o indexador escreve um documento por item de origem (sem fragmentação) ou quando mantém um índice pai separado juntamente com um índice de blocos. Se o seu conjunto de competências dividir documentos num único índice de destino com projectionMode: skipIndexingParentDocuments, os mapeamentos de campos apresentados aqui são substituídos pelo indexProjections.mappings da etapa anterior para o índice de segmentos.

Além da configuração obrigatória de indexer, mapeia os campos de metadados brutos da ACL da SharePoint para os seus campos de índice.

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

5. Executar o indexador

Os metadados ACL são ingeridos quando o indexador é executado. Depois de criar ou atualizar o indexador (ver Passo 6: Criar um indexador), desencadeie uma execução para que o indexador absorva ACLs juntamente com o conteúdo.

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

Se ativaste a ingestão de ACL num indexador existente que já tinha indexado itens, chama /resync com options: ["permissions"] para preencher retroativamente as ACLs desses itens, ou /resetdocs para reextrair itens específicos.

6. Verificar a ingestão da ACL

Para confirmar que os valores de ACL foram corretamente preenchidos:

1. Defina temporariamente retrievable como true em UserIds e GroupIds na definição do seu índice. Mudar retrievable não requer uma reconstrução do índice.
2. Execute uma consulta de leitura elevada que selecione UserIds e GroupIds, e confirme que as coleções não estão vazias. Para cenários com fragmentação, confirme que cada bloco contém ambos os campos.
3. Voltar retrievable a false após a verificação.

Configurar suporte para grupos SharePoint

A partir da API REST 2026-05-01-preview, o indexador do SharePoint pode ingerir associações a grupos de sites do SharePoint (Proprietários, Membros, Visitantes e grupos de sites personalizados). Homenageia estes grupos no momento das consultas. Os IDs de grupo do SharePoint são emitidos no campo metadata_group_ids com o prefixo spg: para os distinguir dos IDs de objeto de grupo do Microsoft Entra.

Este tutorial é autónomo: conclua os passos pela ordem indicada para configurar o índice, os mapeamentos de campos no indexador e consultar o índice com aplicação dos grupos de sites do SharePoint.

Os seguintes componentes trabalham em conjunto para permitir a resolução de grupos de sites do SharePoint:

1. Pré-requisitos

• Indexador SharePoint já configurado para ingestão ACL. Consulte Configurar os mapeamentos de campo do indexador para ACLs.
• Registo da aplicação Microsoft Entra com credencial de identidade federada. Veja Configurar a aplicação registada com uma identidade gerida.
• API REST 2026-05-01-preview ou posterior.

2. Configurar o índice

Adicione a configuração sharePointConnectorAppRegistration e o campo SharePointSiteUrl juntamente com os campos de filtro de permissões UserIds e GroupIds, para que a estrutura completa do índice fique num único local. Manter 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 os mapeamentos de campos do indexador

Mapeie os campos de metadados do SharePoint para os campos de índice num único bloco combinado de mapeamento. Os dois primeiros mapeamentos são os mesmos usados para a ingestão padrão de ACL; o terceiro mapeamento ativa a resolução de grupos do SharePoint.

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

Se o seu conjunto de competências dividir documentos em blocos (por exemplo, com a competência Text Split para vetorização integrada), projete SharePointSiteUrl em cada bloco através de indexProjections.mappings. Consulte Escolher onde preencher os campos de ACL.

4. Consultar o índice

Não é necessária qualquer alteração do lado do cliente. O mesmo token x-ms-query-source-authorization ativa a aplicação tanto do Microsoft Entra como do grupo de sites do SharePoint. O serviço de pesquisa determina, no servidor, as associações aos grupos do SharePoint usando sharePointConnectorAppRegistration no índice.

Para a estrutura do pedido, veja o exemplo de consulta geral e o exemplo específico do SharePoint com imposição do grupo de sites.

5. Verificar

Para confirmar se os IDs de grupo do SharePoint foram incluídos no índice, execute uma consulta de leitura elevada que seleciona GroupIds e procure valores com o prefixo spg: na resposta.

Sincronizar permissões entre conteúdos indexados e de origem

A partir da API REST de pré-visualização de 01-05-2026, as alterações às ACL de itens com permissões únicas são detetadas e atualizadas em cada execução bem-sucedida do indexador. O indexador utiliza tokens de alteração do SharePoint para detetar adições e remoções de atribuição de funções de forma incremental, da mesma forma que capta alterações de conteúdo.

Alguns cenários ainda requerem uma atualização explícita:

Reiniciar documentos específicos

Podes reiniciar documentos específicos para ingerir totalmente conteúdo e ACLs.

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

Sincronizar as ACLs em toda a fonte de dados

Pode ressincronizar o conteúdo da ACL do conjunto completo de dados após a ingestão inicial. Para ter sucesso total, esta operação requer a execução de um indexador após a conclusão.

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

Depois de indexar os seus dados e ACLs, pode consultar o índice.

Troubleshooting

Para resultados em falta, inesperados ou com falha no momento da consulta, depois de os metadados ACL serem indexados, consulte Resolver problemas de filtragem de permissões do SharePoint.

Conteúdo relacionado

• Indexar conteúdo do SharePoint no Pesquisa de IA do Azure (pré-visualização)
• Implementação da ACL em tempo de consulta