Use um indexador SharePoint para ingerir metadados de permissão e filtrar os resultados da pesquisa com base nos direitos de acesso do usuário (versão prévia)

A ingestão de metadados de permissões do SharePoint (versão prévia) usa um indexador do Pesquisa de IA do Azure  para preservar metadados de permissões, como ACLs (listas de controle de acesso), 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 usuários recebem apenas documentos que têm permissão para acessar.

Pré-requisitos

• Pesquisa de IA do Azure  em uma camada faturável (Básica ou superior) em qualquer região.

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

• Conclua todas as etapas de configuração na documentação do indexador do SharePoint, aplicando os requisitos específicos de ACL descritos neste artigo.

• Configure as permissões de aplicativo do Microsoft Entra e uma credencial adequada ao seu cenário. Consulte o cenário de Permissões por ACL. A ingestão de ACL requer permissões de aplicativo. Não há suporte para permissões delegadas. Para decidir entre permissões de aplicativo ou delegadas, consulte Escolha sua configuração de permissões.

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

Limitações

• As atualizações incrementais de ACL exigem a API REST 2026-05-01-preview ou posterior. Nas versões anteriores da API de visualização, o sistema captura ACLs somente na primeira ingestão de cada item. Alterações de permissão posteriores exigem reindexação explícita. Para obter as etapas de migração, consulte Sincronizar permissões entre conteúdo indexado e de origem.

• As alterações de permissão no escopo pai não são detectadas automaticamente em execuções subsequentes do indexador. Para obter as opções de atualização, consulte Sincronizar permissões entre o conteúdo indexado e de origem.

• O portal do Azure não dá suporte a esse recurso.

• Não há suporte para os seguintes recursos nesta versão prévia:

  • Políticas de Gerenciamento de Informações do SharePoint aplicáveis ao acesso do usuário. O sistema não avalia, ingere ou respeita essas políticas no momento da consulta.

  • Links compartilháveis com escopo para "Qualquer pessoa" ou "Pessoas em sua organização". Há suporte apenas para links com escopo para "Pessoas específicas".

  • Grupos do SharePoint (como os grupos Proprietários, Membros e Visitantes) são compatíveis a partir da API REST 2026-05-01-preview. Consulte Configurar suporte a grupos do SharePoint. Nas versões anteriores da API de visualização, somente há suporte a grupos do SharePoint que são resolvidos para grupos do Microsoft Entra.

• Os recursos do indexador a seguir não dão suporte à herança de permissão em documentos indexados provenientes de SharePoint. Se você usar qualquer um desses recursos em um conjunto de habilidades ou indexador, as permissões no nível do documento não serão incluídas no conteúdo indexado.

  • Habilidade de API Web personalizada

  • Repositório de conhecimento, incluindo o repositório de ativos necessário para a exibição de imagens (visualização) na recuperação de agentes. Portanto, o fornecimento de imagens não é compatível com fontes de conhecimento que ingerem ACLs do SharePoint.

  • Cache de enriquecimento do indexador

  • Sessões de depuração

Suporte para o modelo de permissão do SharePoint

Esta prévia oferece suporte a ACLs básicas para documentos, itens de lista e páginas modernas do site ASPX.

Relações de grupo com suporte

A transitividade de grupos do Microsoft Entra se aplica no Microsoft Entra. Ele não expande grupos do Microsoft Entra que são membros dos grupos do SharePoint.

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

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

Durante a ingestão, o indexador reúne identificadores de usuário e grupo (ID) em cada nível e calcula a ACL efetiva para cada arquivo.

Permissões por cenário de ACL

As permissões de aplicativo Microsoft Entra e o tipo de credencial necessários para a ingestão de ACL dependem de quais tipos de item e tipos de grupo você indexa. No registro do aplicativo, todas as permissões são adicionadas em permissões> de APIAdicionar uma permissão e a credencial federada é adicionada em Certificados &segredos>Credenciais federadas. Para obter instruções passo a passo e capturas de tela, consulte Step 3: Criar um registro de aplicativo Microsoft Entra e Configurar o aplicativo registrado com uma identidade gerenciada.

Uma credencial federada autentica o aplicativo usando uma identidade gerenciada confiável em vez de um segredo do cliente. A mesma credencial federada cobre tanto a ingestão (indexador) quanto a avaliação em tempo de consulta de grupos de sites do SharePoint. Para obter as etapas de instalação, consulte Configurar o aplicativo registrado com uma identidade gerenciada.

Antes de habilitar a ingestão de ACL

Conclua estas etapas em seu aplicativo Microsoft Entra registrado:

1. Identifique seu cenário na tabela anterior com base no que você planeja indexar (arquivos de biblioteca de documentos, itens de lista, páginas ASPX do site) e se os grupos de sites do SharePoint devem ser respeitados.
2. Abra o registro do aplicativo no centro de administração do Microsoft Entra e vá para Permissões de API>Adicionar uma permissão.
3. Adicione as permissões de Microsoft Graph listadas para seu cenário. Conceda consentimento do administrador.
4. Se o cenário também exigir permissões do SharePoint, selecione Adicionar uma permissão novamente, escolha a API SharePoint e adicione Sites.FullControl.All (ou Sites.Selected). Conceda consentimento do administrador.
5. Configure a credencial:
   • Para cenários que usam somente o Microsoft Graph, você pode usar um segredo do cliente (Certificates & secrets>Client secrets) ou uma credencial federada.
   • Para qualquer cenário que inclua permissões de SharePoint, adicione uma credencial federada em Certificates & secretsFederated credentials. Consulte Configurar o aplicativo registrado com uma identidade gerenciada.
6. Conceda ao aplicativo acesso aos sites de SharePoint de destino (especialmente importante quando você usa Sites.Selected para acesso com escopo) para que ele possa ler o conteúdo e as permissões que você deseja indexar.

Localizar os identificadores de Microsoft Entra corretos

Cada identificador aparece em um local diferente no portal do Azure e é mapeado para um campo de configuração específico. Use esta seção como referência ao configurar a ingestão de ACL do SharePoint com uma credencial federada. Esses identificadores são mencionados em Configurar o suporte a grupos do SharePoint e na cadeia de conexão da fonte de dados.

ID do aplicativo de credencial federada

Para FederatedCredentialApplicationId na string de conexão da fonte de dados e federatedCredentialId na definição do índice, use o próprio ID do aplicativo (cliente) da identidade gerenciada, não o ID do aplicativo de ingestão.

Identidade gerenciada atribuída pelo sistema:

1. Vá para seu serviço de Pesquisa de IA do Azure .
2. Selecione Segurança + rede>Identidade.
3. Na guia Atribuído pelo sistema, anote o ID do Objeto (principal).
4. Vá para Microsoft Entra ID>Gerenciar>Aplicativos empresariais.
5. Pesquise 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 a ID do aplicativo mostrada aqui, que é o valor da FederatedCredentialApplicationId fonte de dados e federatedCredentialId no índice.

Identidade gerenciada atribuída pelo usuário:

1. Vá para o recurso de identidade gerenciada atribuído pelo usuário.
2. Selecione Configurações>Propriedades.
3. Copie a ID do cliente, que é o valor da FederatedCredentialApplicationId fonte de dados e federatedCredentialId no índice.

Configurar seu serviço de pesquisa para ingestão de ACL e imposição de tempo de consulta

Estas etapas configuram seu serviço de pesquisa para ingestão de ACL e habilitam o respeito às ACL no tempo de consulta.

Escolha onde preencher os campos de ACL

Onde você mapeia os campos de metadados de ACL depende se o indexador grava um documento por item de origem ou várias partes por item de origem.

Em todos os cenários fragmentados, cada parte deve incluir os campos de ACL. Os filtros de permissão se aplicam por documento, portanto, não é possível retornar uma parte dos campos de ACL ausentes para o chamador certo.

1. Configuração da fonte de dados

Esta seção é um complemento ao guia base Etapa 4: Criar fonte de dados. Defina indexerPermissionOptions na definição da fonte de dados para permitir a indexação de userIds e groupIds de 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 de índice

Adicione campos à definição de esquema de índice para armazenar ACLs e dar suporte à 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"
}

Defina o atributo retrievable para true apenas durante o desenvolvimento para verificar os valores. Você pode alterar o valor de retrievable de true para false sem a necessidade de reconstrução do índice.

3. Configurar projeções de índice em seu conjunto de habilidades (se aplicável)

Quando a fragmentação está habilitada, o documento pai não é gravado no índice quando projectionMode é skipIndexingParentDocuments. Carregue os metadados de ACL para cada parte por meio de indexProjections.selectors[].mappings.

Se o indexador usar um conjunto de habilidades com agrupamento de dados, como a habilidade de Divisão de Texto ao habilitar a vetorização integrada, mapeie as propriedades da ACL para cada parte usando projeções de índice. As // linhas no exemplo a seguir são anotações ilustrativas e não são JSON válidas. Remova-os antes de enviar a solicitação.

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 metadados no nível do código-fonte emitidos pelo indexador de SharePoint (/document/metadata_*) e gravam os valores em cada parte.

4. Configurar os mapeamentos de campo do indexador para ACLs

Use mapeamentos de campo do indexador quando o indexador grava um documento por item de origem (sem agrupamento) ou quando você mantém um índice pai separado ao lado de um índice de partes. Se o seu conjunto de competências dividir os documentos em partes em um único índice de destino com projectionMode: skipIndexingParentDocuments, os mapeamentos de campo mostrados aqui serão substituídos pelos indexProjections.mappings da etapa anterior para o índice de fragmentos.

Além da configuração do indexador necessária, mapeie campos ACL de metadados brutos do SharePoint para seus campos de índice.

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

5. Executar o indexador

Os metadados de ACL são ingeridos quando o indexador é executado. Depois de criar ou atualizar o indexador (consulte a Etapa 6: Criar um indexador), dispare uma execução para que o indexador ingera ACLs junto 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 você habilitou a ingestão de ACL em um indexador existente que já indexou itens, chame /resync com options: ["permissions"] para preencher retroativamente as ACLs desses itens, ou /resetdocs para reextrair itens específicos.

6. Verificar a ingestão de ACL

Para confirmar os valores de ACL preenchidos corretamente:

1. Configure temporariamente retrievable como true em UserIds e GroupIds na definição do índice. A alteração retrievable não requer uma recompilação de índice.
2. Execute uma consulta de leitura com privilégios elevados que selecione UserIds e GroupIds, e confirme se as coleções não estão vazias. Para cenários segmentados, confirme se cada bloco contém ambos os campos.
3. Retorne retrievable para false após a verificação.

Configurar o suporte a grupos de SharePoint

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

Este passo a passo é independente: siga as etapas na ordem para configurar o índice, os mapeamentos de campos do indexador e consultar o índice com imposição de grupo de sites do SharePoint.

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

1. Pré-requisitos

• Indexador do SharePoint já configurado para ingestão de ACLs. Consulte Configurar os mapeamentos de campo do indexador para ACLs.
• Registro de aplicativo do Microsoft Entra com credencial de identidade federada. Consulte Configurar o aplicativo registrado com uma identidade gerenciada.
• API REST 2026-05-01-preview ou posterior.

2. Configurar o índice

Adicione a configuração sharePointConnectorAppRegistration e o campo SharePointSiteUrl ao lado dos campos de filtro de permissão UserIds e GroupIds, para que a estrutura completa do índice fique em um só lugar. Mantenha 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 campo do indexador

Mapeie os campos de metadados SharePoint para os campos de índice em um único bloco de mapeamento combinado. Os dois primeiros mapeamentos são os mesmos utilizados 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 conjunto de habilidades dividir os documentos em segmentos (por exemplo, com a habilidade de divisão de texto para vetorização integrada), projete SharePointSiteUrl em cada segmento por meio de indexProjections.mappings. Veja Escolher onde preencher os campos de ACL.

4. Consultar o índice

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

Para ver a estrutura da solicitação, consulte o exemplo de consulta geral e o exemplo específico do SharePoint com imposição de grupo de sites do SharePoint.

5. Verificar

Para confirmar que os IDs de grupo do SharePoint foram indexados, execute uma consulta elevated-read que selecione GroupIds e procure valores com o prefixo spg: na resposta.

Sincronizar permissões entre conteúdo indexado e de origem

A partir da API REST 2026-05-01-preview, as alterações de ACL para itens com permissões exclusivas são detectadas e atualizadas em cada execução bem-sucedida do indexador. O indexador usa tokens de alteração do SharePoint para identificar incrementalmente adições e remoções de atribuições de função, assim como faz com as alterações de conteúdo.

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

Restaurar documentos específicos

Você pode redefinir documentos específicos para ingerir totalmente novamente conteúdo e ACLs.

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

Re-sincronizar ACLs em toda a fonte de dados

Você pode ressincronizar o conteúdo completo da ACL do conjunto de dados após a ingestão inicial. Para ter êxito total, essa operação requer uma execução do 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 seus dados e ACLs, você pode consultar o índice.

Solução de problemas

Para resultados ausentes, inesperados ou com falha no momento da consulta depois que os metadados de ACL forem indexados, consulte Solucionar problemas de filtragem de permissões do SharePoint.

Conteúdo relacionado

• Indexar conteúdo do SharePoint no Pesquisa de IA do Azure  (versão prévia)
• Aplicação da ACL no tempo de consulta