Wymuszanie etykiet poufności Microsoft Purview w czasie wykonywania kwerend w usłudze Wyszukiwanie AI platformy Azure (wersja zapoznawcza)

W czasie wykonywania kwerendy usługa Wyszukiwanie AI platformy Azure może wymuszać zasady etykiet poufności (wersja zapoznawcza) zdefiniowane w Microsoft Purview. Te zasady obejmują ocenę praw użytkowania skojarzonych EXTRACT z każdym dokumentem, dzięki czemu użytkownicy mogą pobierać tylko dokumenty, do których mają dostęp.

Ta funkcja rozszerza kontrolę dostępu na poziomie dokumentu, aby dostosować się do wymagań dotyczących ochrony informacji i zgodności zarządzanych w Microsoft Purview.

Po włączeniu indeksowania etykiet wrażliwości z usługi Purview, Wyszukiwanie AI platformy Azure sprawdza metadane etykiet każdego dokumentu podczas przetwarzania zapytania. Stosuje filtry dostępu oparte na zasadach usługi Purview, aby zwracać tylko wyniki, do których użytkownik żądający może uzyskać dostęp.

W tym artykule wyjaśniono, jak działa wymuszanie etykiet poufności podczas zapytania oraz jak tworzyć bezpieczne zapytania wyszukiwania.

Wymagania wstępne

• Wykonaj wszystkie kroki opisane w Użyj indeksatorów Wyszukiwanie AI platformy Azure do pozyskiwania etykiet poufności Microsoft Purview.

• Sprawdź, czy usługa Wyszukiwanie AI platformy Azure ma włączoną tożsamość zarządzaną przypisaną przez system (a nie tożsamość zarządzaną przypisaną przez użytkownika) oraz czy ma przypisane role Content.SuperUser i UnifiedPolicy.Tenant.Read. Wymuszanie czasu zapytania zależy od metadanych etykiety, które indeksator może wyodrębnić tylko wtedy, gdy tożsamość przypisana przez system ma poprawną konfigurację. Zobacz krok 1 w artykule dotyczącym konfiguracji indeksatora.

• Zarówno usługa Wyszukiwanie AI platformy Azure, jak i użytkownik wydający zapytanie muszą znajdować się w tej samej dzierżawie Microsoft Entra.

• REST API w wersji 2025-11-01-preview lub nowszej albo równoważny pakiet SDK w wersji zapoznawczej do wykonywania zapytań względem indeksu. Funkcja odczytu z podwyższonym poziomem uprawnień i rejestrowanie inspekcji w usłudze Purview wymagają wersji 2026-05-01-preview lub nowszej.

• Uwierzytelnianie zapytań przy użyciu Azure kontroli dostępu opartej na rolach (RBAC), a nie kluczy interfejsu API. Po włączeniu etykiet czułości Purview dostęp do klucza API jest ograniczony do pobierania schematu indeksu.

Ograniczenia

• Konta gościa i zapytania między tenantami nie są obsługiwane.

• Autouzupełnianie i sugerowane interfejsy API nie są obsługiwane w przypadku indeksów z obsługą usługi Purview.

• Jeśli ocena etykiety nie powiedzie się, usługa zwraca określony kod błędu HTTP, a nie częściowy lub niefiltrowany zestaw wyników. Aby uzyskać pełną listę kodów błędów i przyczyn, zobacz Rozwiązywanie problemów z błędami zapytań.

• System ocenia etykiety tylko wtedy, gdy istniały w momencie ostatniego uruchomienia indeksatora. Ostatnie zmiany etykiet mogą nie zostać odzwierciedlone do czasu następnego zaplanowanego ponownego indeksu.

Jak działa wymuszanie etykiet poufności w czasie zapytania

Podczas wykonywania zapytań dotyczących indeksu zawierającego etykiety poufności Microsoft Purview Wyszukiwanie AI platformy Azure sprawdza skojarzone zasady usługi Purview przed zwróceniem wyników. W ten sposób zapytanie zwraca tylko dokumenty, do których token użytkownika może uzyskać dostęp.

1. Tożsamość użytkownika i dane wejściowe roli aplikacji

W czasie wykonywania zapytania Wyszukiwanie AI platformy Azure weryfikuje obie te elementy:

• Rola RBAC dla aplikacji wywołującej podana w nagłówku Authorization . Minimalna wymagana rola to Search Index Data Reader. Aby uzyskać więcej informacji, zapoznaj się z przewodnikiem Wyszukiwanie AI platformy Azure RBAC.
• Tożsamość użytkownika za pośrednictwem tokenu podana w nagłówku x-ms-query-source-authorization .

Oba te elementy są wymagane do autoryzowania widoczności opartej na etykietach.

2. Ocena etykiety poufności

Po odebraniu żądania zapytania Wyszukiwanie AI platformy Azure ocenia:

1. Pole sensitivityLabel w każdym indeksowanym dokumencie (pobrano z Microsoft Purview podczas importowania).
2. Aktywne uprawnienia użytkownika w usłudze Purview zdefiniowane przez Microsoft Entra ID i politykę etykiet Purview.

Jeśli użytkownik nie ma autoryzacji dla etykiety poufności dokumentu z uprawnieniami EXTRACT , ten dokument jest wykluczony z wyników zapytania.

3. Bezpieczne filtrowanie wyników

Wyszukiwanie AI platformy Azure stosuje filtr zabezpieczeń po wszystkich filtrach zdefiniowanych przez użytkownika i krokach oceniania.
Dokument jest uwzględniony w końcowym zestawie wyników tylko wtedy, gdy:

• Aplikacja wywołująca ma prawidłowe przypisanie roli (za pośrednictwem kontroli dostępu opartej na rolach) i
• Token tożsamości użytkownika reprezentowany przez program x-ms-query-source-authorization jest prawidłowy i ma pozwolenie na wyświetlanie zawartości z etykietą poufności dokumentu.

Jeśli którykolwiek z warunków zakończy się niepowodzeniem, dokument zostanie pominięty z wyników.

Uzyskiwanie tokenu dostępu użytkownika

Aby wykonać zapytanie Wyszukiwanie AI platformy Azure przy użyciu kontekstu użytkownika, musisz uzyskać token dostępu reprezentujący zalogowanego użytkownika. Używane podejście zależy od tego, czy testujesz lokalnie przy użyciu własnego tokenu, czy masz dostęp do dokumentu źródłowego, czy też implementujesz przepływ aplikacji, który wymaga przekazania tokenu użytkownika końcowego.

W przypadku scenariuszy testowania

Na potrzeby testowania lokalnego można pobrać token dostępu użytkownika przy użyciu Azure CLI:

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

To podejście korzysta z bieżącej sesji logowania Azure CLI, więc można użyć kontekstu w dokumentach, do których masz uprawnienia EXTRACT przypisane za pośrednictwem etykiet poufności. Ta metoda jest przeznaczona tylko dla scenariuszy programowania i walidacji.

Pozyskiwanie tokenów dla scenariuszy OBO

Aplikacje obsługujące przepływ OBO (on-behalf-of) muszą pozyskiwać tokeny za pośrednictwem usługi Microsoft Entra ID przy użyciu obsługiwanej biblioteki uwierzytelniania, takiej jak Microsoft Authentication Library (MSAL).

W scenariuszach OBO zażądaj tokenu dla podrzędnego interfejsu API wywoływanego przez aplikację. Na przykład podczas wywoływania usługi Wyszukiwanie AI platformy Azure identyfikatorem URI zasobu jest https://search.azure.com/.default.

Zakres .default żąda dostępu do wszystkich uprawnień delegowanych, na które wcześniej wyrażono zgodę dla aplikacji dla określonego zasobu.

Uprawnienia etykiet poufności, w tym EXTRACT, nie są reprezentowane jako zakresy OAuth. Usługa docelowa, taka jak Wyszukiwanie AI platformy Azure, ocenia te uprawnienia w czasie działania na podstawie tożsamości użytkownika zawartej w tokenie oraz zastosowanej polityki etykiet poufności.

Przykład zapytania

Oto przykład żądania, w którym jest stosowane wymuszanie etykiet poufności Microsoft Purview.

Przekaż token aplikacji jako token elementu nośnego w nagłówku Authorization . Przekaż token użytkownika jako wartość nieprzetworzonego tokenu w nagłówku x-ms-query-source-authorization bez prefiksu 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"
}

Odczyt z rozszerzonymi uprawnieniami do dochodzeń administracyjnych (wersja zapoznawcza)

Funkcja odczytu z podwyższonym poziomem uprawnień umożliwia autoryzowanemu deweloperowi zwracanie dokumentów opatrzonych etykietami, których użytkownik wywołujący zwykle nie może zobaczyć, a jednocześnie dla każdego dokumentu zwróconego przez żądanie generuje wpis dziennika inspekcji Microsoft Purview. Służy do przeprowadzania przeglądów zgodności, zbierania elektronicznych materiałów dowodowych, reagowania na zdarzenia i innych badań administracyjnych, w których wymagany jest inspekcja rekordu dostępu.

Odczyt z podwyższonymi uprawnieniami jest dostępny w indeksach z włączoną usługą Purview w interfejsie API REST w wersji 2026-05-01-preview i nowszych.

Jak działa odczyt z podwyższonymi uprawnieniami

1. Aplikacja wywołująca ustawia nagłówek x-ms-enable-elevated-read: true w żądaniu wyszukiwania.

2. Wyszukiwanie AI platformy Azure pomija sprawdzanie dostępu dla każdego dokumentu na podstawie etykiet i zwraca pasujące dokumenty niezależnie od EXTRACT uprawnień użytkownika wysyłającego żądanie do każdej etykiety.

3. Dla każdego dokumentu w odpowiedzi usługa Wyszukiwanie AI platformy Azure generuje jeden wpis w dzienniku inspekcji usługi Microsoft Purview w imieniu dzierżawy wysyłającej żądanie. Pojedyncze żądanie wyszukiwania, które zwraca N dokumentów, generuje N wpisów audytu.

4. Wpisy audytu są przesyłane do Purview asynchronicznie po zwróceniu odpowiedzi na wyszukiwanie.

Wymagane przypisanie roli

Użytkownik-deweloper wywołujący musi mieć przypisaną rolę Współautor danych indeksu wyszukiwania na poziomie usługi wyszukiwania lub indeksu. Czytnik danych indeksu wyszukiwania nie jest wystarczający. Odczyt z podwyższonym poziomem uprawnień kończy się niepowodzeniem, 403 Forbidden jeśli rola nie jest przypisana. Aby uzyskać więcej informacji na temat ról Wyszukiwanie AI platformy Azure, zobacz Połączenie z Wyszukiwanie AI platformy Azure przy użyciu ról.

Gdy nagłówek x-ms-enable-elevated-read jest ustawiony na true, nie można używać nagłówka x-ms-query-source-authorization.

Przykład odczytu z podwyższonymi uprawnieniami

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

Pola inspekcji wysyłane do Microsoft Purview

Każdy wpis audytu jest zgodny ze schematem interfejsu API aktywności zarządzania pakietu Office 365 i zawiera następujące pola.

Łagodna degradacja

Jeśli usługa Wyszukiwanie AI platformy Azure nie może połączyć się z usługą Microsoft Purview podczas przetwarzania zapytania, na przykład podczas przejściowej awarii usługi Purview, pomija ocenę etykiet w przypadku tego żądania. Zachowanie zależy od tego, czy żądanie zawiera token tożsamości użytkownika:

• Żądania odczytu z podwyższonymi uprawnieniami (x-ms-enable-elevated-read: true): Żądanie kończy się niepowodzeniem z komunikatem 5xx. Wyszukiwanie AI platformy Azure nie zwraca dokumentów oznaczonych etykietami bez uprzedniego emitowania dzienników inspekcji.

• Standardowe żądania wymuszane etykietą (z x-ms-query-source-authorization): Żądanie kończy się niepowodzeniem z komunikatem 5xx. Wyszukiwanie AI platformy Azure nie zwraca częściowych ani niefiltrowanych wyników, gdy nie może ocenić zasad etykiet.

• Wywołania bez x-ms-query-source-authorization wykonywane przez aplikację mającą co najmniej rolę Czytelnik danych indeksu wyszukiwania: żądanie kończy się powodzeniem i zwraca tylko dokumenty, które nie mają etykiety poufności. Dokumenty z etykietami są pomijane z odpowiedzi.

Ta ścieżka awaryjna jest przeznaczona wyłącznie do przepływów pracy niewidocznych dla użytkownika, które wyraźnie akceptują wyłącznie wyniki bez etykiet. Nie należy na nim polegać przy wyszukiwaniu dla użytkowników końcowych.

Aby uzyskać pełną listę kodów błędów zwracanych podczas wykonywania zapytania przy ocenie etykiet poufności, zobacz Rozwiązywanie problemów z błędami zapytań.

Znajdź uprzywilejowane dzienniki inspekcji odczytu w Microsoft Purview

Wyszukiwanie AI platformy Azure przesyła wpisy audytu do dziennika audytu Microsoft Purview dzierżawy wywołującej. Aby zbadać zwiększoną aktywność odczytu:

1. W portal Microsoft Purview wybierz pozycję Solutions>Audit.

2. Wybierz Audit Search, a następnie filtruj według zakresu dat, użytkownika lub typu rekordu Wyszukiwanie AI platformy Azure.

3. Otwórz wpis, aby wyświetlić standardowe pola schematu i pola niestandardowe Wyszukiwanie AI platformy Azure, w tym SensitivityLabelName, DocumentDataSourceType i DocumentDataSourceId.

Aby uzyskać wskazówki krok po kroku dotyczące uruchamiania wyszukiwania w dzienniku inspekcji, działania zasad przechowywania i wymaganych ról w usłudze Microsoft Purview, zobacz Przeszukiwanie dziennika inspekcji w portalu Microsoft Purview.

Obsługa etykiet poufności w Wyszukiwanie AI platformy Azure

Gdy Wyszukiwanie AI platformy Azure indeksuje zawartość dokumentu z etykietami poufności z takich źródeł jak SharePoint, Azure Blob Storage i inne, przechowuje zarówno treść, jak i metadane etykiet. Zapytanie wyszukiwania zwraca indeksowaną zawartość wraz z identyfikatorem GUID, który identyfikuje etykietę poufności zastosowaną do dokumentu, tylko wtedy, gdy użytkownik ma dostęp do danych EXTRACT dla tego dokumentu przypisanego za pośrednictwem definicji etykiety poufności. Ten identyfikator GUID jednoznacznie identyfikuje etykietę, ale nie zawiera właściwości czytelnych dla człowieka, takich jak nazwa etykiety lub skojarzone uprawnienia.

Należy pamiętać, że sam identyfikator GUID jest niewystarczający w scenariuszach obejmujących interfejs użytkownika, ponieważ etykiety poufności często zawierają inne kontrole zasad wymuszane przez Microsoft Purview Information Protection, takie jak uprawnienia do drukowania lub ograniczenia dotyczące zrzutów ekranu i przechwytywania ekranu. Wyszukiwanie AI platformy Azure nie pokazuje tych możliwości.

Aby wyświetlić nazwy etykiet i/lub wymusić ograniczenia specyficzne dla interfejsu użytkownika, aplikacja musi wywołać punkt końcowy Microsoft Purview Information Protection w celu pobrania metadanych pełnej etykiety i skojarzonych uprawnień.

Identyfikator GUID zwrócony przez Wyszukiwanie AI platformy Azure umożliwia rozpoznawanie właściwości etykiety i wywoływanie interfejsu API etykiet Purview Labels w celu pobrania nazwy etykiety, opisu i ustawień zasad.

Diagnostyka błędów zapytania

Gdy ocena etykiety poufności podczas wykonywania zapytania kończy się niepowodzeniem, usługa Wyszukiwanie AI platformy Azure zwraca określony kod błędu HTTP, który identyfikuje przyczynę. Usługa nigdy nie zwraca częściowego lub niefiltrowanego zestawu wyników. Jeśli nie można ocenić zasad etykiet, zapytanie zakończy się niepowodzeniem, a nie uwidacznia zawartości nieoznaczonej lub nieautoryzowanej.

400 Nieprawidłowe żądanie

Błąd 400 wskazuje problem z konfiguracją indeksu lub nagłówkami żądań. Napraw konfigurację przed ponowną próbą.

401 Brak autoryzacji

Błąd 401 wskazuje problem z tokenem autoryzacji lub uprawnieniami usługi Purview aplikacji.

502 — zła brama

Błąd 502 wskazuje błąd łączności między Wyszukiwanie AI platformy Azure a Microsoft Purview. Te błędy są zwykle przejściowe.

504 Przekroczenie limitu czasu gateway

Błąd 504 wskazuje, że Microsoft Purview nie odpowiedziała w dozwolonym czasie.

Kompleksowa konfiguracja testowania

Aby ułatwić zweryfikowanie konfiguracji etykiety poufności w Wyszukiwanie AI platformy Azure, zobacz kompleksową konfigurację referencyjną.

To repozytorium pokazuje, jak:

• Konfigurowanie synchronizacji i honorowania etykiet poufności w Wyszukiwanie AI platformy Azure
• Testowanie pozyskiwania danych i scenariuszy wymuszania czasu zapytań dla dokumentów z etykietami poufności
• Wyodrębnij nazwę etykiety i uwidocznij ją jako część cytatów używanych w aplikacjach lub agentach RAG.