Kontrol akses tingkat dokumen di Pencarian Azure AI

Important

Fitur dan fungsionalitas ini adalah bagian dari REST API pratinjau 2026-05-01. Pratinjau 2026-05-01 dilisensikan kepada Anda sebagai bagian dari langganan Azure Anda dan tunduk pada persyaratan yang berlaku untuk "Pratinjau" dalam Ketentuan Produk Microsoft, Adendum Perlindungan Data Produk dan Layanan Microsoft ("DPA"), dan Ketentuan Penggunaan Supplemental untuk Pratinjau Microsoft Azure.

Versi pratinjau 2026-05-01 mendukung koneksi ke layanan Microsoft dan layanan pihak ketiga. Penggunaan layanan ini tunduk pada persyaratan masing-masing dan dapat mengakibatkan pemrosesan data atau penyimpanan di luar batas kepatuhan Azure, serta data yang mengalir ke batas kepatuhan Azure.

2026-05-01-preview tidak dapat mengubah izin akses yang ditetapkan di luar 2026-05-01-preview. Jika Anda menggunakan pratinjau 2026-05-01 dengan konten yang dibatasi akses atau izin, jeda waktu akan terjadi sebelum pratinjau 2026-05-01 mengenali perubahan pada pembatasan akses atau izin tersebut.

Anda bertanggung jawab untuk mengelola apakah data Anda akan mengalir di luar batas kepatuhan dan geografis organisasi Anda dan implikasi terkait, dan bahwa izin, batas, dan persetujuan yang sesuai disediakan.

Anda bertanggung jawab untuk meninjau dan menguji aplikasi yang Anda buat dengan cermat dalam konteks kasus penggunaan spesifik Anda dan membuat semua keputusan dan penyesuaian yang sesuai. Ini termasuk menerapkan mitigasi AI Anda sendiri yang bertanggung jawab, seperti metaprompts, filter konten, atau sistem keamanan lainnya, dan memastikan aplikasi Anda memenuhi standar kualitas, keandalan, keamanan, dan kepercayaan yang sesuai. Untuk informasi selengkapnya, lihat Catatan Transparansi Pencarian Azure AI.

Pencarian Azure AI mendukung kontrol akses tingkat dokumen, memungkinkan organisasi untuk menerapkan izin terperindar pada tingkat dokumen, dari penyerapan data melalui eksekusi kueri. Kemampuan ini sangat penting untuk membangun sistem AI yang mengamankan data, aplikasi retrieval-augmented generation (RAG), dan solusi pencarian korporat yang memerlukan pemeriksaan otorisasi di tingkat dokumen.

Pendekatan untuk kontrol akses tingkat dokumen

Pencarian Azure AI menyediakan empat pendekatan utama untuk menerapkan izin tingkat dokumen, masing-masing cocok untuk sumber data dan model identitas yang berbeda.

Pendekatan Deskripsi
Filter keamanan Perbandingan string. Aplikasi Anda meneruskan identitas pengguna atau grup sebagai string, yang mengisi sebuah filter dalam kueri, tidak termasuk dokumen apa pun yang tidak sesuai dengan string.

Filter keamanan adalah teknik untuk mencapai kontrol akses tingkat dokumen. Pendekatan ini tidak terikat ke API sehingga Anda dapat menggunakan versi atau paket apa pun.
Cakupan ACL / RBAC seperti POSIX (pratinjau) Prinsip keamanan Microsoft Entra di balik token kueri dibandingkan dengan metadata izin dokumen yang dikembalikan dalam hasil pencarian, tidak termasuk dokumen apa pun yang tidak cocok dengan izin. Izin daftar kontrol akses (ACL) berlaku untuk direktori dan file Azure Data Lake Storage (ADLS) Gen2. Cakupan kontrol akses berbasis peran (RBAC) berlaku untuk konten ADLS Gen2 dan untuk Azure blob.

Dukungan bawaan untuk akses berbasis identitas di tingkat dokumen sedang dalam tahap pratinjau, tersedia di API-API REST dan paket-paket Azure SDK pratinjau yang menyediakan fitur ini. Untuk bukti dukungan fitur, periksa detail dukungan versi SDK.
label sensitivitas Microsoft Purview (pratinjau) Pengindeks mengekstrak label sensitivitas yang ditentukan dalam Microsoft Purview dari sumber data yang didukung (Azure Blob Storage, ADLS Gen2, SharePoint di Microsoft 365, OneLake). Label ini disimpan sebagai metadata dan dievaluasi pada waktu kueri untuk memberlakukan akses pengguna berdasarkan token Microsoft Entra dan penetapan kebijakan Purview. Label juga ditampilkan melalui sumber pengetahuan dan respons pengambilan berbasis agen, sehingga agen AI dan aplikasi chat yang menggunakan basis pengetahuan dapat menerima pemfilteran berbasis label yang sama. Pendekatan ini menyelaraskan otorisasi Pencarian Azure AI dengan model Microsoft Information Protection perusahaan Anda.
SharePoint dalam Microsoft 365 ACL (pratinjau) Saat dikonfigurasi, pengindeks Pencarian Azure AI mengekstrak dokumen SharePoint, item daftar, dan izin halaman situs ASPX langsung dari ACL Microsoft 365. Mulai dari REST API versi pratinjau 2026-05-01, perubahan ACL untuk item dengan izin unik juga akan terdeteksi secara inkremental setiap kali pengindeks berhasil dijalankan. Pemeriksaan akses menggunakan keanggotaan pengguna dan grup di Microsoft Entra, dengan grup situs SharePoint juga didukung dalam pratinjau yang sama, bergantung pada konfigurasi tambahan. Memerlukan Microsoft Graph Sites.FullControl.All (untuk membaca konten SharePoint dan ACL) pada pendaftaran aplikasi; User.Read.All juga diperlukan saat Anda mengindeks item daftar atau halaman situs ASPX (untuk menyelesaikan alamat email yang dikembalikan oleh REST API SharePoint ke id objek Microsoft Entra). Untuk matriks izin per skenario lengkap, termasuk kombinasi izin minimum, lihat Izin menurut skenario ACL.

Pilih pendekatan

Gunakan kriteria berikut untuk mengidentifikasi pendekatan yang paling sesuai dengan sumber data, model identitas, dan persyaratan kepatuhan Anda.

Scenario Pendekatan yang disarankan Mengapa
Sistem identitas kustom, kerangka kerja keamanan non-Microsoft, atau indeks model push apa pun. Filter keamanan tidak bergantung pada API, tersedia secara umum, dan berdasarkan pencocokan string sederhana.
Konten di ADLS Gen2 atau Azure Blob Storage dengan penetapan ACL atau RBAC yang sudah ada. Cakupan ACL / RBAC mirip POSIX Integrasi Microsoft Entra bawaan; penegakan pada saat kueri menggunakan metadata izin yang dituliskan ke indeks oleh mekanisme sinkronisasi yang didokumentasikan.
Konten perusahaan sudah diatur oleh kebijakan perlindungan informasi Microsoft Purview. Label sensitivitas Microsoft Purview Menggunakan kembali klasifikasi terpusat dan penetapan kebijakan di Pencarian Azure AI.
Konten yang bersumber dari SharePoint di Microsoft 365 (pustaka, daftar, halaman situs ASPX). SharePoint dalam ACL Microsoft 365 Menghormati izin SharePoint asli, termasuk grup situs SharePoint.

Untuk perbandingan fitur berdampingan (prinsipal yang didukung, jenis item, perilaku sinkronisasi, dan permukaan API), lihat bagian pola tertaut nanti dalam artikel ini dan Cara mengindeks SharePoint dalam izin tingkat dokumen Microsoft 365 (pratinjau).

Pola pemangkasan keamanan dengan menggunakan filter

Untuk skenario saat integrasi cakupan ACL/RBAC asli tidak layak, filter string keamanan direkomendasikan untuk memangkas hasil berdasarkan kriteria pengecualian. Pola ini mencakup komponen-komponen berikut:

  • Untuk menyimpan identitas pengguna atau grup, buat bidang string dalam indeks.
  • Muat indeks menggunakan dokumen sumber yang menyertakan ACL terkait.
  • Sertakan ekspresi filter dalam logika kueri Anda untuk pencocokan pada string.
  • Pada waktu kueri, dapatkan identitas pemanggil.
  • Masukkan identitas pemanggil sebagai string filter.
  • Hasil dipangkas untuk mengecualikan kecocokan apa pun yang gagal menyertakan string identitas pengguna atau grup.

Anda dapat menggunakan API model dorong atau tarik. Karena pendekatan ini agnostik API, Anda hanya perlu mengonfirmasi bahwa indeks dan kueri memiliki string (identitas) yang valid untuk langkah filtrasi.

Pendekatan ini berguna untuk sistem dengan model akses kustom atau kerangka kerja keamanan non-Microsoft. Untuk informasi selengkapnya tentang pendekatan ini, lihat filter Keamanan untuk memangkas hasil Pencarian Azure AI.

Pola untuk dukungan bawaan izin jangkauan ACL dan RBAC mirip POSIX (pratinjau)

Dukungan asli didasarkan pada pengguna dan grup Microsoft Entra yang berafiliasi dengan dokumen yang ingin Anda indeks dan kueri.

kontainer Azure Data Lake Storage (ADLS) Gen2 mendukung ACL pada kontainer dan file. Untuk ADLS Gen2, pelestarian cakupan RBAC di tingkat dokumen didukung secara asli saat Anda menggunakan pengindeks ADLS Gen2 atau sumber pengetahuan Blob (mendukung ADLS Gen2) dan API pratinjau untuk menyerap konten. Untuk blob Azure yang menggunakan pengindeks blob Azure atau sumber pengetahuan, cakupan RBAC dipertahankan pada tingkat kontainer.

Untuk konten yang diamankan ACL, sebaiknya akses grup melalui akses pengguna individual untuk kemudahan manajemen. Pola ini mencakup komponen-komponen berikut:

Aplikasi klien Anda menerima izin baca ke indeks melalui peran Pembaca Data Indeks Pencarian atau Kontributor Data Indeks Pencarian . Akses pada waktu kueri ditentukan oleh metadata izin pengguna atau grup dalam konten terindeks. Kueri yang menyertakan filter izin akan memasukkan token pengguna atau grup sebagai x-ms-query-source-authorization di header dari permintaan. Saat Anda menggunakan filter izin selama waktu kueri, Pencarian Azure AI memeriksa dua hal:

  • Pertama, ini memeriksa izin Pembaca Data Indeks Pencarian yang memungkinkan aplikasi klien Anda mengakses indeks.

  • Kedua, dengan adanya token tambahan pada permintaan, sistem memeriksa izin pengguna atau grup pada dokumen yang dikembalikan dalam hasil pencarian, dan mengecualikan dokumen yang tidak cocok.

Untuk mendapatkan metadata izin ke dalam indeks, Anda dapat menggunakan API push model, dengan mendorong dokumen JSON apa pun ke indeks pencarian, di mana payload menyertakan field string yang menyediakan ACL seperti POSIX untuk setiap dokumen. Perbedaan penting antara pendekatan ini dan pemangkasan keamanan adalah bahwa metadata filter izin dalam indeks dan kueri dikenali sebagai autentikasi Microsoft Entra ID, sedangkan solusi pemangkasan keamanan adalah perbandingan string sederhana. Selain itu, Anda dapat menggunakan Graph SDK untuk mengambil identitas.

Anda juga dapat menggunakan API model penarikan (pengindeks) jika sumber data Azure Data Lake Storage (ADLS) Gen2 dan kode Anda memanggil API pratinjau untuk pengindeksan.

Mengambil metadata izin ACL selama proses penyerapan data (pratinjau)

Cara Anda mengambil hak akses ACL bervariasi tergantung pada apakah Anda mengirimkan payload dokumen atau menggunakan pengindeks ADLS Gen2.

Mulailah dengan API pratinjau yang menyediakan fitur:

Untuk pendekatan model pendorongan:

  1. Pastikan bahwa skema indeks Anda dibuat menggunakan SDK pratinjau atau prarilis dan memiliki filter perizinan.
  2. Pertimbangkan untuk menggunakan SDK Microsoft Graph untuk mendapatkan identitas grup atau pengguna.
  3. Gunakan Index Documents atau API Azure SDK yang setara untuk mendorong dokumen dan metadata izin terkait ke dalam indeks pencarian.

Untuk model penarikan pendekatan pengindeks ADLS Gen2 atau sumber pengetahuan Blob (ADLS Gen2):

  1. Verifikasi bahwa file dalam direktori diamankan menggunakan model kontrol akses ADLS Gen2.
  2. Gunakan Indexers - Create (REST API), Knowledge Sources - Create (REST API), atau API Azure SDK yang setara untuk membuat pengindeks, indeks, dan sumber data.

Jika kumpulan keterampilan Anda membagi dokumen menjadi beberapa bagian, misalnya dengan keterampilan Text Split untuk vektorisasi terintegrasi, bidang metadata izin dipindahkan dari pemetaan bidang pengindeks ke proyeksi indeks. Lihat Pilih lokasi untuk mengisi bidang ACL.

Pola untuk penyerapan izin dasar ACL di SharePoint dalam Microsoft 365 (pratinjau)

Untuk SharePoint dalam konten Microsoft 365, Pencarian Azure AI dapat menerapkan izin tingkat dokumen berdasarkan ACL SharePoint. Dengan integrasi ini, hanya pengguna atau grup yang memiliki akses ke item sumber di SharePoint yang dapat mengambilnya dari hasil pencarian. Pencocokan berlaku setelah metadata ACL ditulis ke indeks pada eksekusi pengindeks terjadwal berikutnya yang berhasil setelah perubahan pada sumber. Penyerapan ACL berlaku untuk dokumen dalam pustaka, item dalam daftar SharePoint, dan halaman situs ASPX.

Dukungan ACL SharePoint tersedia dalam pratinjau melalui pengindeks SharePoint menggunakan REST API 2026-05-01-preview atau SDK yang didukung.

Pola ini mencakup komponen-komponen berikut:

  • Gunakan SharePoint di pengindeks Microsoft 365 dengan izin aplikasi untuk membaca konten situs SharePoint dan izin penuh untuk membaca ACL. Ikuti langkah-langkah konfigurasi ACL pengindeks SharePoint untuk pengaktifan dan batasan.

  • Selama pengindeksan awal, SharePoint entri ACL (pengguna dan grup) disimpan sebagai metadata izin dalam indeks pencarian.

  • Mulai dari REST API pratinjau 2026-05-01, sinkronisasi ACL SharePoint mengikuti model ini:

    • Perubahan pada item dengan izin unik terdeteksi dan disegarkan pada setiap pengindeks yang berhasil dijalankan.
    • Perubahan yang diwarisi dari cakupan induk (situs, pustaka, daftar, atau folder) memerlukan refresh eksplisit, seperti /resync dengan options: ["permissions"] atau /resetdocs. Untuk informasi selengkapnya, lihat Menyinkronkan izin antara konten terindeks dan sumber.

  • Pada waktu kueri, Pencarian Azure AI memeriksa prinsipal Microsoft Entra dalam token kueri terhadap metadata ACL SharePoint yang disimpan dalam indeks. Ini mengecualikan item apa pun yang tidak diizinkan untuk diakses oleh pemanggil.

Selama pratinjau, jenis utama berikut didukung dalam ACL SharePoint:

  • Akun pengguna Microsoft Entra
  • Microsoft Entra kelompok keamanan
  • grup Microsoft 365
  • Grup keamanan dengan dukungan email
  • grup situs SharePoint (pratinjau, mulai dari REST API 2026-05-01-preview). Memerlukan konfigurasi indeks tambahan. Untuk informasi selengkapnya, lihat Mengonfigurasi dukungan grup SharePoint.

kebijakan Manajemen Informasi SharePoint yang membatasi akses pengguna tidak dievaluasi, diproses, atau diterapkan saat kueri dijalankan.

Untuk detail konfigurasi dan batasan penuh, lihat Cara mengindeks SharePoint dalam izin tingkat dokumen Microsoft 365 (pratinjau). Untuk panduan konfigurasi menyeluruh termasuk dukungan grup situs SharePoint, lihat Konfigurasi dukungan grup SharePoint.

Jika skillset Anda memecah dokumen menjadi potongan-potongan (misalnya, dengan skill Text Split untuk vektorisasi terintegrasi), bidang ACL berpindah dari pemetaan bidang indexer ke proyeksi indeks. Lihat Pilih lokasi untuk mengisi bidang ACL.

Pola untuk label sensitivitas Microsoft Purview (pratinjau)

Saat penyerapan label diaktifkan, Pencarian Azure AI mengekstrak metadata sensitivitas dari sumber data yang didukung. Ini termasuk: Azure Blob Storage, Azure Data Lake Storage Gen2 (ADLS Gen2), SharePoint di Microsoft 365, dan Microsoft OneLake. Label yang diekstrak disimpan dalam indeks bersama konten dokumen.

Pada waktu kueri, Pencarian Azure AI memeriksa label sensitivitas setiap dokumen, token Microsoft Entra pengguna, dan kebijakan Purview organisasi untuk menentukan akses. Dokumen dikembalikan hanya jika identitas pengguna dan izin berbasis label memungkinkan akses di bawah kebijakan Purview yang dikonfigurasi.

Pola ini mencakup komponen-komponen berikut:

  • Konfigurasikan indeks, sumber data, dan pengindeks Anda (untuk tujuan penjadwalan) menggunakan REST API pratinjau 2026-05-01 atau SDK terkait yang mendukung penyerapan label Purview.
  • Aktifkan identitas terkelola yang ditetapkan sistem ke layanan pencarian Anda. Kemudian minta administrator global penyewa atau administrator peran istimewa Anda untuk membagikan akses yang diperlukan, sehingga layanan pencarian dapat mengakses Microsoft Purview dan mengekstrak metadata label dengan aman.
  • Terapkan label sensitivitas ke dokumen sebelum pengindeksan sehingga dapat dikenali dan dipertahankan selama penyerapan.
  • Pada waktu kueri, lampirkan token Microsoft Entra yang valid melalui header x-ms-query-source-authorization ke setiap permintaan kueri. Pencarian Azure AI mengevaluasi token dan metadata label terkait untuk menerapkan kontrol akses berbasis label.

Pemberlakuan label sensitivitas Purview terbatas pada skenario tenant tunggal dan memerlukan autentikasi RBAC. Selama pratinjau, fitur ini hanya didukung melalui REST API dan Azure SDK. API Autocomplete dan Suggest saat ini tidak tersedia untuk indeks yang mendukung Purview.

Tempat label sensitivitas ditampilkan

Sebelum label dapat diberlakukan pada waktu kueri atau dikembalikan dalam respons pengambilan, metadata label harus terlebih dahulu disinkronkan ke dalam indeks. Kedua jalur konsumsi yang dijelaskan di bagian ini bergantung pada langkah sinkronisasi ini. Anda dapat menyinkronkan label baik dengan mengonfigurasi pengindeks Pencarian Azure AI secara langsung terhadap sumber data yang didukung, atau dengan mengaktifkan opsi penyerapan yang setara saat Anda membuat sumber pengetahuan. Dalam kedua kasus, lingkungan Anda harus memenuhi prasyarat konfigurasi sinkronisasi metadata label sensitivitas (identitas terkelola, RBAC di layanan pencarian, serta izin Microsoft Purview dan sumber data yang diperlukan). Untuk penyiapan indexer menyeluruh, lihat Menggunakan indexer Pencarian Azure AI untuk mengimpor label sensitivitas Microsoft Purview. Untuk ingesti berbasis sumber pengetahuan, atur ingestionPermissionOptions agar menyertakan sensitivityLabel selama pembuatan sumber pengetahuan.

Setelah label disinkronkan, metadata label terindeks yang sama digunakan melalui dua jalur kueri. Pilih jalur yang cocok dengan cara aplikasi Anda memanggil Pencarian Azure AI:

Jika sumber pengetahuan menunjuk ke indeks yang dibagi menjadi potongan-potongan, seperti yang diisi melalui vektorisasi terintegrasi atau skill Pemisahan Teks kustom, skillset juga harus memproyeksikan label sensitivitas ke setiap baris potongan. Tanpa proyeksi ini, referensi tingkat gugus tidak difilter.

Untuk informasi selengkapnya, lihat Gunakan pengindeks Pencarian Azure AI untuk menyerap label sensitivitas Microsoft Purview.

Menerapkan izin tingkat dokumen saat kueri dilakukan

Penegakan kueri berbasis token adalah kapabilitas lintas fungsi yang berlaku untuk cakupan ACL/RBAC mirip POSIX, label sensitivitas Microsoft Purview, serta pola ACL SharePoint di Microsoft 365. Dengan kueri berbasis token bawaan, Pencarian Azure AI memvalidasi token Microsoft Entra milik pemanggil pada setiap permintaan dan memangkas kumpulan hasil sehingga hanya mencakup dokumen yang diizinkan untuk dibaca oleh pemanggil sesuai dengan ACL dokumen, selama metadata ACL dokumen telah disinkronkan ke indeks.

Saat Anda melampirkan token pengguna ke permintaan kueri melalui header x-ms-query-source-authorization, Pencarian Azure AI:

  1. Mengekstrak klaim pengguna, grup, dan cakupan dari token.
  2. Membandingkan klaim tersebut dengan metadata izin yang disimpan bersama dokumen terindeks (entri ACL, cakupan RBAC, penetapan label Purview, atau ACL SharePoint).
  3. Mengembalikan hanya dokumen yang metadata izinnya disinkronkan yang memberikan akses pemanggil.

Penerapan saat kueri membandingkan klaim Microsoft Entra milik pemanggil dengan metadata izin yang telah disimpan di dalam indeks. Perubahan izin dalam sistem sumber (Microsoft Entra keanggotaan grup, ACL ADLS Gen2, penetapan label Purview, atau ACL SharePoint) hanya tercermin dalam hasil pencarian setelah metadata tersebut disinkronkan ke indeks melalui mekanisme khusus sumber, misalnya, eksekusi pengindeks berikutnya, pembaruan PUSH-API, atau refresh berbasis Purview. Untuk SharePoint, perubahan ACL pada item dengan izin unik terdeteksi secara bertahap pada setiap eksekusi indexer yang berhasil mulai REST API versi pratinjau 2026-05-01, sedangkan perubahan yang diwarisi dari cakupan induk (situs, pustaka, daftar, atau folder) memerlukan penyegaran eksplisit. Untuk informasi selengkapnya, lihat Menyinkronkan izin antara konten terindeks dan sumber.

Untuk langkah-langkah penerapan kueri secara menyeluruh, lihat Penegakan ACL dan RBAC pada waktu kueri di Pencarian Azure AI.

Manfaat kontrol akses tingkat dokumen

Kontrol akses tingkat dokumen asli di Pencarian Azure AI memberikan keuntungan konkret daripada pemfilteran sisi aplikasi:

  • Menghilangkan kode izin kustom: Anda tidak perlu menerapkan resolusi grup berlapis, traversal ACL multi-tingkat, atau pemangkasan pasca-kueri di aplikasi Anda. Pencarian Azure AI menangani perbandingan dan pemfilteran selama eksekusi kueri.
  • Sejajarkan dengan kontrol kepatuhan yang ada: Menggunakan kembali metadata izin Microsoft Entra, Microsoft Purview, dan SharePoint membantu menjaga hasil pencarian tetap selaras dengan sistem identitas sumber. Tinjau model sinkronisasi izin untuk setiap sumber untuk memahami batasannya.
  • Mematuhi izin sumber setelah setiap sinkronisasi ACL: Untuk pendekatan berbasis token (ACL, cakupan RBAC, label Purview, ACL SharePoint), penegakan pada waktu kueri menggunakan metadata izin yang telah ditulis ke indeks oleh mekanisme sinkronisasi khusus sumber yang didokumentasikan (eksekusi pengindeks, pembaruan Push API, atau penyegaran Purview).
  • Meningkatkan kinerja dibandingkan dengan pemangkasan setelah kueri: Penyaringan di dalam alur pencarian lebih cepat daripada memuat kumpulan hasil yang lebih besar ke dalam aplikasi Anda lalu memangkasnya di sana, terutama ketika volume kueri tinggi.
  • Menggunakan kembali infrastruktur identitas yang sudah ada: Microsoft Entra dan identitas SharePoint tetap menjadi rujukan utama untuk keputusan pemberian akses, sehingga mengurangi duplikasi identitas dan beban operasional tambahan untuk memelihara penyimpanan izin paralel.

Tutorial dan sampel

Lihat lebih dekat kontrol akses tingkat dokumen di Pencarian Azure AI dengan lebih banyak artikel dan sampel.

Konten terkait

  • Last updated on