Resolver problemas com filtragem de permissões do SharePoint no Pesquisa de IA do Azure (pré-visualização)

Note

O Pesquisa de IA do Azure está disponível através do portal Azure, APIs REST e SDKs do Azure. Também sustenta o Foundry IQ, a camada de conhecimento gerida que transforma conteúdos empresariais em bases de conhecimento reutilizáveis e conscientes de permissões para agentes no portal Microsoft Foundry.

Utilize este artigo se a filtragem de permissões no momento da consulta para conteúdo do SharePoint indexado devolver resultados incompletos ou inesperados, ou se uma consulta filtrada por permissões falhar.

Pré-requisitos

  • Um índice preenchido pelo SharePoint no indexador Microsoft 365 com a ingestão ACL configurada.
  • Filtragem de permissões em tempo de consulta configurada conforme descrito em ACL em tempo de consulta e aplicação de RBAC.
  • Versão 2026-08-01-preview da API REST ou um pacote de SDK de pré-visualização equivalente quando usas grupos de sites do SharePoint.
  • Acesso à definição do índice, ao estado do indexador gerado ou explícito, e às permissões do SharePoint para um utilizador de teste.
  • Search Index Data Contributor ou uma permissão equivalente de leitura elevada se precisar de comparar resultados filtrados e não filtrados.

Siga a árvore de decisão de resolução de problemas

Conclua estas verificações pela ordem indicada. Pare quando o resultado observado identificar a configuração ou permissão que necessita de correção.

1. Confirmar que a falha ocorre no momento da consulta

Este artigo aborda a filtragem de permissões após a indexação do conteúdo SharePoint e dos metadados ACL.

Continue aqui apenas quando existirem metadados de permissão indexados e o sintoma ocorrer quando os consulta.

2. Identificar as três identidades

Regista qual a identidade que ocupa cada função. Não substitua um identificador por outro.

Identity Purpose Onde verificar
Utilizador em consulta O token de utilizador delegado em x-ms-query-source-authorization determina quais os documentos protegidos que o utilizador pode recuperar. O fluxo de autenticação da tua aplicação e o pedido de consulta.
Registo da aplicação de ligação SharePoint O sharePointConnectorAppRegistration no índice permite que o Pesquisa de IA do Azure resolva as pertenças de grupos de sites SharePoint do utilizador que faz consultas. A definição do índice e o registo da aplicação descritos em Configurar o suporte para grupos do SharePoint.
Identidade do pedido do Pesquisa de IA do Azure O token de portador do Microsoft Entra no cabeçalho Authorization, ou a chave da API no cabeçalho api-key, autentica o pedido junto do serviço de pesquisa. A identidade deve ter permissão para consultar o índice. O seu cliente de pesquisa e atribuição de função no plano de dados do Pesquisa de IA do Azure.

3. Verifique a configuração do filtro de permissões

Compare o índice, o indexador e os objetos gerados com os artigos aos quais pertencem.

  1. Confirme que o índice tem permissionFilterOption definido como enabled.
  2. Confirma que UserIds e GroupIds têm os valores de permissionFilter corretos.
  3. Para grupos de sites do SharePoint, confirme que o índice tem sharePointConnectorAppRegistration e um SharePointSiteUrl campo com sharepointSiteUrl: true.
  4. Confirme que cada documento indexado ou bloco tem os campos de permissões aplicáveis. Se o conjunto de competências utilizar projeções de índice, verifique se os campos ACL se encontram em indexProjections.mappings.

Se algum valor estiver ausente, volte a Configurar o seu serviço de pesquisa para a ingestão de ACL e a aplicação do tempo de consulta.

4. Verifique o token de consulta em segurança

Nunca faça login, cole um pedido de suporte ou partilhe um token de acesso completo. Decodifica apenas a carga útil do token localmente e limpa os identificadores antes de capturares a saída de diagnóstico.

  1. Confirme que o pedido inclui x-ms-query-source-authorization com um token delegado atual para o utilizador de teste.
  2. Descodifique a carga útil localmente e confirme que oid identifica o utilizador de teste pretendido. Registar um valor sanitizado como <test-user-object-id>.
  3. Reautentique o utilizador e tente novamente se o token estiver em falta ou expirado.

Se o token de utilizador for omitido, o conteúdo protegido por permissão não é devolvido. O Authorization cabeçalho sozinho não substitui x-ms-query-source-authorization.

5. Verifique as permissões do Microsoft Entra

  1. Confirme se o UserIds ou GroupIds indexado contém o ID de objeto do Microsoft Entra esperado. Use apenas uma consulta de leitura elevada para esta comparação diagnóstica.
  2. Confirme que o utilizador do teste tem uma atribuição direta ou chega ao grupo Microsoft Entra atribuído através da filiação transitiva ao grupo Microsoft Entra.
  3. Se o grupo Microsoft Entra estiver aninhado num grupo do SharePoint, altere a atribuição. Esta relação mista não se expande e pode causar resultados falhados. Adicione o utilizador diretamente ao grupo SharePoint, ou conceda permissão através de uma atribuição de grupo Microsoft Entra suportada.

Para o limite exato de apoio, veja Relações de grupo suportadas.

6. Verifique as permissões dos grupos de sites do SharePoint

Conclua este passo quando a ACL do documento depender de um grupo de site do SharePoint de Proprietários, Membros, Visitantes ou personalizado.

  1. Utilize uma consulta de leitura elevada para confirmar que GroupIds contém o ID de grupo esperado com o prefixo spg: e que SharePointSiteUrl identifica o site de origem.
  2. Confirme que o utilizador de teste é membro direto desse grupo do SharePoint.
  3. Confirme que o sharePointConnectorAppRegistration do índice utiliza os identificadores e as permissões necessários para o suporte de grupos do SharePoint.

Se os campos indexados estiverem vazios ou obsoletos, corrige a ingestão ou sincronize as permissões do SharePoint antes de voltar a testar a consulta.

7. Verifique o pedido de consulta

  1. Use a versão 2026-08-01-preview da API REST ou um pacote equivalente do SDK de pré-visualização para filtros de permissões do grupo de sites SharePoint.
  2. Confirmar Authorization autentica um principal que possa consultar o índice.
  3. Confirme que x-ms-query-source-authorization contém o token delegado do utilizador de teste.
  4. Tenta a mesma consulta sem filtros ou alterações de ranking não relacionadas para poderes isolar o comportamento das permissões.

Utilize o exemplo de consulta genérica como referência para a estrutura do pedido. Não inclua tokens completos em pedidos ou registos guardados.

8. Comparar resultados esperados e reais

  1. Escolha um documento ao qual o utilizador de teste possa aceder e um documento ao qual o utilizador não possa aceder no SharePoint.
  2. Execute a consulta com filtro de permissões como utilizador de teste e registre apenas chaves de documentos ou outros identificadores não secretos.
  3. Execute uma consulta de leitura elevada e compare os valores armazenados UserIds, GroupIds, e SharePointSiteUrl com as permissões de origem.
  4. Se uma leitura com privilégios elevados devolver o documento esperado, mas a consulta do utilizador não o devolver, concentre-se no token do utilizador e na resolução de grupos. Se a leitura elevada também falhar, concentre-se na ingestão, mapeamentos e sincronização de ACL.

Uma leitura elevada deve ser investigada. Não o uses para devolver resultados irrestritos aos utilizadores finais.

9. Detalhes da correlação dos pedidos de captura

Se a consulta continuar a falhar, capture a versão da API, o carimbo temporal UTC, o corpo do pedido limpo, o estado HTTP, os cabeçalhos de resposta e qualquer ID de pedido ou correlação devolvido pelo serviço. Inclua o nome do índice e se o mesmo documento aparece em leitura elevada.

Remova tokens de acesso, chaves de API, segredos, nomes de utilizador e URLs específicas de inquilinos antes de partilhar diagnósticos com o Suporte da Microsoft.

Conteúdo relacionado

  • Última atualização a