Aplicação em tempo de consulta de rótulos de confidencialidade do Microsoft Purview na Pesquisa de IA do Azure (versão prévia)

No momento da consulta, Pesquisa de IA do Azure  pode impor políticas de rótulo de confidencialidade definidas em Microsoft Purview. Essas políticas incluem a avaliação dos direitos deEXTRACT uso associados a cada documento, garantindo que os usuários só possam recuperar documentos que têm permissão para acessar.

Essa funcionalidade estende o controle de acesso em nível de documento para se alinhar com os requisitos de proteção da informação e conformidade da sua organização, gerenciados no Microsoft Purview.

Quando a indexação da etiqueta de sensibilidade do Purview está habilitada, o Pesquisa de IA do Azure  verifica os metadados de etiqueta de cada documento durante o tempo de consulta. Ele aplica filtros de acesso com base nas políticas do Purview para retornar apenas os resultados que o usuário solicitante tem permissão para acessar.

Este artigo explica como funciona a aplicação de rótulos de sensibilidade no momento da consulta e como realizar consultas de pesquisa seguras.

Pré-requisitos

• Conclua todos os passos em Usar indexadores de Pesquisa de IA do Azure para ingerir rótulos de sensibilidade do Microsoft Purview.

• Verifique se o serviço Pesquisa de IA do Azure  tem a identidade gerenciada atribuída pelo sistema (e não uma identidade gerenciada atribuída pelo usuário) habilitada e se possui as atribuições de função Content.SuperUser e UnifiedPolicy.Tenant.Read. A imposição de tempo de consulta depende dos metadados de rótulo que o indexador só pode extrair quando a identidade atribuída pelo sistema tiver a configuração correta. Consulte a Etapa 1 no artigo de configuração do indexador.

• O serviço Pesquisa de IA do Azure  e o usuário que está emitindo a consulta devem estar no mesmo locatário Microsoft Entra.

• A API REST versão 2025-11-01-preview ou posterior, ou um pacote SDK de visualização equivalente, para consultar o índice. A funcionalidade de leitura com privilégios elevados e o registro de auditoria do Purview exigem 2026-05-01-preview ou versão posterior.

• Autorizar consultas usando controle de acesso baseado em função do Azure (RBAC), não chaves de API. Quando os rótulos de confidencialidade do Purview estão habilitados, o acesso à chave de API fica restrito à recuperação de esquema de índice.

Limitações

• Não há suporte para contas de convidado e consultas entre locatários.

• APIs de preenchimento automático e sugestão não têm suporte para índices habilitados para Purview.

• Se a avaliação do rótulo falhar, o serviço retornará um código de erro HTTP específico em vez de um conjunto de resultados parcial ou não filtrado. Para obter a lista completa de códigos de erro e causas, consulte Solucionar problemas de erros de consulta.

• O sistema avalia os rótulos apenas como eles existiam no momento da última execução do indexador. Alterações recentes de rótulo podem não ser refletidas até o próximo reindex agendado.

Como funciona a imposição de rótulos de confidencialidade em tempo de consulta

Quando você consulta um índice que inclui rótulos de confidencialidade Microsoft Purview, Pesquisa de IA do Azure  verifica as políticas associadas do Purview antes de retornar os resultados. Dessa forma, a consulta retorna apenas documentos que o token de usuário tem permissão para acessar.

1. Identidade do usuário e entrada de função de aplicativo

No momento da consulta, Pesquisa de IA do Azure  valida ambos:

• A função RBAC do aplicativo de chamada, fornecida no cabeçalho Authorization. A função mínima necessária é Search Index Data Reader. Para obter mais detalhes, examine o guia Pesquisa de IA do Azure  RBAC.
• A identidade do usuário por meio do token, fornecida no x-ms-query-source-authorization cabeçalho.

Ambos são necessários para autorizar a visibilidade baseada em etiquetas.

2. Avaliação do rótulo de confidencialidade

Quando uma solicitação de consulta é recebida, Pesquisa de IA do Azure  avalia:

1. O campo sensitivityLabel em cada documento indexado (extraído de Microsoft Purview durante o processo de ingestão).
2. As permissões efetivas do usuário no Purview, conforme definido pelo Microsoft Entra ID e pela política de rótulo do Purview.

Se o usuário não tiver permissões EXTRACT para o nível de confidencialidade de um documento, esse documento será excluído dos resultados da consulta.

3. Filtragem de resultados segura

Pesquisa de IA do Azure  aplica o filtro de segurança após todos os filtros definidos pelo usuário e etapas de pontuação.
Um documento será incluído no conjunto de resultados final somente se:

• O aplicativo de chamada tem uma atribuição de função válida (via RBAC) e
• O token de identidade do usuário representado por x-ms-query-source-authorization é válido e tem permissão para exibir o conteúdo com o rótulo de confidencialidade do documento.

Se uma das condições falhar, o documento será omitido dos resultados.

Adquirir um token de acesso do usuário

Para consultar Pesquisa de IA do Azure  usando o contexto do usuário, você deve adquirir um token de acesso que represente o usuário conectado. A abordagem que você usa depende se você está testando localmente com seu próprio token, se você tiver acesso ao documento de origem ou implementando o fluxo de aplicativo que requer a passagem do token do usuário final.

Para cenários de teste

Para testes locais, você pode recuperar um token de acesso do usuário usando CLI do Azure:

$token = az account get-access-token `
  --resource https://search.azure.com `
  --query accessToken `
  --output tsv

Essa abordagem utiliza sua sessão atual de login da CLI do Azure, permitindo que você aplique o contexto aos documentos aos quais você tem permissões EXTRACT atribuídas por meio de rótulos de confidencialidade. Esse método destina-se apenas a cenários de desenvolvimento e validação.

Aquisição de token para cenários OBO

Os aplicativos que implementam o fluxo “on-behalf-of” (OBO) devem obter tokens usando o Microsoft Entra ID, por meio de uma biblioteca de autenticação compatível, como a Biblioteca de Autenticação da Microsoft (MSAL).

Em cenários OBO, solicite o token para a API downstream que o aplicativo chama. Por exemplo, ao chamar Pesquisa de IA do Azure , o URI do recurso é https://search.azure.com/.default.

O .default escopo solicita todas as permissões delegadas que o aplicativo preconsentou para o recurso especificado.

As permissões de rótulo de confidencialidade, incluindo EXTRACT, não são representadas como escopos OAuth. O serviço downstream, como Pesquisa de IA do Azure , avalia essas permissões em runtime com base na identidade do usuário no token e na política de rótulo de confidencialidade aplicada.

Exemplo de consulta

Aqui está um exemplo de uma solicitação de consulta que usa a aplicação de rótulos de confidencialidade do Microsoft Purview.

Passe o token do aplicativo como um token de portador no cabeçalho Authorization. Passe o token do usuário como o valor bruto do token no cabeçalho x-ms-query-source-authorization, sem o prefixo Bearer.

POST  {{endpoint}}/indexes/sensitivity-docs/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{app-query-token}}
x-ms-query-source-authorization: {{user-query-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "title,summary,sensitivityLabel",
    "orderby": "title asc"
}

Leitura elevada para investigações administrativas (versão prévia)

A leitura com privilégios elevados permite que um desenvolvedor autorizado retorne documentos rotulados que o usuário que faz a chamada normalmente não pode ver, enquanto gera uma entrada no log de auditoria do Microsoft Purview para cada documento retornado pela solicitação. Use-o para revisões de conformidade, Descoberta Eletrônica, resposta a incidentes e outras investigações administrativas em que um registro auditável de acesso é necessário.

O recurso Elevated read está disponível em índices habilitados para Purview na versão 2026-05-01-preview da API REST e posteriores.

Como funciona a leitura elevada

1. O aplicativo chamador define o cabeçalho x-ms-enable-elevated-read: true na solicitação de busca.

2. O Pesquisa de IA do Azure  ignora a verificação de acesso por rótulo em cada documento e retorna os documentos correspondentes, independentemente das permissões do usuário solicitante sobre cada rótulo EXTRACT.

3. Para cada documento na resposta, Pesquisa de IA do Azure  emite uma entrada para o log de auditoria Microsoft Purview em nome do locatário solicitante. Uma única solicitação de pesquisa que retorna N documentos produz entradas de auditoria N .

4. As entradas de auditoria são carregadas no Purview de forma assíncrona depois que a resposta de pesquisa é retornada.

Atribuição de função necessária

O usuário desenvolvedor que faz a chamada deve ter a função Colaborador de dados de índice de pesquisa no serviço Pesquisa ou no escopo do índice. O Leitor de Dados do Índice de Pesquisa não é suficiente. A leitura elevada falha com 403 Forbidden se a função não tiver sido atribuída. Para obter mais informações sobre as funções do Pesquisa de IA do Azure , consulte Conectar-se ao Pesquisa de IA do Azure  usando funções.

Quando o x-ms-enable-elevated-read cabeçalho é definido como true, o x-ms-query-source-authorization cabeçalho não tem permissão para ser usado.

Exemplo de leitura elevada

POST  {{endpoint}}/indexes/sensitivity-docs/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{contributor-token}}
x-ms-enable-elevated-read: true
Content-Type: application/json

{
    "search": "*",
    "select": "title,summary,sensitivityLabel",
    "orderby": "title asc"
}

Campos de auditoria enviados para Microsoft Purview

Cada entrada de auditoria segue o esquema da API de atividade de gerenciamento do Office 365 e inclui os campos a seguir.

Degradação elegante

Se Pesquisa de IA do Azure  não conseguir alcançar Microsoft Purview durante o processamento de uma consulta, como durante uma interrupção transitória do Purview, ela ignorará a avaliação do rótulo para essa solicitação. O comportamento depende se a solicitação inclui um token de identidade do usuário:

• Solicitações de leitura elevadas (x-ms-enable-elevated-read: true): a solicitação falha com 5xx. Pesquisa de IA do Azure  não retorna documentos rotulados sem antes poder emitir logs de auditoria.

• Requisições padrão impostas por rótulo (com x-ms-query-source-authorization): a requisição falha com 5xx. Pesquisa de IA do Azure  não retorna resultados parciais ou não filtrados quando não consegue avaliar políticas de rótulo.

• Chamadas sem x-ms-query-source-authorization emitidas por um aplicativo com pelo menos a função Search Index Data Reader: a solicitação é bem-sucedida e retorna apenas documentos que não têm um rótulo de confidencialidade. Documentos rotulados são omitidos da resposta.

Esse caminho degradado destina-se apenas a fluxos de trabalho não voltados para o usuário que aceitam explicitamente resultados sem rótulo. Não confie nele para experiências de pesquisa do usuário final.

Para obter a lista completa de códigos de erro retornados durante a avaliação do rótulo de confidencialidade no momento da consulta, confira Solucionar erros de consulta.

Localizar logs de auditoria de leitura com privilégios elevados no Microsoft Purview

O Pesquisa de IA do Azure  envia entradas de auditoria para o log de auditoria do Microsoft Purview do locatário que faz a chamada. Para investigar a alta atividade de leitura:

1. No portal do Microsoft Purview, selecione Soluções>Auditoria.

2. Selecione Audit Search e, em seguida, filtre por intervalo de datas, usuário ou tipo de registro Pesquisa de IA do Azure .

3. Abra uma entrada para exibir os campos de esquema padrão e os campos personalizados Pesquisa de IA do Azure , incluindo SensitivityLabelName, DocumentDataSourceType e DocumentDataSourceId.

Para obter orientações passo a passo sobre como executar pesquisas de auditoria, o comportamento de retenção e as funções do Purview necessárias, consulte Pesquisar no log de auditoria no portal do Microsoft Purview.

Tratamento de rótulo de confidencialidade no Pesquisa de IA do Azure 

Quando o Pesquisa de IA do Azure  indexa o conteúdo de documentos com rótulos de confidencialidade de fontes como SharePoint, Azure Blob e outros, ele armazena tanto o conteúdo quanto os metadados do rótulo. A consulta de pesquisa retorna conteúdo indexado junto com o GUID que identifica o rótulo de confidencialidade aplicado ao documento, somente se o usuário tiver acesso a dados EXTRACT para esse documento atribuído por meio da definição de rótulo de confidencialidade. Esse GUID identifica exclusivamente o rótulo, mas não inclui propriedades legíveis por humanos, como o nome do rótulo ou permissões associadas.

Observe que o GUID sozinho é insuficiente para cenários que incluem a interface do usuário, pois os rótulos de confidencialidade geralmente carregam outros controles de política impostos por Proteção de Informações do Microsoft Purview, como: permissões de impressão ou restrições de captura de tela. Pesquisa de IA do Azure  não apresenta essas funcionalidades.

Para exibir nomes de rótulos e/ou impor restrições específicas da interface do usuário, seu aplicativo deve chamar o ponto de extremidade da Proteção de Informações do Microsoft Purview para recuperar metadados completos do rótulo e as permissões associadas.

Você pode usar o GUID retornado por Pesquisa de IA do Azure  para resolver as propriedades do rótulo e chamar as APIs Purview Labels para buscar o nome do rótulo, a descrição e as configurações de política.

Solucionar erros de consulta

Quando a avaliação do rótulo de confidencialidade em tempo de consulta falha, Pesquisa de IA do Azure  retorna um código de erro HTTP específico que identifica a causa. O serviço nunca retorna um conjunto de resultados parcial ou não filtrado. Se as políticas de rótulo não puderem ser avaliadas, a consulta falhará em vez de expor conteúdo não rotulado ou não autorizado.

400 Solicitação Inválida

Um erro 400 indica um problema com a configuração do índice ou os cabeçalhos de solicitação. Corrija a configuração antes de tentar novamente.

401 Não autorizado

Um erro 401 indica um problema com o token de autorização ou as permissões do Purview do aplicativo.

502 Gateway Incorreto

Um erro 502 indica uma falha de conectividade entre Pesquisa de IA do Azure  e Microsoft Purview. Esses erros normalmente são transitórios.

Tempo limite do gateway 504

Um erro 504 indica que Microsoft Purview não respondeu dentro do tempo permitido.

Configuração de teste de ponta a ponta

Para ajudá-lo a validar sua configuração de rótulos de confidencialidade na Pesquisa de IA do Azure, confira a configuração completa de referência.

Este repositório demonstra como:

• Configurar a sincronização e o cumprimento de rótulos de confidencialidade na Pesquisa de IA do Azure
• Testar cenários de ingestão e aplicação de regras no momento da consulta para documentos com rótulos de confidencialidade
• Extraia o nome do rótulo e exponha-o como parte das citações usadas em seus aplicativos ou agentes RAG.