Imposição no momento da consulta das etiquetas de sensibilidade do Microsoft Purview no Pesquisa de IA do Azure (pré-visualização)

No momento da consulta, Pesquisa de IA do Azure pode aplicar políticas de etiquetas de sensibilidade definidas em Microsoft Purview. Estas políticas incluem a avaliação dos EXTRACT direitos de utilização associados a cada documento, garantindo que os utilizadores só possam recuperar os documentos a que têm permissão para aceder.

Esta capacidade estende o controlo de acesso ao nível de documentos para alinhar com os requisitos de proteção e conformidade da sua organização geridos em Microsoft Purview.

Quando a indexação de etiquetas de sensibilidade Purview está ativada, o Pesquisa de IA do Azure verifica os metadados de etiquetas de cada documento durante o tempo de consulta. Aplica filtros de acesso baseados nas políticas do Purview para devolver apenas os resultados a que o utilizador solicitante pode aceder.

Este artigo explica como funciona a aplicação de etiquetas de sensibilidade ao tempo de consulta e como emitir consultas de pesquisa seguras.

Pré-requisitos

• Complete todos os passos em Usar indexadores do Pesquisa de IA do Azure para ingerir etiquetas de sensibilidade do Microsoft Purview.

• Verifique se o serviço Pesquisa de IA do Azure tem a sua identidade gerida atribuída pelo sistema (não uma identidade gerida atribuída pelo utilizador) ativada e que detém as Content.SuperUser atribuições de funções e UnifiedPolicy.Tenant.Read . A imposição no momento da consulta depende dos metadados do rótulo que o indexador só consegue extrair quando a identidade atribuída pelo sistema tem a configuração correta. Veja o Passo 1 no artigo sobre configuração do indexador.

• Tanto o serviço Pesquisa de IA do Azure como o utilizador que emite a consulta devem estar no mesmo tenant Microsoft Entra.

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

• Autenticar consultas usando controlo de acesso baseado em funções Azure (RBAC), não chaves API. Quando as etiquetas de sensibilidade do Purview estão ativadas, o acesso à chave API é restrito à recuperação do esquema do índice.

Limitações

• Contas de convidados e consultas entre entidades não são suportadas.

• As APIs de Autocomplete e Sugestão não são suportadas para índices com Purview.

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

• O sistema avalia as etiquetas apenas tal como existiam na altura da última execução do indexador. As alterações recentes de rótulo podem não se refletir até à próxima reindexação agendada.

Como funciona a aplicação de etiquetas de sensibilidade ao tempo de consulta

Quando consulta um índice que inclui etiquetas de sensibilidade do Microsoft Purview, o Pesquisa de IA do Azure verifica as políticas associadas ao Purview antes de devolver os resultados. Desta forma, a consulta devolve apenas documentos a que o token de utilizador pode aceder.

1. Identidade do utilizador e entrada da função da aplicação

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

• O papel RBAC da aplicação chamadora, fornecido no cabeçalho Authorization. A função mínima necessária é Search Index Data Reader. Para mais detalhes, consulte o guia Pesquisa de IA do Azure RBAC.
• A identidade do utilizador via token, fornecida no x-ms-query-source-authorization cabeçalho.

Ambos são necessários para autorizar a visibilidade baseada em rótulos.

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

Quando é recebido um pedido de consulta, o Pesquisa de IA do Azure avalia:

1. O campo sensitivityLabel em cada documento indexado (extraído durante a ingestão no Microsoft Purview).
2. As permissões efetivas do utilizador no Purview, conforme definidas pelo Microsoft Entra ID e pela Política de Rótulos do Purview.

Se o utilizador não estiver autorizado a usar a etiqueta de sensibilidade de um documento com EXTRACT permissões, esse documento é excluído dos resultados da consulta.

3. Filtragem segura de resultados

O Pesquisa de IA do Azure aplica o filtro de segurança após todos os filtros e passos de pontuação definidos pelo utilizador.
Um documento é incluído no conjunto final de resultados apenas se:

• A aplicação que efetua a chamada tem uma atribuição de função válida (via RBAC), e
• O token de identidade do utilizador representado por x-ms-query-source-authorization é válido e autorizado a visualizar conteúdo com a etiqueta de sensibilidade do documento.

Se qualquer uma das condições falhar, o documento é omitido dos resultados.

Adquirir um token de acesso de utilizador

Para consultar o Pesquisa de IA do Azure usando o contexto do utilizador, deve adquirir um token de acesso que represente o utilizador autenticado. A abordagem que utiliza depende se está a testar localmente com o seu próprio token, se tem acesso ao documento de origem ou a implementar o fluxo de aplicação que exige a passagem do token do utilizador final.

Para testar cenários

Para testes locais, pode obter um token de acesso de utilizador usando CLI do Azure:

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

Esta abordagem utiliza a sua sessão de login atual do CLI do Azure, por isso pode utilizar o contexto em documentos para os quais tem EXTRACT permissões atribuídas através de rótulos de sensibilidade. Este método destina-se apenas a cenários de desenvolvimento e validação.

Aquisição de tokens para cenários OBO

As aplicações que implementam o fluxo on-behalf-of (OBO) devem adquirir tokens através do Microsoft Entra ID utilizando uma biblioteca de autenticação suportada, como a Biblioteca de Autenticação da Microsoft (MSAL).

Em cenários OBO, peça o token da API downstream que a aplicação invoca. Por exemplo, ao chamar Pesquisa de IA do Azure, o URI do recurso é https://search.azure.com/.default.

O .default âmbito solicita todas as permissões delegadas que a aplicação previamente consentiu para o recurso especificado.

As permissões de etiquetas de sensibilidade, incluindo EXTRACT, não são representadas como escopos OAuth. O serviço downstream, como o Pesquisa de IA do Azure, avalia estas permissões em tempo de execução com base na identidade do utilizador no token e na política de etiquetas de sensibilidade aplicada.

Exemplo de consulta

Aqui está um exemplo de um pedido de consulta que utiliza a imposição de etiquetas de sensibilidade do Microsoft Purview.

Passe o token de aplicação como token portador no Authorization cabeçalho. Transmita o token do utilizador como o valor do token em bruto 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"
}

Acesso de leitura elevado para investigações administrativas (versão preliminar)

A leitura elevada permite que um programador autorizado devolva documentos rotulados que o utilizador que faz a chamada normalmente não pode ver, gerando uma entrada no registo de auditoria do Microsoft Purview para cada documento que o pedido devolver. Utilize-o para revisões de conformidade, eDiscovery, resposta a incidentes e outras investigações administrativas onde é necessário um registo auditável de acesso.

A leitura avançada está disponível nos índices com Purview ativado na versão da API REST 2026-05-01-preview e em versões posteriores.

Como funciona a leitura elevada

1. A aplicação cliente define o cabeçalho x-ms-enable-elevated-read: true no pedido de pesquisa.

2. Pesquisa de IA do Azure ignora a verificação de acesso baseada em etiquetas por documento e devolve documentos correspondentes, independentemente das permissões EXTRACT do utilizador solicitante em cada etiqueta.

3. Para cada documento da resposta, Pesquisa de IA do Azure emite uma entrada no registo de auditoria Microsoft Purview em nome do inquilino solicitante. Um único pedido de pesquisa que devolve N documentos produz N entradas de auditoria.

4. As entradas de auditoria são carregadas para a Purview de forma assíncrona após a resposta de pesquisa ser devolvida.

Atribuição obrigatória de funções

O utilizador programador que efetua a chamada tem de ter a função de Contribuidor de Dados do Índice de Pesquisa no serviço de pesquisa ou ao nível do índice. O Search Index Data Reader não é suficiente. A leitura elevada falha 403 Forbidden se a função não for atribuída. Para mais informações sobre Pesquisa de IA do Azure funções, veja Liga-te a Pesquisa de IA do Azure usando roles.

Quando o x-ms-enable-elevated-read cabeçalho está definido para true, o x-ms-query-source-authorization cabeçalho não pode ser usado.

Exemplo de leitura com privilégios elevados

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 gestão do Office 365 e inclui os seguintes campos.

Degradação graciosa

Se o Pesquisa de IA do Azure não conseguir aceder ao Microsoft Purview durante o processamento de uma consulta, como durante uma interrupção temporária do Purview, ignora a avaliação de rótulos para esse pedido. O comportamento depende de o pedido incluir ou não um token de identidade de utilizador:

• Pedidos de leitura elevados (x-ms-enable-elevated-read: true): O pedido falha com 5xx. O Pesquisa de IA do Azure não devolve documentos rotulados sem antes poder emitir registos de auditoria.

• Solicitações padrão impostas por etiqueta (com x-ms-query-source-authorization): A solicitação falha com 5xx. O Pesquisa de IA do Azure não devolve resultados parciais ou não filtrados quando não consegue avaliar políticas de etiqueta.

• Chamadas sem x-ms-query-source-authorization emitidas por uma aplicação com, pelo menos, a função Leitor de Dados do Índice de Pesquisa: O pedido é bem-sucedido e devolve apenas documentos que não têm uma etiqueta de confidencialidade. Documentos rotulados são omitidos da resposta.

Esta via degradada destina-se apenas a fluxos de trabalho não expostos ao utilizador que aceitam explicitamente resultados exclusivamente não rotulados. Não dependa dele para experiências de pesquisa do utilizador final.

Para a lista completa de códigos de erro retornados durante a avaliação de etiquetas de sensibilidade ao tempo de consulta, veja Resolução de erros de consulta.

Localizar registos de auditoria de leituras elevadas no Microsoft Purview

O Pesquisa de IA do Azure carrega as entradas de auditoria para o registo de auditoria do Microsoft Purview do tenant que efetua a chamada. Para investigar a elevada atividade de leitura:

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

2. Selecione Audit Search e depois filtre por intervalo de datas, utilizador ou pelo tipo de registo Pesquisa de IA do Azure.

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

Para orientações passo a passo sobre a execução de pesquisas de auditoria, comportamento de retenção e funções obrigatórias no Purview, consulte Pesquisa no registo de auditoria no portal do Microsoft Purview.

Tratamento de etiquetas de sensibilidade no Pesquisa de IA do Azure

Quando o Pesquisa de IA do Azure indexa o conteúdo do documento com etiquetas de sensibilidade provenientes de fontes como SharePoint, Azure Blob e outras, armazena tanto o conteúdo como os metadados das etiquetas. A consulta de pesquisa retorna conteúdo indexado juntamente com o GUID que identifica o rótulo de sensibilidade aplicado ao documento, somente se o utilizador tiver acesso aos dados EXTRACT atribuído pela definição do rótulo de sensibilidade. Este GUID identifica de forma única o rótulo, mas não inclui propriedades legíveis por humanos, como o nome da etiqueta ou permissões associadas.

Note-se que o GUID sozinho é insuficiente para cenários que incluem interface de utilizador porque as etiquetas de sensibilidade frequentemente contêm outros controlos de políticas aplicados por Proteção de Informações do Microsoft Purview, tais como: permissões de impressão ou restrições de captura de ecrã e captura de ecrã. O Pesquisa de IA do Azure não apresenta estas capacidades.

Para mostrar nomes de etiquetas e/ou aplicar restrições específicas da interface, a sua aplicação deve contactar o endpoint Proteção de Informações do Microsoft Purview para obter metadados completos e permissões associadas.

Pode usar o GUID devolvido por Pesquisa de IA do Azure para resolver as propriedades da etiqueta e chamar as APIs de Etiquetas Purview para obter o nome da etiqueta, a descrição e as definições da política.

Resolver erros de consulta

Quando a avaliação de etiquetas de sensibilidade ao tempo da consulta falha, o Pesquisa de IA do Azure devolve 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 falha em vez de expor conteúdos não rotulados ou não autorizados.

400 Pedido Inválido

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

401 Não autorizado

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

502 Bad Gateway

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

Tempo de Expiração do Gateway 504

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

Configuração de teste de ponta a ponta

Para o ajudar a validar a configuração da sua etiqueta de sensibilidade no Pesquisa de IA do Azure, consulte a configuração de referência de ponta a ponta.

Este repositório demonstra como:

• Configurar a sincronização e a aplicação de etiquetas de confidencialidade no Pesquisa de IA do Azure
• Teste de cenários de ingestão e aplicação no momento da consulta para documentos com rótulos de confidencialidade
• Extrai o nome do rótulo e expõe-o como parte das citações utilizadas nas tuas aplicações ou agentes RAG.