Tillämpning vid frågetillfället av Microsoft Purview-känslighetsetiketter i Azure AI-sökning (förhandsversion)

Vid frågetillfället kan Azure AI-sökning framtvinga principer för känslighetsetiketter (förhandsversion) som definierats i Microsoft Purview. Dessa principer omfattar utvärdering av användningsrättigheterEXTRACT som är associerade med varje dokument, vilket säkerställer att användarna bara kan hämta dokument som de har behörighet att komma åt.

Den här funktionen utökar åtkomstkontrollen på dokumentnivå så att den överensstämmer med organisationens informationsskydd och efterlevnadskrav som hanteras i Microsoft Purview.

När Purview-indexering av känslighetsetiketter är aktiverat kontrollerar Azure AI-sökning varje dokument etikettmetadata under frågetiden. Den tillämpar åtkomstfilter baserat på Purview-principer för att endast returnera resultat som den begärande användaren har åtkomst till.

Den här artikeln beskriver hur tillämpning av känslighetsetiketter för frågetid fungerar och hur du utfärdar säkra sökfrågor.

Förutsättningar

• Slutför alla steg i Använd Azure AI-sökning indexerare för att mata in Microsoft Purview känslighetsetiketter.

• Kontrollera att Azure AI-sökning-tjänsten har sin systemtilldelade hanterade identitet (inte en användartilldelad hanterad identitet) aktiverad och att den har rolltilldelningarna Content.SuperUser och UnifiedPolicy.Tenant.Read. Frågetidsframtvingande beror på etikettmetadata som indexeraren endast kan extrahera när den systemtilldelade identiteten har rätt konfiguration. Se steg 1 i artikeln om indexerarens konfiguration.

• Både Azure AI-sökning-tjänsten och användaren som utfärdar frågan måste finnas i samma Microsoft Entra klientorganisation.

• REST API version 2025-11-01-preview eller senare, eller ett motsvarande SDK-paket för förhandsversion, för att köra frågor mot indexet. Förhöjd läsfunktion och Purview-granskningsloggning kräver 2026-05-01-preview eller senare.

• Autentisera frågor med hjälp av Azure rollbaserad åtkomstkontroll (RBAC), inte API-nycklar. När Purview-känslighetsetiketter är aktiverade begränsas API-nyckelåtkomsten till hämtning av indexschema.

Begränsningar

• Gästkonton och klientöverskridande frågor stöds inte.

• Komplettera automatiskt och föreslå API:er stöds inte för Purview-aktiverade index.

• Om etikettutvärderingen misslyckas returnerar tjänsten en specifik HTTP-felkod i stället för en partiell eller ofiltrerad resultatuppsättning. En fullständig lista över felkoder och orsaker finns i Felsöka frågefel.

• Systemet utvärderar endast etiketter som de fanns vid tidpunkten för den senaste indexeringskörningen. De senaste etikettändringarna kanske inte återspeglas förrän nästa schemalagda omindex.

Så här fungerar tillämpning av känslighetsetiketter för frågetid

När du kör frågor mot ett index som innehåller Microsoft Purview känslighetsetiketter kontrollerar Azure AI-sökning de associerade Purview-principerna innan du returnerar resultat. På så sätt returnerar frågan endast dokument som användartoken har åtkomst till.

1. Indata för användaridentitet och programroll

Vid frågetillfället verifierar Azure AI-sökning båda:

• Det anropande programmets RBAC-roll, som anges i Authorization rubriken. Den lägsta rollen som krävs är Search Index Data Reader. Mer information finns i rbac-guiden Azure AI-sökning.
• Användaridentiteten via token, som anges i x-ms-query-source-authorization rubriken.

Båda krävs för att auktorisera etikettbaserad synlighet.

2. Utvärdering av känslighetsetiketter

När en frågebegäran tas emot utvärderas Azure AI-sökning:

1. Fältet sensitivityLabel i varje indexerat dokument (extraherat från Microsoft Purview under inmatning).
2. Användarens gällande Purview-behörigheter enligt definitionen i Microsoft Entra ID och Purview-etikettpolicy.

Om användaren inte har behörighet för ett dokuments känslighetsetikett med EXTRACT behörigheter undantas dokumentet från frågeresultatet.

3. Säker resultatfiltrering

Azure AI-sökning tillämpar säkerhetsfiltret efter alla användardefinierade filter och bedömningssteg.
Ett dokument ingår endast i den slutliga resultatuppsättningen om:

• Det anropande programmet har en giltig rolltilldelning (via RBAC) och
• Den användaridentitetstoken som representeras av x-ms-query-source-authorization är giltig och tillåten att visa innehåll med dokumentets känslighetsetikett.

Om något av villkoren misslyckas utelämnas dokumentet från resultaten.

Hämta en användaråtkomsttoken

Om du vill fråga Azure AI-sökning med hjälp av användarkontext måste du skaffa en åtkomsttoken som representerar den inloggade användaren. Vilken metod du använder beror på om du testar lokalt med din egen token, om du har åtkomst till källdokumentet eller om du implementerar det programflöde som kräver att slutanvändarens token skickas.

För testscenarier

För lokal testning kan du hämta en användaråtkomsttoken med hjälp av Azure CLI:

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

Den här metoden använder din aktuella Azure CLI inloggningssession, så att du kan använda kontexten över dokument som du har EXTRACT behörigheter tilldelade via känslighetsetiketter. Den här metoden är endast avsedd för utvecklings- och valideringsscenarier.

Tokenhämtning för OBO-scenarier

Program som implementerar OBO-flödet (on-behalf-of) måste hämta token via Microsoft Entra ID med hjälp av ett autentiseringsbibliotek som stöds, till exempel Microsofts autentiseringsbibliotek (MSAL).

I OBO-scenarier begär du token för det underordnade API som programmet anropar. När du till exempel anropar Azure AI-sökning är resurs-URI:n https://search.azure.com/.default.

Omfånget .default begär alla delegerade behörigheter som programmet fördefinierat för den angivna resursen.

Behörigheter för känslighetsetiketter, inklusive EXTRACT, representeras inte som OAuth-omfång. Den underliggande tjänsten, till exempel Azure AI-sökning, utvärderar dessa behörigheter vid körning utifrån användaridentiteten i tokenen och den tillämpade principen för känslighetsetiketter.

Frågeexempel

Här är ett exempel på en frågeförfrågan som använder Microsoft Purviews framtvingande av känslighetsetiketter.

Skicka applikationstokenen som en bearer-token i Authorization-headern. Skicka användartoken som det råa tokenvärdet i x-ms-query-source-authorization rubriken, utan prefixet 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"
}

Utökad läsåtkomst för administrativa utredningar (förhandsversion)

Med utökad läsåtkomst kan en behörig utvecklare returnera etiketterade dokument som den anropande användaren normalt inte kan se, samtidigt som en granskningsloggpost i Microsoft Purview genereras för varje dokument som begäran returnerar. Använd den för efterlevnadsgranskningar, eDiscovery, incidenthantering och andra administrativa undersökningar där en granskningsbar åtkomstpost krävs.

Förhöjd läsning är tillgängligt för Purview-aktiverade index i REST API version 2026-05-01-preview och senare.

Så här fungerar upphöjd läsning

1. Det anropande programmet anger headern x-ms-enable-elevated-read: true i sökbegäran.

2. Azure AI-sökning hoppar över den etikettbaserade åtkomstkontrollen per dokument och returnerar matchande dokument, oavsett den begärande användarens EXTRACT behörigheter på varje etikett.

3. För varje dokument i svaret genererar Azure AI-sökning en post i Microsoft Purview-granskningsloggen på uppdrag av den begärande klientorganisationen. En enda sökförfrågan som returnerar N dokument genererar N granskningsposter.

4. Granskningsposter laddas upp till Purview asynkront när söksvaret returneras.

Obligatorisk rolltilldelning

Den anropande utvecklaranvändaren måste ha rollen Search Index Data Contributor i söktjänsten eller indexomfånget. Dataläsare för sökindex räcker inte. Förhöjd läsning misslyckas med 403 Forbidden om rollen inte har tilldelats. Mer information om Azure AI-sökning roller finns i Anslut till Azure AI-sökning med hjälp av roller.

När x-ms-enable-elevated-read-rubriken är inställd på true får x-ms-query-source-authorization-rubriken inte användas.

Exempel på utökad läsåtkomst

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"
}

Granskningsfält som skickas till Microsoft Purview

Varje granskningspost följer schemat Office 365 management activity API och innehåller följande fält.

Gradvis nedtrappning

Om Azure AI-sökning inte kan nå Microsoft Purview när en fråga bearbetas, till exempel under ett tillfälligt Purview-avbrott, hoppar den över etikettutvärderingen för den begäran. Beteendet beror på om begäran innehåller en användaridentitetstoken:

• Utökade läsbegäranden (x-ms-enable-elevated-read: true): Begäran misslyckas med 5xx. Azure AI-sökning returnerar inte etiketterade dokument utan att först kunna generera granskningsloggar.

• Standardbegäranden som framtvingas av etiketter (med x-ms-query-source-authorization): Begäran misslyckas med 5xx. Azure AI-sökning returnerar inte partiella eller ofiltrerade resultat när det inte kan utvärdera etikettprinciper.

• Anrop utan x-ms-query-source-authorization som görs av ett program med minst rollen Dataläsare för sökindex: Begäran lyckas och returnerar endast dokument som inte har en känslighetsetikett. Etiketterade dokument utelämnas från svaret.

Den här degraderade sökvägen är endast avsedd för arbetsflöden som inte är användarriktade och som uttryckligen accepterar resultat utan etiketter. Förlita dig inte på det för slutanvändarnas sökupplevelser.

Den fullständiga listan över felkoder som returnerades under utvärdering av känslighetsetiketter för frågetid finns i Felsöka frågefel.

Hitta utökade läsgranskningsloggar i Microsoft Purview

Azure AI-sökning överför granskningsposter till den anropande klientens Microsoft Purview granskningslogg. Så här undersöker du förhöjd läsaktivitet:

1. I Microsoft Purview-portal väljer du Solutions>Audit.

2. Välj Audit Search och filtrera sedan efter datumintervall, användare eller Azure AI-sökning posttyp.

3. Öppna en post för att visa standardschemafälten och de Azure AI-sökning anpassade fälten, inklusive SensitivityLabelName, DocumentDataSourceType och DocumentDataSourceId.

Stegvisa anvisningar om hur du kör granskningssökningar, kvarhållningsbeteende och nödvändiga Purview-roller finns i Sök granskningsloggen i Microsoft Purview-portal.

Hantering av känslighetsetiketter i Azure AI-sökning

När Azure AI-sökning indexerar dokumentinnehåll med känslighetsetiketter från källor som SharePoint, Azure Blob och andra lagras både innehållet och etikettmetadata. Sökfrågan returnerar indexerat innehåll tillsammans med det GUID som identifierar känslighetsetikett som tillämpas på dokumentet, endast om användaren har dataåtkomst EXTRACT för dokumentet som tilldelats genom definitionen av känslighetsetiketten. Detta GUID identifierar etiketten unikt men innehåller inte läsbara egenskaper som etikettnamn eller associerade behörigheter.

Observera att enbart GUID är otillräckligt för scenarier som innehåller användargränssnitt eftersom känslighetsetiketter ofta har andra principkontroller som tillämpas av Microsoft Purview Information Protection, till exempel: utskriftsbehörigheter eller skärmbilds- och skärmdumpsbegränsningar. Azure AI-sökning visar inte dessa funktioner.

Om du vill visa etikettnamn och/eller tillämpa användargränssnittsspecifika begränsningar måste ditt program anropa Microsoft Purview Information Protection slutpunkten för att hämta fullständiga etikettmetadata och associerade behörigheter.

Du kan använda GUID som returneras av Azure AI-sökning för att matcha etikettegenskaperna och anropa API:erna Purview Labels för att hämta etikettnamn, beskrivning och principinställningar.

Felsök frågefel

När utvärdering av känslighetsetiketter för frågetid misslyckas returnerar Azure AI-sökning en specifik HTTP-felkod som identifierar orsaken. Tjänsten returnerar aldrig en partiell eller ofiltrerad resultatuppsättning. Om etikettprinciper inte kan utvärderas misslyckas frågan i stället för att exponera omärkt eller obehörigt innehåll.

400 – Felaktig begäran

Ett 400-fel anger ett problem med indexkonfigurationen eller begärandehuvudena. Åtgärda konfigurationen innan du försöker igen.

401 Inte auktoriserad

Ett 401-fel anger ett problem med auktoriseringstoken eller programmets Purview-behörigheter.

502 Felaktig gateway

Ett 502-fel anger ett anslutningsfel mellan Azure AI-sökning och Microsoft Purview. Dessa fel är vanligtvis tillfälliga.

Tidsgräns för 504 Gateway

Ett 504-fel anger att Microsoft Purview inte svarade inom den tillåtna tiden.

Testkonfiguration från slutpunkt till slutpunkt

Information om hur du verifierar konfigurationen av känslighetsetiketter i Azure AI-sökning finns i referenskonfigurationen från slutpunkt till slutpunkt.

Den här lagringsplatsen visar hur du:

• Konfigurera synkronisering och hantering av känslighetsetiketter i Azure AI-sökning
• Testa inmatnings- och frågetidstillämpningsscenarier för dokument med känslighetsetiketter
• Extrahera etikettnamnet och exponera det som en del av citaten som används i dina RAG-program eller agenter.