Tutorial: Mengindeks metadata izin dari ADLS Gen2 dan membuat kueri dengan hasil yang difilter berdasarkan izin (pratinjau)

Tutorial ini menunjukkan penyerapan metadata izin Azure Data Lake Storage (ADLS) Gen2 (pratinjau), di mana pengindeks Pencarian Azure AI menambahkan daftar kontrol akses (ACL) dan cakupan kontrol akses berbasis peran (RBAC) ke indeks pencarian.

Ini juga menunjukkan kepada Anda cara menyusun kueri yang menghormati izin akses pengguna. Hasil kueri sukses menunjukkan transfer izin yang terjadi selama proses pengindeksan.

Untuk informasi selengkapnya tentang pengindeksan ACL, lihat Menggunakan pengindeks ADLS Gen2 untuk menyerap metadata izin.

Dalam tutorial ini, Anda mempelajari cara:

Gunakan klien REST untuk menyelesaikan tutorial ini dan REST API versi pratinjau terbaru. Saat ini, tidak ada dukungan untuk pengindeksan ACL di portal Azure.

Prasyarat

• Akun Azure dengan langganan aktif. Buat akun secara gratis.

• Microsoft Entra ID autentikasi dan otorisasi. Layanan dan aplikasi harus berada di penyewa yang sama. Penetapan peran digunakan untuk setiap koneksi yang diautentikasi. Pengguna dan grup harus berada di penyewa yang sama. Anda harus memiliki pengguna dan grup untuk bekerja sama. Membuat tenant dan entitas keamanan tidak termasuk dalam cakupan tutorial ini.

• ADLS Gen2 dengan namespace hierarkis.

• File dalam struktur folder hierarkis. Tutorial ini mengasumsikan demo ADLS Gen2 dari struktur folder untuk file /Oregon/Portland/Data.txt. Tutorial ini memandu Anda melalui penugasan ACL pada folder dan file sehingga Anda dapat menyelesaikan latihan dengan sukses.

• Pencarian Azure AI, wilayah mana pun. Tingkat dasar atau lebih tinggi diperlukan untuk dukungan identitas terkelola.

• Visual Studio Code dengan ekstensi Klien REST.

Menyiapkan data sampel

Unggah data sampel taman negara ke kontainer di ADLS Gen2. Nama kontainer harus "parks" dan harus berisi dua folder: "Oregon" dan "Washington".

Periksa konfigurasi layanan pencarian

Layanan pencarian Anda harus dikonfigurasi untuk autentikasi dan otorisasi Microsoft Entra ID. Tinjau daftar periksa ini untuk memastikan Anda siap.

• Mengaktifkan akses berbasis peran

• Mengonfigurasi identitas terkelola yang ditetapkan sistem.

Mendapatkan token identitas pribadi untuk pengujian lokal

Tutorial ini mengasumsikan klien REST pada sistem lokal, terhubung ke Azure melalui koneksi internet publik.

Ikuti langkah-langkah ini untuk memperoleh token identitas pribadi dan menyiapkan Visual Studio Code untuk koneksi lokal ke sumber daya Azure Anda.

Mengatur izin di ADLS Gen2

Sebagai praktik terbaik, gunakan Group set daripada secara langsung menetapkan User set.

1. Berikan akses baca identitas layanan pencarian ke kontainer. Pengindeks tersambung ke Azure Storage di bawah identitas layanan pencarian. Layanan pencarian harus memiliki izin Pembaca Data Blob pada Penyimpanan untuk mengambil data.

2. Berikan izin per grup atau pengguna dalam hierarki file. Dalam hierarki file, identifikasi semua Group dan User set yang ditetapkan ke kontainer, direktori, dan file.

3. Anda dapat menggunakan portal Azure untuk mengelola ACL. Di Browser Penyimpanan, pilih direktori Oregon lalu pilih Kelola ACL dari menu konteks.

4. Tambahkan prinsip keamanan baru untuk pengguna dan grup.

5. Hapus prinsipal yang ada untuk grup pemilik, pengguna pemilik, dan lainnya. Prinsipal ini tidak didukung untuk pengindeksan ACL selama pratinjau.

Membuat indeks pencarian untuk metadata izin

Buat indeks yang berisi bidang untuk konten dan metadata izin.

Pastikan untuk menggunakan pratinjau REST API terbaru atau paket Azure SDK pratinjau yang menyediakan fungsionalitas yang setara. Properti filter izin hanya tersedia di API pratinjau tersebut.

Untuk tujuan demo, bidang izin telah retrievable diaktifkan sehingga Anda dapat memeriksa nilai dari indeks. Di lingkungan produksi, Anda harus menonaktifkan retrievable untuk menghindari kebocoran informasi sensitif.

{
  "name" : "my-adlsgen2-acl-index",
  "fields": [
    {
      "name": "name", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "description", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true    
    },
    {
      "name": "location", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "state", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "AzureSearch_DocumentKey", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true, "stored": true,
      "key": true
    },
    { 
      "name": "UserIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "userIds", 
      "searchable": true, "filterable": false, "retrievable": true
    },
    { 
      "name": "GroupIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "groupIds", 
      "searchable": true, "filterable": false, "retrievable": true
    },
    { 
      "name": "RbacScope", "type": "Edm.String", 
      "permissionFilter": "rbacScope", 
      "searchable": true, "filterable": false, "retrievable": true
    }
  ],
  "permissionFilterOption": "enabled"
}

Membuat sumber data

Ubah konfigurasi sumber data untuk menentukan penyerapan izin pengindeks dan jenis metadata izin yang ingin Anda indeks.

Sumber data membutuhkan indexerPermissionOptions.

Dalam tutorial ini, gunakan identitas terkelola yang ditetapkan sistem untuk koneksi yang diautentikasi.

{
    "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": "parks",
    "query": null
    }
}

Membuat dan menjalankan pengindeks

Konfigurasi pengindeks fieldMappings untuk pengolahan izin terutama tentang menentukan metadata izin.

{
  "name" : "my-adlsgen2-acl-indexer",
  "dataSourceName" : "my-adlsgen2-acl-datasource",
  "targetIndexName" : "my-adlsgen2-acl-index",
  "parameters": {
    "batchSize": null,
    "maxFailedItems": 0,
    "maxFailedItemsPerBatch": 0,
    "configuration": {
      "dataToExtract": "contentAndMetadata",
      "parsingMode": "delimitedText",
      "firstLineContainsHeaders": true,
      "delimitedTextDelimiter": ",",
      "delimitedTextHeaders": ""
      },
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
    ]
  }
}

Setelah pembuatan pengindeks dan segera dijalankan, konten file bersama dengan informasi metadata izin diindeks ke dalam indeks.

Menjalankan kueri untuk memeriksa hasil

Setelah dokumen dimuat, Anda dapat mengeluarkan kueri terhadapnya dengan menggunakan Dokumen - Pos Pencarian (REST).

URI diperluas untuk menyertakan input kueri, yang ditentukan dengan menggunakan /docs/search operator. Token kueri diteruskan di header permintaan. Untuk informasi lebih lanjut, lihat Penerapan ACL dan RBAC saat kueri.

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{search-token}}
x-ms-query-source-authorization: {{search-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,location,GroupIds",
    "orderby": "name asc"
}

Konten terkait

• https://github.com/Azure-Samples/azure-search-rest-samples/tree/main/acl