Gunakan pengindeks blob atau sumber pengetahuan untuk mengimpor metadata cakupan RBAC (pratinjau)

Azure Storage memungkinkan akses berbasis peran pada kontainer dalam penyimpanan blob, di mana peran seperti Storage Blob Data Reader atau Storage Blob Data Contributor menentukan apakah seseorang memiliki akses ke konten. Pencarian Azure AI mendukung penyerapan izin pengguna (pratinjau) bersama penyerapan dokumen sehingga Anda dapat menggunakan izin tersebut untuk mengontrol akses ke hasil pencarian. Jika pengguna tidak memiliki izin pada direktori atau file tertentu di Azure Storage, pengguna tersebut tidak memiliki akses ke dokumen terkait dalam hasil pencarian Azure AI, bahkan jika Anda secara pribadi memiliki Pembaca Data Indeks Pencarian penugasan pada indeks.

• 2025-05-01-preview dan yang lebih baru, metadata cakupan RBAC dapat diserap menggunakan pengindeks Blob.
• 2025-11-01-preview dan versi yang lebih baru menyediakan dukungan yang setara untuk sumber pengetahuan Blob di Azure Storage.

Cakupan RBAC diatur pada tingkat kontainer dan diterapkan ke semua blob (dokumen) melalui pewarisan izin. Cakupan RBAC diambil selama pengindeksan sebagai metadata izin. Anda dapat menggunakan API pendorongan untuk mengunggah dan mengindeks konten dan metadata izin secara manual (lihat Izin Pengindeksan menggunakan REST API pendorongan), atau Anda dapat menggunakan pengindeks atau sumber pengetahuan untuk mengotomatiskan penyerapan data. Artikel ini berfokus pada otomatisasi pengindeksan.

Pada waktu kueri, identitas pemanggil disertakan dalam header permintaan melalui x-ms-query-source-authorization parameter . Identitas harus cocok dengan metadata izin pada dokumen jika pengguna ingin melihat hasil pencarian.

Artikel ini berfokus pada pendekatan otomatisasi pengindeksan, dibangun di atas fondasi ini:

• Azure Storage blob diamankan menggunakan kontrol akses berbasis peran (Azure RBAC). Tidak ada dukungan untuk kontrol akses berbasis Atribut (Azure ABAC).

• Pengindeks Blob Azure atau Sumber Pengetahuan Blob yang mengambil dan menyerap data dan metadata, termasuk filter izin. Untuk mendapatkan dukungan filter izin, gunakan REST API pratinjau terbaru atau paket pratinjau Azure SDK yang mendukung fitur tersebut.

• Sebuah indeks di Pencarian Azure AI yang berisi dokumen yang diunggah dan izin yang sesuai. Metadata izin disimpan sebagai bidang dalam indeks.

• Kueri yang menggunakan filter izin. Untuk menyiapkan kueri yang mematuhi filter izin, gunakan pratinjau terbaru REST API atau sebuah paket pratinjau Azure SDK yang mendukung fitur tersebut.

Prasyarat

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

• Pencarian Azure AI, wilayah mana pun, tetapi Anda harus memiliki tingkat berbayar (level dasar ke atas) untuk dukungan identitas terkelola. Layanan pencarian harus dikonfigurasi untuk akses berbasis peran dan harus memiliki identitas terkelola (baik sistem atau pengguna).

• Azure Storage, Kinerja Standar (untuk tujuan umum v2), pada tingkat akses panas, sejuk, dan dingin, dengan kontainer atau blob yang diamankan oleh RBAC.

• Anda harus memahami cara kerja pengindeks dan sumber pengetahuan serta cara membuat indeks. Artikel ini menjelaskan pengaturan konfigurasi untuk sumber data dan pengindeks, tetapi tidak menyediakan langkah-langkah untuk membuat indeks. Untuk informasi selengkapnya tentang indeks yang dirancang untuk filter izin, lihat Membuat indeks dengan bidang filter izin.

Keterbatasan

• Portal Azure tidak mendukung fitur ini.

• 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 pada tingkat dokumen tidak disertakan dalam konten yang diindeks.

  • Kemampuan API Web Kustom

  • Gudang Pengetahuan

  • Cache penyempurnaan pengindeks

  • Sesi pemecahan masalah debug

Konfigurasi Penyimpanan Blob

Verifikasi kontainer blob Anda menggunakan akses berbasis peran.

1. Masuk ke portal Azure dan temukan akun penyimpanan Anda.

2. Perluas kontainer dan pilih kontainer yang memiliki blob yang ingin Anda indeks.

3. Pilih Access Control (IAM) untuk memeriksa penetapan peran. Pengguna dan grup dengan Pembaca Data Blob Penyimpanan atau Kontributor Data Blob Penyimpanan memiliki akses ke dokumen pencarian dalam indeks setelah kontainer diindeks.

Otorisasi

Untuk eksekusi pengindeks, identitas layanan pencarian Anda harus memiliki izin Pembaca Data Blob Penyimpanan . Untuk informasi selengkapnya, lihat Hubungkan ke Azure Storage menggunakan identitas terkelola.

Mengonfigurasi Pencarian Azure AI

Ingat bahwa layanan pencarian harus memiliki:

• Akses berbasis peran diaktifkan
• Identitas yang dikelola sudah dikonfigurasi

Otorisasi

Untuk eksekusi pengindeks, klien yang mengeluarkan panggilan API harus memiliki izin Search Service Contributor untuk membuat objek, Kontributor Data IndeksSearch izin untuk melakukan impor data, dan Pembaca Data IndeksSearch untuk mengkueri indeks, 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). Cakupan RBAC 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 false, sehingga sumber datanya adalah Azure Blob Storage.
• ingestionPermissionOptions menentukan rbacScope.

# 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": false,
        "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": ["rbacScope"],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}

Referensi:Membuat atau Memperbarui Sumber Pengetahuan (REST API)

Mengonfigurasi pengindeksan berbasis pengindeks

Jika Anda menggunakan pengindeks, konfigurasikan pengindeks, sumber data, dan indeks untuk menarik metadata izin dari blob.

Membuat sumber data

• Jenis Sumber Data harus azureblob.

• Mode penguraian sumber data harus default.

• Sumber data harus memiliki indexerPermissionOptions dengan 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 dan indexerPermissionOptions:

{
    "name" : "my-blob-datasource",
    "type": "azureblob",
    "indexerPermissionOptions": ["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-query-used-for-selecting-specific-blobs>"
    }
}

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

{
    "name" : "my-blob-datasource",
    "type": "azureblob",
    "indexerPermissionOptions": ["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-query-used-for-selecting-specific-blobs>"
    },
    "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 disarankan Ruang Lingkup RBAC:

• 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 benar selama pengembangan untuk memverifikasi bahwa izin ada, tetapi ingatlah untuk mengatur kembali ke false sebelum menyebarkan ke lingkungan produksi sehingga identitas utama keamanan tidak terlihat dalam hasil.

Contoh skema JSON:

{
  ...
  "fields": [
    ...
    { 
        "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 Azure Blob Storage mungkin memerlukan pemetaan bidang jika Anda memvariasi nama bidang:

• 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_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Menjalankan pengindeks

Setelah pengindeks, sumber data, dan indeks Anda dikonfigurasi, jalankan pengindeks untuk mengatur proses bergerak. Jika ada masalah dengan konfigurasi atau izin, masalah tersebut muncul dalam langkah ini.

Secara default, pengindeks berjalan segera setelah Anda mempostingnya ke layanan pencarian, tetapi jika konfigurasi pengindeks termasuk disabled diatur ke true, pengindeks diposting dalam status dinonaktifkan sehingga Anda dapat menjalankan pengindeks secara manual.

Sebaiknya menerapkan pengindeks dari portal Azure sehingga Anda dapat memantau status dan pesan.

Dengan asumsi tidak ada kesalahan, indeks sekarang diisi dan Anda dapat bergerak maju dengan kueri dan pengujian.

Pelacakan penghapusan

Untuk mengelola penghapusan blob secara efektif, pastikan Anda telah mengaktifkan pelacakan penghapusan sebelum pengindeks Anda berjalan untuk pertama kalinya. Fitur ini memungkinkan sistem mendeteksi blob yang dihapus dari sumber Anda dan menghapus konten yang sesuai dari indeks.

Lihat juga

• Hubungkan ke Pencarian Azure AI menggunakan peran

• Penerapan ACL dan RBAC pada saat kueri
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API

• Pencarian di konten Azure Blob Storage
• Mengonfigurasi pengindeks blob