Gunakan pengindeks SharePoint untuk menyerap metadata izin dan memfilter hasil pencarian berdasarkan hak akses pengguna (pratinjau)

Ingesti metadata izin SharePoint (pratinjau) menggunakan pengindeks Pencarian Azure AI untuk mempertahankan metadata izin, seperti daftar kontrol akses (ACL), bersama konten lainnya dari SharePoint di Microsoft 365. Pengindeks menyimpan izin sebagai metadata pada setiap dokumen terindeks. Saat kueri dijalankan, pengguna hanya menerima dokumen yang diizinkan untuk mereka akses.

Diagram arsitektur menunjukkan solusi RAG dengan keamanan yang ditingkatkan di mana pengindeks SharePoint mengambil dokumen dan metadata izin ACL dari situs SharePoint, menyimpannya dalam indeks Pencarian Azure AI, dan orkestrator RAG memfilter hasil kueri sehingga setiap pengguna hanya mengambil dokumen yang diizinkan untuk diakses.

Prasyarat

• Pencarian Azure AI pada tingkat yang dapat ditagih (Dasar atau lebih tinggi) di wilayah mana pun.

• SharePoint di situs, pustaka, folder, dan file Microsoft 365 dengan izin yang dikonfigurasi.

• Selesaikan semua langkah konfigurasi dalam dokumentasi pengindeks SharePoint, menerapkan persyaratan khusus ACL yang dijelaskan dalam artikel ini.

• Konfigurasikan izin aplikasi Microsoft Entra dan kredensial yang sesuai untuk skenario Anda. Lihat Izin berdasarkan skenario ACL. Penyerapan ACL memerlukan izin aplikasi. Izin yang didelegasikan tidak didukung. Untuk pilihan antara aplikasi dan izin yang didelegasikan, lihat Pilih penyiapan izin Anda.

• REST API versi 2026-08-01-preview atau paket SDK pratinjau yang setara.

Keterbatasan

• Pembaruan ACL inkremental memerlukan REST API versi pratinjau 2026-05-01 atau yang lebih baru. Dalam versi API pratinjau sebelumnya, sistem hanya mengambil ACL pada penyerapan pertama setiap item. Perubahan izin selanjutnya memerlukan pengindeksan ulang secara eksplisit. Untuk langkah-langkah migrasi, lihat Menyinkronkan izin antara konten terindeks dan sumber.

• Perubahan izin cakupan induk tidak terdeteksi secara otomatis pada eksekusi pengindeks berikutnya. Untuk opsi refresh, lihat Menyinkronkan izin antara konten terindeks dan sumber.

• Portal Azure tidak mendukung fitur ini.

• Fitur berikut ini tidak didukung dalam pratinjau ini:

  • SharePoint kebijakan Manajemen Informasi berlaku untuk akses pengguna. Sistem tidak mengevaluasi, menerima, atau menerapkan kebijakan ini saat kueri dijalankan.

  • Tautan yang dapat dibagikan dilingkup ke "Siapa saja" atau "Orang di organisasi Anda." Hanya tautan yang dilingkup ke "Orang tertentu" yang didukung.

  • grup SharePoint (seperti grup Pemilik, Anggota, dan Pengunjung) didukung mulai di REST API pratinjau 2026-05-01. Lihat Konfigurasi dukungan grup SharePoint. Dalam versi API pratinjau sebelumnya, hanya grup SharePoint yang dipetakan ke grup Microsoft Entra yang didukung.

• Fitur pengindeks berikut tidak mendukung pewarisan izin dalam dokumen terindeks yang berasal dari SharePoint. Jika Anda menggunakan salah satu fitur ini dalam kumpulan keterampilan atau pengindeks, izin level dokumen tidak disertakan dalam konten terindeks.

  • Keahlian API Web Khusus

  • Penyimpanan pengetahuan, termasuk penyimpanan aset yang diperlukan untuk penyajian gambar (pratinjau) dalam pengambilan agenik. Oleh karena itu, penyajian gambar tidak didukung untuk sumber pengetahuan yang menyerap ACL SharePoint.

  • Cache penyempurnaan pengindeks

  • Sesi debug

Dukungan untuk model izin SharePoint

Versi pratinjau ini mendukung ACL dasar untuk dokumen, item daftar, dan halaman situs ASPX modern.

Hubungan grup yang didukung

Microsoft Entra transitivitas grup berlaku dalam Microsoft Entra. Ini tidak memperluas grup Microsoft Entra yang merupakan anggota grup SharePoint.

Bagaimana izin hirarkis dievaluasi

SharePoint izin mewarisi hierarki Situs → Pustaka → Folder → File, kecuali pewarisan rusak.

Selama penyerapan, pengindeks mengumpulkan pengidentifikasi pengguna dan grup (ID) di setiap tingkat dan menghitung ACL yang efektif untuk setiap file.

Izin menurut skenario ACL

Izin aplikasi Microsoft Entra dan jenis kredensial yang diperlukan untuk penyerapan ACL bergantung pada jenis item dan jenis grup yang Anda indeks. Dalam pendaftaran aplikasi, semua izin ditambahkan di bawah izin> APITambahkan izin, dan kredensial federasi ditambahkan di bawah Sertifikat & rahasia>Kredensial Federasi. Untuk petunjuk langkah demi langkah dan cuplikan layar, lihat Step 3: Membuat pendaftaran aplikasi Microsoft Entra dan Mengonfigurasi aplikasi terdaftar dengan identitas terkelola.

Kredensial federasi mengautentikasi aplikasi menggunakan identitas terkelola tepercaya alih-alih rahasia klien. Kredensial federasi yang sama mencakup baik proses ingest (pengindeks) maupun evaluasi saat kueri untuk grup situs SharePoint. Untuk langkah-langkah penyiapan, lihat Mengonfigurasi aplikasi terdaftar dengan identitas terkelola.

Sebelum Anda mengaktifkan proses penyerapan ACL

Selesaikan langkah-langkah ini pada aplikasi Microsoft Entra terdaftar Anda:

1. Identifikasi skenario Anda di tabel sebelumnya berdasarkan apa yang Anda rencanakan untuk diindeks (file pustaka dokumen, item daftar, halaman situs ASPX) dan apakah grup situs SharePoint harus dihormati.
2. Buka pendaftaran aplikasi Anda di pusat admin Microsoft Entra dan buka izin API>Tambahkan izin.
3. Tambahkan izin Microsoft Graph yang tercantum untuk skenario Anda. Memberikan persetujuan admin.
4. Jika skenario Anda juga memerlukan izin SharePoint, pilih Tambahkan izin lagi, pilih SharePoint API, dan tambahkan Sites.FullControl.All (atau Sites.Selected). Memberikan persetujuan admin.
5. Konfigurasikan kredensial:
   • Untuk skenario khusus Microsoft Graph, Anda dapat menggunakan rahasia klien (Certificates & secrets>Rahasia klien) atau kredensial federasi.
   • Untuk skenario apa pun yang mencakup izin SharePoint, tambahkan kredensial federasi di bawah Certificates & secrets>Federated credentials. Lihat Mengonfigurasi aplikasi terdaftar dengan identitas terkelola.
6. Berikan akses aplikasi ke situs SharePoint target (terutama penting ketika Anda menggunakan Sites.Selected untuk akses tercakup) sehingga dapat membaca konten dan izin yang ingin Anda indeks.

Temukan pengidentifikasi Microsoft Entra yang benar

Setiap pengenal muncul di lokasi yang berbeda di portal Azure dan sesuai dengan bidang konfigurasi tertentu. Gunakan bagian ini sebagai referensi saat mengonfigurasi penyerapan ACL SharePoint dengan kredensial federasi. Pengidentifikasi ini dirujuk pada dalam Mengonfigurasi dukungan grup SharePoint dan dalam string koneksi sumber data.

ID aplikasi kredensial federasi

Untuk FederatedCredentialApplicationId dalam string koneksi sumber data dan federatedCredentialId dalam definisi indeks, gunakan ID aplikasi (klien) milik identitas terkelola, bukan ID aplikasi ingesti.

Identitas terkelola yang ditetapkan sistem:

1. Buka layanan Pencarian Azure AI Anda.
2. Pilih Keamanan + Identitas jaringan>.
3. Pada tab Yang ditetapkan sistem, perhatikan ID Objek (utama).
4. Buka Microsoft Entra ID>Kelola>aplikasi Enterprise.
5. Cari nama layanan pencarian Anda atau tempelkan ID Objek (utama) ke dalam kotak pencarian.
6. Pilih hasil dan buka Properti. Salin ID Aplikasi yang ditampilkan di sini, yang merupakan nilai untuk FederatedCredentialApplicationId di sumber data dan federatedCredentialId dalam indeks.

Identitas terkelola yang ditetapkan pengguna:

1. Buka sumber daya identitas terkelola yang ditetapkan pengguna.
2. Pilih Pengaturan>Properti.
3. Salin ID Klien, yang merupakan nilai untuk FederatedCredentialApplicationId di sumber data dan federatedCredentialId dalam indeks.

Mengonfigurasi layanan pencarian Anda untuk penyerapan ACL dan penerapan waktu kueri

Langkah-langkah ini mengonfigurasi layanan pencarian Anda untuk penyerapan ACL dan mengaktifkan penerapan ACL saat waktu kueri.

Pilih tempat untuk mengisi bidang ACL

Di mana Anda memetakan bidang metadata ACL bergantung pada apakah pengindeks menulis satu dokumen per item sumber atau beberapa gugus per item sumber.

Dalam semua skenario yang dibagi menjadi chunk, setiap chunk harus menyertakan field ACL. Filter izin berlaku per dokumen, sehingga potongan bidang ACL yang hilang tidak dapat dikembalikan ke pemanggil yang tepat.

1. Konfigurasi sumber data

Bagian ini merupakan tambahan atas panduan dasar Langkah 4: Membuat sumber data. Atur indexerPermissionOptions dalam definisi sumber data untuk memungkinkan pengindeksan userIds dan groupIds dari dokumen SharePoint.

{
  "name": "my-sharepoint-acl-datasource",
  "type": "sharepoint",
  "indexerPermissionOptions": ["userIds", "groupIds"],
  "credentials": {
    "connectionString": "<connection-string>;"
  },
  "container": {
    "name": "<library-name>",
    "query": "<optional-folder-path>"
  }
}

2. Tambahkan bidang izin ke definisi indeks

Tambahkan bidang ke definisi skema indeks Anda untuk menyimpan ACL dan mendukung pemfilteran waktu kueri.

{
  "fields": [
    { "name": "UserIds",  "type": "Collection(Edm.String)", "permissionFilter": "userIds",  "filterable": true, "retrievable": false },
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

Atur retrievable atribut ke true hanya selama pengembangan untuk memverifikasi nilai. Anda dapat mengubah aksesibilitas dari true ke false tanpa perlu membangun ulang indeks.

3. Mengonfigurasi proyeksi indeks dalam skillset Anda (jika berlaku)

Saat pemotongan diaktifkan, dokumen induk tidak ditulis ke indeks saat projectionMode adalah skipIndexingParentDocuments. Terapkan metadata ACL ke setiap bagian melalui indexProjections.selectors[].mappings.

Jika pengindeks Anda menggunakan set keterampilan dengan potongan data, seperti keterampilan Pemisahan Teks saat mengaktifkan vektorisasi terintegrasi, pastikan untuk memetakan properti ACL ke setiap gugus menggunakan proyeksi indeks. Baris // dalam contoh berikut adalah anotasi ilustratif dan bukan JSON yang valid. Hapus sebelum mengirimkan permintaan.

PUT https://{service}.search.windows.net/skillsets/{skillset}?api-version=2026-08-01-preview
{
  "name": "my-skillset",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
      "name": "#split",
      "context": "/document",
      "inputs": [{ "name": "text", "source": "/document/content" }],
      "outputs": [{ "name": "textItems", "targetName": "chunks" }]
    }
    // ... (other skills such as embeddings, entity recognition, etc.)
  ],
  "indexProjections": {
    "selectors": [
      {
        "targetIndexName": "chunks-index",
        "parentKeyFieldName": "parentId",          // must exist in target index
        "sourceContext": "/document/chunks/*",     // match your split output path
        "mappings": [
          { "name": "chunkId",           "source": "/document/chunks/*/id" },     // if you create an id per chunk
          { "name": "content",           "source": "/document/chunks/*/text" },   // chunk text
          { "name": "parentId",          "source": "/document/id" },              // parent doc id
          { "name": "UserIds",  "source": "/document/metadata_user_ids" },
          { "name": "GroupIds",  "source": "/document/metadata_group_ids" },
          { "name": "SharePointSiteUrl", "source": "/document/metadata_spo_site_url" } // include when the index has sharePointConnectorAppRegistration (SharePoint groups support)
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}

Pemetaan UserIds, GroupIds, dan SharePointSiteUrl membaca metadata tingkat sumber yang dihasilkan oleh pengindeks SharePoint (/document/metadata_*) dan menuliskan nilainya ke setiap potongan.

4. Mengonfigurasi pemetaan bidang pengindeks untuk ACL

Gunakan pemetaan bidang pengindeks saat pengindeks menulis satu dokumen per item sumber (tidak ada potongan) atau saat Anda mempertahankan indeks induk terpisah bersama indeks gugus. Jika kumpulan keterampilan Anda membagi dokumen menjadi potongan-potongan ke satu indeks target dengan projectionMode: skipIndexingParentDocuments, pemetaan bidang yang ditampilkan di sini digantikan oleh indexProjections.mappings dari langkah sebelumnya untuk indeks potongan.

Selain konfigurasi indexer yang diperlukan, petakan bidang ACL metadata mentah dari SharePoint ke bidang indeks Anda.

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids",  "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" }
  ]
}

5. Jalankan pengindeks

Metadata ACL diserap saat pengindeks berjalan. Setelah Anda membuat atau memperbarui pengindeks (lihat Langkah 6: Membuat pengindeks), picu eksekusi sehingga pengindeks menyerap ACL bersama konten.

POST https://[service name].search.windows.net/indexers/[indexer-name]/run?api-version=2026-08-01-preview
api-key: [admin key]

Jika Anda mengaktifkan ingesti ACL pada pengindeks yang sudah ada dan telah mengindeks item, panggil /resync dengan options: ["permissions"] untuk mengisi ACL secara retroaktif bagi item-item tersebut, atau /resetdocs untuk mengekstrak ulang item-item tertentu.

6. Verifikasi penyerapan ACL

Untuk mengonfirmasi nilai ACL yang diisi dengan benar:

1. Untuk sementara, atur retrievable ke true pada UserIds dan GroupIds dalam definisi indeks Anda. Mengubah retrievable tidak memerlukan pembangunan ulang indeks.
2. Jalankan kueri elevated-read yang memilih UserIds dan GroupIds, lalu pastikan koleksi tersebut tidak kosong. Untuk skenario yang dipecah menjadi beberapa chunk, pastikan setiap chunk memuat kedua field tersebut.
3. Kembali retrievable ke false setelah verifikasi.

Konfigurasikan dukungan grup SharePoint

Mulai dari REST API pratinjau 2026-05-01, pengindeks SharePoint dapat menyerap keanggotaan grup situs SharePoint (Pemilik, Anggota, Pengunjung, dan grup situs kustom). Ini menghormati grup ini pada waktu kueri. ID kelompok SharePoint dipancarkan di bidang metadata_group_ids dengan awalan spg: untuk membedakannya dari ID objek grup Microsoft Entra.

Panduan ini mandiri: selesaikan langkah-langkah untuk mengonfigurasi indeks, pemetaan bidang pengindeks, dan mengkueri indeks dengan penerapan grup situs SharePoint.

Komponen berikut bekerja sama untuk mengaktifkan resolusi grup situs SharePoint:

1. Prasyarat

• SharePoint pengindeks sudah dikonfigurasi untuk penyerapan ACL. Lihat Mengonfigurasi pemetaan bidang pengindeks untuk ACL.
• Pendaftaran aplikasi Microsoft Entra dengan kredensial identitas federasi. Lihat Mengonfigurasi aplikasi terdaftar dengan identitas terkelola.
• REST API 2026-05-01-preview atau yang lebih baru.

2. Mengonfigurasi indeks

Tambahkan konfigurasi sharePointConnectorAppRegistration dan bidang SharePointSiteUrl bersama bidang filter izin UserIds dan GroupIds, sehingga struktur indeks lengkap berada di satu tempat. Pertahankan permissionFilterOption: "enabled".

PUT https://{service}.search.windows.net/indexes/{index}?api-version=2026-08-01-preview
{
  "name": "my-sharepoint-acl-index",
  "sharePointConnectorAppRegistration": {
      "applicationId": "<ingestion-app-client-id>",
      "federatedCredentialId": "<managed-identity-application-id>",
     "tenantId": "<sharepoint-tenant-id>"
  },
  "fields": [
    { "name": "UserIds",           "type": "Collection(Edm.String)", "permissionFilter": "userIds",  "filterable": true, "retrievable": false },
    { "name": "GroupIds",          "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false },
    { "name": "SharePointSiteUrl", "type": "Edm.String", "sharepointSiteUrl": true, "filterable": false, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

3. Mengonfigurasi pemetaan bidang pengindeks

Petakan bidang metadata SharePoint ke bidang indeks dalam satu blok pemetaan gabungan. Dua pemetaan pertama adalah pemetaan yang sama yang digunakan untuk penyerapan ACL standar; pemetaan ketiga mengaktifkan resolusi grup SharePoint.

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids",             "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids",            "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_spo_site_url",  "targetFieldName": "SharePointSiteUrl" }
  ]
}

Jika kumpulan keterampilan Anda membagi dokumen menjadi beberapa bagian (misalnya, dengan keterampilan Text Split untuk vektorisasi terintegrasi), proyeksikan SharePointSiteUrl ke setiap bagian melalui indexProjections.mappings sebagai gantinya. Lihat Pilih lokasi untuk mengisi bidang ACL.

4. Mengkueri indeks

Tidak diperlukan perubahan sisi klien. Token x-ms-query-source-authorization yang sama mengaktifkan penerapan kebijakan untuk Microsoft Entra dan grup situs SharePoint. Layanan pencarian menentukan keanggotaan grup SharePoint di sisi server menggunakan sharePointConnectorAppRegistration pada indeks.

Untuk bentuk permintaan, lihat contoh kueri umum dan contoh khusus SharePoint dengan penerapan grup situs SharePoint.

5. Verifikasi

Untuk mengonfirmasi bahwa ID grup SharePoint telah masuk ke indeks, jalankan kueri elevated-read yang memilih GroupIds, lalu cari nilai dengan awalan spg: dalam respons.

Menyinkronkan izin antara konten terindeks dan sumber

Mulai dari REST API pratinjau 2026-05-01-preview, perubahan ACL untuk item dengan izin unik dideteksi dan diperbarui pada setiap eksekusi pengindeks yang berhasil. Pengindeks menggunakan token perubahan SharePoint untuk mendeteksi penambahan dan penghapusan penetapan peran secara inkremental, dengan cara yang sama seperti saat mendeteksi perubahan konten.

Beberapa skenario masih memerlukan refresh eksplisit:

Mereset dokumen tertentu

Anda dapat mengatur ulang dokumen tertentu untuk sepenuhnya menyerap lagi konten dan ACL.

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2026-08-01-preview
{
  "documentKeys": ["doc123", "doc456"]
}

Menyinkronkan ulang ACL di seluruh sumber data lengkap

Anda dapat menyinkronkan ulang konten ACL kumpulan data lengkap setelah penyerapan awal. Agar berhasil sepenuhnya, operasi ini memerlukan pengindeks yang dijalankan setelah selesai.

POST https://{service}.search.windows.net/indexers/{indexer}/resync?api-version=2026-08-01-preview
{
  "options": ["permissions"]
}

Setelah mengindeks data dan ACL, Anda bisa mengkueri indeks.

Troubleshooting

Untuk hasil yang hilang, tidak terduga, atau gagal pada waktu kueri setelah metadata ACL diindeks, lihat Pemecahan masalah pemfilteran izin SharePoint.

Konten terkait

• Indeks konten SharePoint di Pencarian Azure AI (pratinjau)
• Penerapan ACL waktu kueri