Mengindeks daftar kontrol akses (ACL) dokumen menggunakan REST API push (pratinjau)

Penyerapan izin tingkat dokumen melalui REST API push (pratinjau) memungkinkan Anda mengindeks dokumen beserta daftar kontrol akses (ACL) terkait dan peran kontrol akses berbasis peran (RBAC) kontainer. Saat Anda mendorong konten ke dalam indeks Pencarian Azure AI melalui push REST API, layanan mempertahankan izin tersebut pada konten yang diindeks dan memberlakukannya saat kueri dijalankan.

Fitur utama meliputi:

• Kontrol fleksibel atas alur penyerapan.
• Skema standar untuk metadata izin.
• Dukungan untuk izin hierarkis, seperti Daftar Kontrol Akses (ACL) tingkat folder.

Artikel ini menjelaskan cara menggunakan REST API pendorongan untuk mengindeks metadata izin tingkat dokumen di Pencarian Azure AI. Proses ini menyiapkan indeks Anda untuk mengkueri dan menerapkan izin pengguna akhir pada hasil pencarian.

Prasyarat

• Konten dengan metadata ACL dari Microsoft Entra ID atau sistem ACL bergaya POSIX lainnya. Untuk bidang ACL userIds dan groupIds, gunakan ID objek Microsoft Entra (GUID), bukan UPN atau alamat email. ID objek yang stabil memastikan pencocokan identitas yang andal pada waktu kueri, bahkan jika atribut direktori berubah.

• Pratinjau REST API terbaru atau paket pratinjau Azure SDK yang menyediakan fitur setara.

• Skema indeks dengan permissionFilterOption diaktifkan, serta atribut bidang permissionFilter yang menyimpan izin dokumen.

Keterbatasan

• Bidang ACL dengan jenis userIds filter izin atau groupIds dapat menyimpan paling banyak 1000 nilai.

• Indeks dapat menyimpan paling banyak lima nilai unik di antara bidang jenis rbacScope pada semua dokumen. Tidak ada batasan jumlah dokumen yang memiliki nilai yang sama dari rbacScope.

• Bidang yang ada dapat diperbarui untuk menyertakan permissionFilter penugasan untuk pemfilteran metadata ACL atau RBAC bawaan. Untuk mengaktifkan pemfilteran pada indeks yang sudah ada, tambahkan bidang baru atau perbarui bidang yang sudah ada untuk menyertakan permissionFilter nilai.

• Hanya satu bidang dari setiap permissionFilter jenis (satu masing-masing groupIds, userIds, dan rbacScope) yang dapat ada dalam indeks.

• Setiap permissionFilter field harus filterable disetel ke true.

• Penerapan izin akses pada saat kueri mencerminkan nilai ACL yang terakhir ditulis ke indeks. Jika izin sumber berubah, pembaruan tersebut tidak tercermin sampai Anda menyerap ulang atau memperbarui dokumen yang terpengaruh. Jadwalkan penyerapan ulang inkremental atau pembaruan parsial agar ACL tetap mutakhir.

• Fungsionalitas ini saat ini tidak didukung di portal Azure.

Membuat indeks dengan bidang filter izin

Pengindeksan ACL dokumen dan metadata RBAC dengan REST API memerlukan penyetelan skema indeks yang memungkinkan penetapan filter izin dan memiliki bidang dengan penugasan filter izin.

Pertama, tambahkan permissionFilterOption. Nilai yang valid adalah enabled atau disabled, dan Anda harus mengaturnya ke enabled. Anda dapat mengubahnya menjadi disabled jika Anda ingin menonaktifkan fungsi filter izin di tingkat indeks.

Kedua, buat bidang string untuk metadata izin Anda dan sertakan permissionFilter. Ingat bahwa Anda dapat memiliki salah satu dari setiap jenis filter izin.

Berikut adalah contoh skema dasar yang mencakup semua permissionFilter jenis:

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

Untuk repositori perusahaan, seperti SharePoint Online, petakan izin pada tingkat dokumen atau folder ke ID objek pengguna dan grup Microsoft Entra selama proses ingestion sebelum memanggil push API. Anda kemudian harus menyimpan ID tersebut di bidang izin yang sesuai.

Contoh pengindeksan REST API

Setelah Anda memiliki indeks dengan bidang filter izin, Anda dapat mengisi nilai tersebut menggunakan API pengindeksan push, sama seperti bidang dokumen lainnya. Berikut adalah contoh menggunakan skema indeks yang ditentukan, di mana setiap dokumen menentukan tindakan pengindeksan, bidang kunci (DocumentId), dan bidang izin. Dokumen juga harus menyertakan konten, tetapi bidang tersebut dihilangkan dalam contoh ini untuk mempermudah.

POST https://exampleservice.search.windows.net/indexes('indexdocumentsexample')/docs/search.index?api-version=2026-08-01-preview
{
  "value": [
    {
      "@search.action": "upload",
      "DocumentId": "1",
      "UserIds": ["00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "11bb11bb-cc22-dd33-ee44-55ff55ff55ff", "22cc22cc-dd33-ee44-ff55-66aa66aa66aa"],
      "GroupIds": ["none"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-01"
    },
    {
      "@search.action": "merge",
      "DocumentId": "2",
      "UserIds": ["all"],
      "GroupIds": ["33dd33dd-ee44-ff55-aa66-77bb77bb77bb", "44ee44ee-ff55-aa66-bb77-88cc88cc88cc"]
    },
    {
      "@search.action": "mergeOrUpload",
      "DocumentId": "3",
      "UserIds": ["1cdd8521-38cf-49ab-b483-17ddaa48f68f"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-03"
    }
  ]
}

Aturan penyelesaian akses ACL

Bagian ini menjelaskan bagaimana sistem menentukan akses dokumen pengguna berdasarkan bidang izin pada setiap dokumen. Bidang ini adalah ACL (userIds dan groupIds, di mana groupIds termasuk kelompok keamanan dan Grup Microsoft 365) atau cakupan RBAC (rbacScope). Azure mengevaluasi cakupan RBAC dan ACL dalam urutan yang ditentukan, konsisten dengan model izin ADLS Gen2.

Pengguna memperoleh akses dengan memenuhi salah satu kriteria berikut: entri userIds atau groupIds yang cocok, atau penetapan peran Azure yang memenuhi syarat untuk rbacScope. Untuk informasi tentang bagaimana identitas pemanggil diberikan saat kueri dijalankan, lihat Penerapan ACL dan RBAC saat kueri dijalankan.

Nilai ACL khusus "semua" dan "tidak ada"

Bidang ACL, seperti userIds dan groupIds, biasanya berisi daftar GUID (Pengidentifikasi Unik Global) yang mengidentifikasi pengguna dan grup dengan akses ke dokumen. Dua nilai string khusus, "semua" dan "tidak ada", didukung untuk jenis bidang ACL ini. Nilai-nilai ini bertindak sebagai filter luas untuk mengontrol akses di tingkat global, seperti yang diperlihatkan dalam tabel berikut.

Karena pengguna hanya perlu mencocokkan satu jenis bidang, nilai khusus "semua" memberikan akses publik terlepas dari nilai bidang ACL lainnya. Sebaliknya, pengaturan userIds ke "tidak ada" atau array kosong berarti tidak ada pengguna yang diberikan akses ke dokumen berdasarkan ID pengguna. Mereka mungkin masih dapat diberikan akses dengan mencocokkan ID grup atau metadata RBAC.

Contoh kontrol akses

Contoh ini menggambarkan bagaimana aturan akses dokumen diselesaikan berdasarkan nilai bidang izin di userIds, groupIds, dan rbacScope. Untuk keterbacaan, skenario ini menggunakan alias seperti "user1" dan "group1" alih-alih GUID; dalam produksi, gunakan ID objek Microsoft Entra (GUID).

Konten terkait

• Hubungkan ke Pencarian Azure AI menggunakan peran
• Penerapan ACL dan RBAC pada saat kueri
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API