Menggunakan pengindeks ADLS Gen2 untuk menyerap metadata izin dan memfilter hasil pencarian berdasarkan hak akses pengguna (pratinjau)

Azure Data Lake Storage (ADLS) Gen2 mendukung akses per pengguna ke direktori dan file melalui daftar kontrol akses (ACL) dan kontrol akses berbasis peran (Azure RBAC). kontrol akses berbasis Attribute (Azure ABAC) tidak didukung.

Pencarian Azure AI dapat menyertakan metadata izin ini (pratinjau) bersama konten dokumen dengan menggunakan REST API pratinjau. Pengguna yang tidak memiliki akses ke direktori atau file di penyimpanan tidak melihat dokumen yang sesuai dalam hasil pencarian. Ini adalah salah satu dari beberapa strategi untuk kontrol akses tingkat dokumen di Pencarian Azure AI.

Artikel ini menjelaskan cara mengonfigurasi pengindeks ADLS Gen2 atau sumber pengetahuan blob ADLS Gen2 untuk secara otomatis menarik metadata izin ke dalam indeks pencarian. Ini melengkapi data Indeks dari ADLS Gen2 dan Membuat sumber pengetahuan blob untuk ADLS Gen2 dengan informasi khusus terkait penerimaan izin. Untuk mendorong metadata izin secara manual, lihat Mengindeks ACL dokumen menggunakan API pendorongan.

diagram

Prasyarat

• Microsoft Entra ID autentikasi dan otorisasi. Layanan dan aplikasi harus berada di penyewa yang sama. Pengguna dapat berada di penyewa yang berbeda selama semua penyewa menggunakan Microsoft Entra ID. Penetapan peran digunakan untuk setiap koneksi yang diautentikasi.

• Pencarian Azure AI pada level berbayar (Dasar atau lebih tinggi) di wilayah mana pun. Layanan pencarian harus mengaktifkan akses berbasis peran dan identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna.

• Blob ADLS Gen2 dalam namespace hierarkis, dengan hak akses pengguna yang diberikan melalui ACL atau peran.

• REST API versi 2025-05-01-preview atau yang lebih baru untuk penyerapan izin pengindeks. REST API versi 2025-11-01-preview atau yang lebih baru untuk dukungan sumber pengetahuan. Gunakan REST API pratinjau terbaru atau paket SDK pratinjau yang mendukung filter izin.

Keterbatasan

• Portal Azure tidak mendukung fitur ini.

• Batas ADLS Gen2 pada penetapan peran dan entri ACL berlaku.

• Kategori identitas ACL owning users, owning groups, dan Other (all) tidak didukung selama pratinjau. Gunakan penugasan named users dan named groups sebagai pengganti.

• Fitur pengindeks berikut tidak mendukung pewarisan izin dalam dokumen terindeks yang berasal dari ADLS Gen2. 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 atau cakupan RBAC.

  • Cache penyempurnaan pengindeks

  • Sesi debug

Dukungan untuk model izin

Bagian ini membandingkan fitur kontrol akses tingkat dokumen antara ADLS Gen2 dan Pencarian Azure AI. Ini menjelaskan mekanisme kontrol akses Azure Data Lake Storage (ADLS) Gen2 mana yang didukung atau dipetakan oleh AI Search. Ini membantu Anda memahami bagaimana izin diberlakukan di tingkat dokumen.

Pada waktu kueri, Pencarian Azure AI mengevaluasi RBAC tingkat kontainer terlebih dahulu lalu memeriksa entri ACL tingkat dokumen. Akses diberikan jika ada mekanisme yang mengizinkannya.

Tentang izin hierarkis ACL

Pengindeks dan sumber pengetahuan dapat mengambil penugasan ACL dari kontainer yang ditentukan dan semua direktori yang mengarah ke setiap file dengan mengikuti alur evaluasi akses hierarki ADLS Gen2. Daftar akses efektif akhir untuk setiap file dihitung dan berbagai kategori akses diindeks ke dalam bidang indeks yang sesuai.

Misalnya, dalam skenario umum ADLS Gen2 yang berkaitan dengan izin seperti pada jalur berkas /Oregon/Portland/Data.txt.

Pengindeks atau sumber pengetahuan mengumpulkan ACL dari setiap kontainer dan direktori. Kemudian menentukan akses efektif pada tingkat yang lebih rendah dan berlanjut hingga menyelesaikan izin untuk setiap file.

/ assigned access vs Oregon/ assigned access
  => Oregon/ effective access vs Portland/ assigned access
    => Portland/ effective access vs Data.txt assigned access
      => Data.txt effective access

Mengonfigurasi ADLS Gen2

Pengindeks atau sumber pengetahuan dapat mengambil ACL di akun penyimpanan jika kriteria berikut terpenuhi. Untuk informasi selengkapnya tentang penetapan ACL, lihat Penetapan ACL ADLS Gen2.

Otorisasi

Identitas layanan pencarian Anda harus memiliki izin Storage Blob Data Reader untuk pengindeksan.

Jika Anda menguji secara lokal, Anda juga harus memiliki penugasan peran Pembaca Data Blob Penyimpanan. Untuk informasi selengkapnya, lihat Hubungkan ke Azure Storage menggunakan identitas terkelola.

Izin kontainer akar:

1. Tetapkan semua Group dan User set (prinsip keamanan) di kontainer akar / dengan izin Read dan Execute.

2. Pastikan bahwa Read dan Execute keduanya ditambahkan sebagai "izin default" sehingga diterapkan ke file dan direktori yang baru dibuat secara otomatis.

Menerapkan izin ke seluruh hierarki file.

Meskipun direktori dan file baru mewarisi izin, direktori dan file yang ada tidak secara otomatis mewarisi penetapan ini.

Gunakan alat ADLS Gen2 untuk menerapkan ACL secara rekursif untuk penyebaran tugas pada konten yang ada. Alat ini menyebarluaskan penetapan ACL kontainer akar ke semua direktori dan file yang mendasar.

Menghapus izin berlebih

Setelah menerapkan ACL secara rekursif, tinjau izin untuk setiap direktori dan file.

Hapus salah satu Group atau User set yang seharusnya tidak memiliki akses ke direktori atau file tertentu. Misalnya, hapus User2 pada folder Portland/, dan untuk folder Idaho hapus Group2 dan User2 dari penugasannya, dan sebagainya.

Contoh Struktur Penugasan ACL

Berikut adalah diagram struktur penugasan ACL untuk hierarki direktori fiktif dalam dokumentasi ADLS Gen2.

Memperbarui penugasan ACL dari waktu ke waktu

Seiring waktu, karena setiap penugasan ACL baru ditambahkan atau dimodifikasi, ulangi langkah-langkah sebelumnya untuk memastikan penyebaran dan perataan izin yang tepat. Izin yang diperbarui di ADLS Gen2 diperbarui dalam indeks pencarian saat Anda menyerap ulang konten menggunakan pengindeks atau sumber pengetahuan.

Mengonfigurasi Pencarian Azure AI

Ingat bahwa layanan pencarian harus memiliki:

• Akses berbasis peran diaktifkan
• Identitas yang dikelola sudah dikonfigurasi

Otorisasi

Untuk pengindeksan, klien yang mengeluarkan panggilan API harus memiliki izin Kontributor Layanan Pencarian untuk membuat objek, izin Kontributor Data Indeks Pencarian untuk melakukan impor data, dan Pembaca Data Indeks Pencarian untuk mengkueri indeks.

Jika Anda menguji secara lokal, Anda harus memiliki tugas peran yang sama. Untuk informasi selengkapnya, lihat Hubungkan ke Pencarian Azure AI menggunakan peran.

Mengonfigurasi sumber pengetahuan

Jika Anda menggunakan sumber pengetahuan, definisi dalam sumber pengetahuan digunakan untuk menghasilkan alur pengindeksan penuh (pengindeks, sumber data, dan indeks). Penugasan ACL terdeteksi dan secara otomatis disertakan dalam indeks yang dihasilkan. Tidak perlu mengubah salah satu objek yang dihasilkan jika Anda menginginkan pewarisan izin dalam konten terindeks Anda.

Poin-poin penting tentang konfigurasi yang membuatnya berfungsi untuk skenario ini:

• isADLSGen2 diatur ke true, memenuhi persyaratan sumber data untuk skenario ini.
• ingestionPermissionOptions menentukan ID pengguna dan grup.

# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2026-08-01-preview
api-key: {{key}}
Content-Type: application/json
 
{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source",
    "azureBlobParameters": {
        "connectionString": "{{blob-connection-string}}",
        "containerName": "blobcontainer",
        "folderPath": null,
        "isADLSGen2": true,
        "ingestionParameters": {
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": true,
            "ingestionSchedule": null,
             "ingestionPermissionOptions": [
                "userIds","groupIds"
                           ],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}
###

Mengonfigurasi pengindeksan berbasis pengindeks

Jika Anda menggunakan indexer, konfigurasikan indexer tersebut, sumber data tersebut, dan indeks untuk mengambil metadata izin dari blob ADLS Gen2.

Membuat sumber data

Bagian ini melengkapi data Indeks dari ADLS Gen2 dengan informasi yang khusus untuk memasukkan izin beserta konten dokumen ke dalam indeks Pencarian Azure AI.

• Jenis Sumber Data harus adlsgen2.

• Sumber data harus memiliki indexerPermissionOptions dengan userIds, groupIds, dan/atau rbacScope.

  • Untuk rbacScope, konfigurasikan string koneksi dengan format identitas terkelola.

  • Untuk string koneksi yang menggunakan identitas terkelola yang ditetapkan pengguna, Anda juga harus menentukan properti identity.

Contoh JSON dengan identitas terkelola sistem:

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    }
}

Contoh skema JSON dengan identitas yang dikelola pengguna di string koneksi:

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    },
    "identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
    }
}

Membuat bidang izin dalam indeks

Di Pencarian Azure AI, pastikan indeks Anda berisi definisi bidang untuk metadata izin. Metadata izin dapat diindeks ketika indexerPermissionOptions ditentukan dalam definisi sumber data.

Atribut skema yang direkomendasikan untuk ACL (UserId, GroupIds) dan Cakupan RBAC:

• Kolom pengidentifikasi pengguna (ID) dengan nilai userIds permissionFilter.
• Bidang ID Grup dengan groupIds nilai permissionFilter.
• Bidang cakupan RBAC dengan nilai rbacScope permissionFilter.
• Properti permissionFilterOption untuk mengaktifkan pemfilteran selama proses kueri.
• Menggunakan bidang string untuk metadata izin
• Atur filterable ke true pada semua bidang.

Perhatikan bahwa retrievable salah. Anda dapat mengaturnya ke true selama pengembangan untuk memverifikasi izin tersedia, tetapi ingatlah untuk mengaturnya kembali ke false sebelum menyebarkan ke lingkungan produksi.

Contoh skema JSON:

{
  ...
  "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": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

Mengonfigurasi pengindeksan

Pemetaan bidang dalam pengindeks mengatur jalur data ke bidang dalam indeks. Bidang target dan tujuan yang bervariasi menurut nama atau jenis data memerlukan pemetaan bidang eksplisit. Bidang metadata berikut di ADLS Gen2 mungkin memerlukan pemetaan bidang jika Anda memvariasi nama bidang:

• metadata_user_ids (Collection(Edm.String)) - daftar ID pengguna ACL.
• metadata_group_ids (Collection(Edm.String)) - daftar ID grup ACL.
• metadata_rbac_scope (Edm.String) - cakupan RBAC untuk kontainer.

Tentukan fieldMappings di pengindeks untuk merutekan metadata izin ke bidang target selama pengindeksan.

Contoh skema JSON:

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

Rekomendasi dan praktik terbaik

• Rencanakan struktur folder ADLS Gen2 dengan hati-hati sebelum membuat folder apa pun.

• Atur identitas ke dalam grup dan gunakan grup jika memungkinkan, daripada memberikan akses langsung ke pengguna individual. Terus menambahkan pengguna individual alih-alih menerapkan grup meningkatkan jumlah entri kontrol akses yang harus dilacak dan dievaluasi. Tidak mengikuti praktik terbaik ini dapat menyebabkan pembaruan metadata keamanan yang lebih sering diperlukan untuk indeks saat metadata ini berubah, menyebabkan peningkatan penundaan dan inefisiensi dalam proses refresh.

Menyinkronkan izin antara konten terindeks dan sumber

Mengaktifkan pengayaan ACL atau RBAC pada pengindeks hanya berfungsi secara otomatis dalam dua situasi:

• Eksekusi pengindeksan penuh atau perayapan data yang pertama kali: diambil semua metadata izin yang ada pada saat itu untuk setiap dokumen.

• Dokumen baru yang ditambahkan setelah dukungan ACL/RBAC diaktifkan: informasi ACL/RBAC mereka diserap bersama dengan kontennya.

Jika Anda mengubah izin dokumen, seperti menambahkan pengguna ke ACL atau memperbarui penetapan peran, perubahan tidak muncul di indeks pencarian kecuali Anda memberi tahu pengindeks untuk merayapi metadata izin dokumen lagi.

Pilih salah satu mekanisme berikut, tergantung pada berapa banyak item yang berubah:

Contoh (pratinjau) API Resetdocs:

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

Contoh API sinkronisasi ulang (pratinjau):

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

Pelacakan penghapusan

Untuk mengelola penghapusan blob secara efektif, pastikan pelacakan penghapusan diaktifkan sebelum pengindeks Anda berjalan untuk pertama kalinya. Fitur ini memungkinkan sistem mendeteksi blob yang dihapus di sumber Anda dan menghapusnya dari indeks.

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