Penegakan label sensitivitas Microsoft Purview saat kueri di Pencarian Azure AI (pratinjau)

Pada saat kueri, Pencarian Azure AI dapat memberlakukan kebijakan label sensitivitas (pratinjau) yang ditentukan di Microsoft Purview. Kebijakan ini mencakup evaluasi EXTRACT hak penggunaan yang terkait dengan setiap dokumen, memastikan pengguna hanya dapat mengambil dokumen yang diizinkan untuk diakses.

Kemampuan ini memperluas kontrol akses tingkat dokumen agar selaras dengan persyaratan perlindungan dan kepatuhan informasi organisasi Anda yang dikelola dalam Microsoft Purview.

Saat pengindeksan label sensitivitas Purview diaktifkan, Pencarian Azure AI memeriksa metadata label setiap dokumen selama waktu kueri. Ini menerapkan filter akses berdasarkan kebijakan Purview untuk mengembalikan hanya hasil yang diizinkan untuk diakses oleh pengguna yang meminta.

Artikel ini menjelaskan cara kerja penegakan label sensitivitas waktu kueri dan cara mengeluarkan kueri pencarian yang aman.

Prasyarat

• Selesaikan semua langkah dalam Gunakan pengindeks Pencarian Azure AI untuk menyerap label sensitivitas Microsoft Purview.

• Verifikasi bahwa layanan Pencarian Azure AI telah mengaktifkan identitas terkelola yang ditetapkan sistem (bukan identitas terkelola yang ditetapkan pengguna) dan memiliki penetapan peran Content.SuperUser dan UnifiedPolicy.Tenant.Read. Penegakan pada saat kueri bergantung pada metadata label yang hanya dapat diekstrak oleh pengindeks ketika identitas yang ditetapkan oleh sistem memiliki konfigurasi yang benar. Lihat Langkah 1 di artikel penyiapan pengindeks.

• Baik layanan Pencarian Azure AI maupun pengguna yang mengajukan kueri harus berada di dalam penyewa Microsoft Entra yang sama.

• REST API versi 2025-11-01-preview atau yang lebih baru, atau paket SDK pratinjau yang setara, untuk mengkueri indeks. Kemampuan baca dengan hak istimewa dan pencatatan audit Purview memerlukan 2026-05-01-preview atau versi yang lebih baru.

• Autentikasi kueri menggunakan Azure kontrol akses berbasis peran (RBAC), bukan kunci API. Saat label sensitivitas Purview diaktifkan, akses kunci API dibatasi untuk pengambilan skema indeks.

Keterbatasan

• Akun tamu dan kueri lintas penyewa tidak didukung.

• Autocomplete dan Suggest API tidak didukung untuk indeks yang diaktifkan dengan Purview.

• Jika evaluasi label gagal, layanan mengembalikan kode kesalahan HTTP tertentu daripada kumpulan hasil parsial atau tidak difilter. Untuk daftar lengkap kode kesalahan dan penyebabnya, lihat Memecahkan masalah kesalahan kueri.

• Sistem mengevaluasi label hanya seperti yang ada pada saat pengindeks terakhir dijalankan. Perubahan label terbaru mungkin tidak tercermin hingga indeks ulang terjadwal berikutnya.

Cara kerja penegakan label sensitivitas waktu kueri

Saat Anda mengkueri indeks yang menyertakan label sensitivitas Microsoft Purview, Pencarian Azure AI memeriksa kebijakan Purview terkait sebelum mengembalikan hasil. Dengan cara ini, kueri hanya mengembalikan dokumen yang diizinkan untuk diakses oleh token pengguna.

1. Identitas pengguna dan input peran aplikasi

Pada waktu kueri, Pencarian Azure AI memvalidasi keduanya:

• Peran RBAC dari aplikasi yang melakukan panggilan, disediakan di tajuk Authorization. Peran minimum yang diperlukan adalah Search Index Data Reader. Untuk detail selengkapnya, tinjau panduan RBAC Pencarian Azure AI.
• Identitas pengguna melalui token, disediakan di x-ms-query-source-authorization header.

Keduanya diperlukan untuk mengotorisasi visibilitas berbasis label.

2. Evaluasi label sensitivitas

Saat permintaan kueri diterima, Pencarian Azure AI mengevaluasi:

1. Bidang sensitivityLabel di setiap dokumen terindeks (diekstrak dari Microsoft Purview selama pengambilan data).
2. Izin Purview pengguna yang efektif, seperti yang didefinisikan oleh kebijakan label Microsoft Entra ID dan Purview.

Jika pengguna tidak berwenang untuk label sensitivitas dokumen dengan EXTRACT izin, dokumen tersebut dikecualikan dari hasil kueri.

3. Pemfilteran hasil yang aman

Pencarian Azure AI menerapkan filter keamanan setelah semua filter dan langkah penilaian yang ditentukan pengguna.
Dokumen disertakan dalam tataan hasil akhir hanya jika:

• Aplikasi panggilan memiliki penetapan peran yang valid (melalui RBAC), dan
• Token identitas pengguna yang diwakili oleh x-ms-query-source-authorization valid dan diizinkan untuk melihat konten dengan label sensitivitas dokumen.

Jika salah satu kondisi gagal, dokumen dihilangkan dari hasil.

Memperoleh token akses pengguna

Untuk mengkueri Pencarian Azure AI menggunakan konteks pengguna, Anda harus memperoleh token akses yang mewakili pengguna yang masuk. Pendekatan yang Anda gunakan tergantung pada apakah Anda menguji secara lokal dengan token Anda sendiri, jika Anda memiliki akses ke dokumen sumber, atau menerapkan alur aplikasi yang memerlukan melewati token pengguna akhir.

Untuk skenario pengujian

Untuk pengujian lokal, Anda dapat mengambil token akses pengguna menggunakan Azure CLI:

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

Pendekatan ini menggunakan sesi masuk Azure CLI Anda saat ini, sehingga Anda dapat menggunakan konteks dalam dokumen-dokumen di mana Anda memiliki izin EXTRACT yang ditetapkan melalui label sensitivitas. Metode ini hanya ditujukan untuk skenario pengembangan dan validasi.

Akuisisi token untuk skenario OBO

Aplikasi yang menerapkan alur on-behalf-of (OBO) harus memperoleh token melalui Microsoft Entra ID dengan menggunakan pustaka autentikasi yang didukung, seperti Pustaka Autentikasi Microsoft (MSAL).

Dalam skenario OBO, minta token untuk API hilir yang dipanggil aplikasi. Misalnya, saat memanggil Pencarian Azure AI, URI sumber daya https://search.azure.com/.default.

Cakupan .default meminta semua izin yang didelegasikan yang telah diberi persetujuan sebelumnya oleh aplikasi untuk sumber daya yang ditentukan.

Izin label sensitivitas, termasuk EXTRACT, tidak diwakili sebagai ruang lingkup OAuth. Layanan hilir, seperti Pencarian Azure AI, mengevaluasi izin ini saat runtime berdasarkan identitas pengguna dalam token dan kebijakan label sensitivitas yang diterapkan.

Contoh kueri

Berikut adalah contoh permintaan kueri yang menggunakan penerapan label sensitivitas Microsoft Purview.

Berikan token aplikasi sebagai token pembawa di Authorization header. Kirimkan token pengguna sebagai nilai token mentah dalam header x-ms-query-source-authorization, tanpa awalan 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"
}

Akses baca tingkat lanjut untuk investigasi administratif (pratinjau)

Pembacaan dengan hak akses istimewa memungkinkan pengembang yang berwenang mengembalikan dokumen berlabel yang biasanya tidak dapat dilihat oleh pengguna pemanggil, sekaligus menghasilkan entri log audit Microsoft Purview untuk setiap dokumen yang dikembalikan oleh permintaan tersebut. Gunakan untuk tinjauan kepatuhan, eDiscovery, respons insiden, dan investigasi administratif lainnya di mana catatan akses yang dapat diaudit diperlukan.

Pembacaan yang ditingkatkan tersedia pada indeks yang diaktifkan Purview di REST API versi 2026-05-01-preview dan yang lebih baru.

Cara kerja pembacaan tingkat lanjut

1. Aplikasi panggilan mengatur x-ms-enable-elevated-read: true header pada permintaan pencarian.

2. Pencarian Azure AI melewati pemeriksaan akses berbasis label per dokumen dan mengembalikan dokumen yang cocok, terlepas dari izin EXTRACT pengguna yang diminta pada setiap label.

3. Untuk setiap dokumen dalam respons, Pencarian Azure AI memancarkan satu entri ke log audit Microsoft Purview atas nama penyewa yang meminta. Satu permintaan pencarian yang mengembalikan dokumen N menghasilkan entri audit N .

4. Entri audit diunggah ke Purview secara asinkron setelah respons pencarian dikembalikan.

Penugasan peran yang diperlukan

Pengguna pengembang panggilan harus memegang peran Kontributor Data Indeks Pencarian pada layanan pencarian atau cakupan indeks. Pembaca Data Indeks Pencarian tidak cukup. Pembacaan yang ditingkatkan gagal jika 403 Forbidden peran tidak ditetapkan. Untuk informasi selengkapnya tentang peran Pencarian Azure AI, lihat Hubungkan ke Pencarian Azure AI menggunakan peran.

Ketika header x-ms-enable-elevated-read disetel ke true, header x-ms-query-source-authorization tidak boleh digunakan.

Contoh baca yang ditingkatkan

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

Bidang audit yang dikirim ke Microsoft Purview

Setiap entri audit mengikuti skema API aktivitas manajemen Office 365 dan mencakup bidang-bidang berikut.

Degradasi yang anggun

Jika Pencarian Azure AI tidak dapat menghubungi Microsoft Purview saat memproses kueri, misalnya selama gangguan Purview yang bersifat sementara, Pencarian Azure AI akan melewati evaluasi label untuk permintaan tersebut. Perilaku tergantung pada apakah permintaan menyertakan token identitas pengguna:

• Permintaan baca yang ditingkatkan (x-ms-enable-elevated-read: true): Permintaan gagal dengan 5xx. Pencarian Azure AI tidak mengembalikan dokumen berlabel sebelum dapat menghasilkan log audit.

• Permintaan standar yang dipaksakan oleh label (dengan x-ms-query-source-authorization): Permintaan gagal dengan 5xx. Pencarian Azure AI tidak mengembalikan hasil parsial atau tidak difilter saat tidak dapat mengevaluasi kebijakan label.

• Panggilan tanpa x-ms-query-source-authorization dikeluarkan oleh aplikasi dengan setidaknya peran Pembaca Data Indeks Pencarian : Permintaan berhasil dan hanya mengembalikan dokumen yang tidak memiliki label sensitivitas. Dokumen berlabel dihilangkan dari respons.

Jalur yang terdegradasi ini hanya ditujukan untuk alur kerja yang tidak menghadap pengguna yang secara eksplisit menerima hasil khusus yang tidak berlabel. Jangan mengandalkannya untuk pengalaman pencarian pengguna akhir.

Untuk daftar lengkap kode kesalahan yang dikembalikan selama evaluasi label sensitivitas waktu kueri, lihat Memecahkan masalah kesalahan kueri.

Temukan log audit pembacaan tingkat lanjut di Microsoft Purview

Pencarian Azure AI mengunggah entri audit ke log audit Microsoft Purview milik tenant pemanggil. Untuk menyelidiki aktivitas pembacaan yang tinggi:

1. Di portal Microsoft Purview, pilih Solutions>Audit.

2. Pilih Pencarian Audit, lalu filter berdasarkan rentang tanggal, pengguna, atau jenis rekaman Pencarian Azure AI.

3. Buka entri untuk melihat bidang skema standar dan bidang kustom Pencarian Azure AI, termasuk SensitivityLabelName, DocumentDataSourceType, dan DocumentDataSourceId.

Untuk panduan langkah demi langkah tentang menjalankan pencarian audit, perilaku retensi, dan peran Purview yang diperlukan, lihat Search log audit di portal Microsoft Purview.

Penanganan Label Sensitivitas dalam Pencarian Azure AI

Saat Pencarian Azure AI mengindeks konten dokumen dengan label sensitivitas dari sumber seperti SharePoint, Azure Blob, dan lainnya, konten dan metadata label disimpan. Kueri pencarian mengembalikan konten terindeks bersama dengan GUID yang mengidentifikasi label sensitivitas yang diterapkan ke dokumen, hanya jika pengguna memiliki akses data EXTRACT untuk dokumen tersebut yang ditetapkan melalui definisi label sensitivitas. GUID ini secara unik mengidentifikasi label tetapi tidak menyertakan properti yang dapat dibaca manusia seperti nama label atau izin terkait.

Perhatikan bahwa GUID saja tidak mencukupi untuk skenario yang mencakup antarmuka pengguna karena label sensitivitas sering membawa kontrol kebijakan lain yang diberlakukan oleh Perlindungan Informasi Microsoft Purview, seperti: izin cetak atau cuplikan layar dan pembatasan tangkapan layar. Pencarian Azure AI tidak memunculkan kemampuan ini.

Untuk menampilkan nama label dan/atau memberlakukan pembatasan khusus UI, aplikasi Anda harus memanggil titik akhir Perlindungan Informasi Microsoft Purview untuk mengambil metadata label lengkap dan izin terkait.

Anda dapat menggunakan GUID yang dikembalikan oleh Pencarian Azure AI untuk mengatasi properti label dan memanggil API label Purview Labels untuk mengambil nama label, deskripsi, dan pengaturan kebijakan.

Memecahkan masalah kesalahan kueri

Saat evaluasi label sensitivitas waktu kueri gagal, Pencarian Azure AI mengembalikan kode kesalahan HTTP tertentu yang mengidentifikasi penyebabnya. Layanan tidak pernah mengembalikan tataan hasil parsial atau tidak difilter. Jika kebijakan label tidak dapat dievaluasi, kueri gagal daripada mengekspos konten yang tidak berlabel atau tidak sah.

400 Permintaan Tidak Valid

Kesalahan 400 menunjukkan masalah dengan konfigurasi indeks atau header permintaan. Perbaiki konfigurasi sebelum mencoba kembali.

401 Tidak Sah

Kesalahan 401 menunjukkan masalah dengan token otorisasi atau izin Purview aplikasi.

Kesalahan 502: Bad Gateway

Kesalahan 502 menunjukkan kegagalan konektivitas antara Pencarian Azure AI dan Microsoft Purview. Kesalahan ini biasanya bersifat sementara.

Kesalahan 504: Gateway Timeout

Kesalahan 504 menunjukkan bahwa Microsoft Purview tidak merespons dalam waktu yang diizinkan.

Persiapan pengujian end-to-end

Untuk membantu Anda memvalidasi konfigurasi label sensitivitas di Pencarian Azure AI, lihat penyiapan referensi menyeluruh.

Repositori ini menunjukkan cara:

• Mengonfigurasi sinkronisasi dan penghormatan label sensitivitas di Pencarian Azure AI
• Menguji skenario penyerapan dan penegakan waktu kueri untuk dokumen dengan label sensitivitas
• Ekstrak nama label dan tampilkan sebagai bagian dari kutipan yang digunakan dalam aplikasi atau agen RAG Anda.