Solucionar problemas de filtragem de permissões do SharePoint no Pesquisa de IA do Azure  (versão prévia)

Use este artigo se a filtragem de permissões em tempo de consulta para conteúdo indexado SharePoint retornar resultados ausentes ou inesperados ou se uma consulta filtrada por permissão falhar.

Pré-requisitos

• Um índice populado pelo SharePoint no indexador Microsoft 365 com a ingestão de ACL configurada.
• Filtragem de permissões em tempo de consulta configurada conforme descrita em aplicação de ACL e RBAC em tempo de consulta.
• versão 2026-08-01-preview da API REST ou um pacote de SDK de pré-visualização equivalente quando você usa grupos de sites do SharePoint.
• Acesso à definição de índice, ao status do indexador gerado ou explícito e às permissões de SharePoint para um usuário de teste.
• Colaborador de Dados do Índice de Pesquisa ou permissão de leitura elevada equivalente, se precisar comparar resultados filtrados e não filtrados.

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

Conclua essas verificações em ordem. Pare quando o resultado observado indicar a configuração ou a permissão que precisa de correção.

1. Confirme se a falha ocorre no momento da consulta

Este artigo aborda a filtragem de permissões depois que SharePoint conteúdo e metadados de ACL são indexados.

• Se a criação da fonte de dados ou um indexador executar relatórios Invalid AAD tenant, siga a correção do locatário do Microsoft Entra.
• Se você precisar corrigir TenantId, a autenticação ou a cadeia de conexão da fonte de dados, consulte Configurar o indexador do SharePoint no Microsoft 365.
• Se UserIds, GroupIdsou SharePointSiteUrl estiver ausente durante a indexação, use a tabela de solução de problemas de ingestão de ACL.

Continue por aqui somente quando existirem metadados de permissão indexados e o sintoma ocorrer quando você consultá-los.

2. Identificar as três identidades

Registre qual identidade preenche cada função. Não substitua um identificador por outro.

3. Verifique a configuração de filtro de permissão

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

1. Confirme se o índice está com permissionFilterOption definido como enabled.
2. Confirme que UserIds e GroupIds tenham os valores corretos de permissionFilter.
3. Para grupos de sites do SharePoint, confirme se o índice tem sharePointConnectorAppRegistration e um campo SharePointSiteUrl com sharepointSiteUrl: true.
4. Confirme se cada documento indexado ou parte carrega os campos de permissão aplicáveis. Se o conjunto de habilidades usa projeções de índice, verifique se os campos ACL estão em indexProjections.mappings.

Se algum valor estiver ausente, retorne para Configurar seu serviço de pesquisa para ingestão de ACL e imposição de tempo de consulta.

4. Verifique o token de consulta com segurança

Nunca faça logon, cole em uma solicitação de suporte ou compartilhe um token de acesso completo. Decodificar somente o conteúdo do token localmente e limpar identificadores antes de capturar a saída de diagnóstico.

1. Confirme se a solicitação inclui x-ms-query-source-authorization com um token delegado atual para o usuário de teste.
2. Decodifique a carga útil localmente e confirme se oid identifica o usuário de teste desejado. Registre um valor higienizado, como <test-user-object-id>.
3. Reautenticar o usuário e tentar novamente se o token estiver ausente ou expirado.

Se o token de usuário for omitido, o conteúdo protegido por permissão não será retornado. O Authorization cabeçalho sozinho não substitui x-ms-query-source-authorization.

5. Verificar permissões de Microsoft Entra

1. Confirme se os valores indexados UserIds ou GroupIds contêm a ID do objeto do Microsoft Entra esperada. Use uma consulta de leitura elevada apenas para esta comparação de diagnóstico.
2. Confirme se o usuário de teste possui uma atribuição direta ou faz parte do grupo do Microsoft Entra atribuído por meio de associação transitiva a grupos do Microsoft Entra.
3. Se o grupo Microsoft Entra estiver aninhado em um grupo do SharePoint, altere a atribuição. Essa relação mista não é expandida e pode causar resultados ausentes. Adicione o usuário diretamente ao grupo do SharePoint ou conceda permissão por meio de uma atribuição a um grupo do Microsoft Entra compatível.

Para obter o limite de suporte exato, consulte relações de grupo com suporte.

6. Verificar as permissões do grupo de sites do SharePoint

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

1. Use uma consulta de leitura privilegiada para confirmar se GroupIds contém o ID de grupo esperado com o prefixo spg: e se SharePointSiteUrl identifica o site de origem.
2. Confirme se o usuário de teste é um membro direto desse grupo do Sharepoint.
3. Confirme se o índice sharePointConnectorAppRegistration usa os identificadores e permissões exigidos pelo suporte de grupos de SharePoint.

Se os campos indexados estiverem vazios ou obsoletos, corrija a ingestão ou sincronize as permissões de SharePoint antes de reteste da consulta.

7. Verificar a solicitação de consulta

1. Use a versão 2026-08-01-preview da API REST ou um pacote de SDK de versão preliminar equivalente para filtros de permissão de grupo de sites do SharePoint.
2. Confirme se Authorization autentica um principal que pode consultar o índice.
3. Confirme se x-ms-query-source-authorization contém o token delegado do usuário de teste.
4. Tente novamente a mesma consulta sem filtros não relacionados ou alterações de classificação para que você possa isolar o comportamento de permissão.

Use o exemplo de consulta geral como proprietário do formato da solicitação. Não inclua tokens completos em logs ou solicitações salvas.

8. Comparar os resultados esperados e reais

1. Escolha um documento que o usuário de teste possa acessar e um documento que o usuário não possa acessar no SharePoint.
2. Execute a consulta filtrada por permissão como o usuário de teste e registre apenas chaves de documento ou outros identificadores não seguros.
3. Execute uma consulta com leitura elevada e compare os valores armazenados UserIds, GroupIds e SharePointSiteUrl com as permissões de origem.
4. Se a leitura elevada retorna o documento esperado, mas a consulta do usuário não o retorna, concentre-se no token do usuário 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 use-o para retornar resultados irrestritos aos usuários finais.

9. Registrar detalhes de correlação da solicitação

Se a consulta ainda falhar, capture a versão da API, o carimbo de data/hora UTC, o corpo da solicitação sanitizado, o status HTTP, os cabeçalhos da resposta e qualquer ID de solicitação ou de correlação retornado 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 usuário e URLs específicas do locatário antes de compartilhar o diagnóstico com Suporte da Microsoft.

Conteúdo relacionado

• Imposição de ACL e RBAC no momento da consulta
• Usar um indexador SharePoint para ingerir metadados de permissão
• Configurar o indexador do SharePoint no Microsoft 365