Filter keamanan untuk memangkas hasil di Pencarian Azure AI

Untuk solusi pencarian yang tidak dapat menggunakan dukungan daftar kontrol akses bawaan (ACL) untuk otorisasi tingkat dokumen, Pencarian Azure AI mendukung pembuatan filter yang memangkas hasil pencarian berdasarkan string yang berisi grup atau identitas pengguna.

Artikel ini menjelaskan pola untuk pemfilteran keamanan yang memiliki langkah-langkah berikut:

Ini menyimpulkan dengan tautan ke demo dan contoh yang menyediakan pembelajaran langsung. Sebaiknya tinjau artikel ini terlebih dahulu untuk memahami polanya.

Tentang pola filter keamanan

Pola filter keamanan mensimulasikan otorisasi tingkat dokumen dengan menggunakan filter OData reguler yang menyertakan atau mengecualikan hasil pencarian berdasarkan string yang terdiri dari prinsip keamanan. Tidak ada autentikasi atau otorisasi melalui prinsipal keamanan. Prinsipal hanyalah string, yang digunakan dalam ekspresi filter, untuk menyertakan atau mengecualikan dokumen dari hasil pencarian.

Ada beberapa cara untuk mencapai pemfilteran keamanan. Salah satu caranya adalah melalui pembedaan rumit dari ekspresi kesetaraan: misalnya, Id eq 'id1' or Id eq 'id2', dan sebagainya. Pendekatan ini rentan terhadap kesalahan, sulit dipertahankan, dan dalam kasus di mana daftar berisi ratusan atau ribuan nilai, memperlambat waktu respons kueri dalam beberapa detik.

Solusi yang lebih baik adalah menggunakan fungsi search.in untuk filter keamanan, seperti yang dijelaskan dalam artikel ini. Jika Anda menggunakan search.in(Id, 'id1, id2, ...') alih-alih ekspresi kesetaraan, Anda dapat mengharapkan waktu respons sub-detik.

Prasyarat

• Bidang string yang berisi grup atau identitas pengguna, seperti pengidentifikasi objek Microsoft Entra.

• Bidang lain dalam dokumen yang sama harus menyediakan konten yang dapat diakses oleh grup atau pengguna tersebut. Dalam dokumen JSON berikut, bidang "security_id" berisi identitas yang digunakan dalam filter keamanan, dan nama, gaji, dan status perkawinan disertakan jika identitas pemanggil cocok dengan "security_id" dokumen.

  {  
      "Employee-1": {  
          "employee_id": "100-1000-10-1-10000-1",
          "name": "Abram",   
          "salary": 75000,   
          "married": true,
          "security_id": "alphanumeric-object-id-for-employee-1"
      },
      "Employee-2": {  
          "employee_id": "200-2000-20-2-20000-2",
          "name": "Adams",   
          "salary": 75000,   
          "married": true,
          "security_id": "alphanumeric-object-id-for-employee-2"
      } 
  }  
  

Membuat bidang keamanan

Dalam indeks pencarian, dalam kumpulan bidang, Anda memerlukan satu bidang yang berisi grup atau identitas pengguna, mirip dengan bidang "security_id" fiktif dalam contoh sebelumnya.

1. Tambahkan bidang keamanan sebagai Collection(Edm.String).

2. Atur atribut bidang filterable ke true.

3. Atur atribut bidang retrievable ke false sehingga tidak dikembalikan sebagai bagian dari respons pencarian.

4. Indeks memerlukan kunci dokumen. Bidang "file_id" memenuhi persyaratan tersebut.

5. Indeks juga harus berisi konten yang dapat dicari dan dapat diambil. Bidang "file_name" dan "file_description" mewakilinya dalam contoh ini.

   Skema indeks berikut memenuhi persyaratan bidang. Dokumen yang Anda indeks di Pencarian Azure AI harus memiliki nilai untuk semua bidang ini, termasuk group_ids. Kueri mengembalikan dokumen dengan file_namesecured_file_b saat filter keamanannya menyertakan group_id1 atau group_id2.

   POST https://[search service].search.windows.net/indexes/securedfiles/docs/index?api-version=2026-04-01
   {
        "name": "securedfiles",  
        "fields": [
            {"name": "file_id", "type": "Edm.String", "key": true, "searchable": false },
            {"name": "file_name", "type": "Edm.String", "searchable": true },
            {"name": "file_description", "type": "Edm.String", "searchable": true },
            {"name": "group_ids", "type": "Collection(Edm.String)", "filterable": true, "retrievable": false }
        ]
    }
   

Mendorong data ke indeks Anda menggunakan REST API

Isi indeks pencarian Anda dengan dokumen yang menyediakan nilai untuk setiap bidang dalam kumpulan bidang, termasuk nilai untuk bidang keamanan. Pencarian Azure AI tidak menyediakan API atau fitur untuk mengisi bidang keamanan secara khusus. Namun, beberapa contoh yang tercantum di akhir artikel ini menjelaskan teknik untuk mengisi bidang ini.

Di Pencarian Azure AI, pendekatan untuk memuat data adalah:

• Operasi pendorongan atau penarikan tunggal (pengindeks) yang mengimpor dokumen yang diisi dengan semua bidang
• Beberapa operasi pendorongan atau penarikan. Selama operasi impor sekunder menargetkan pengidentifikasi dokumen yang tepat, Anda dapat memuat setiap bidang secara terpisah melalui beberapa impor.

Contoh berikut menunjukkan satu permintaan HTTP POST ke kumpulan dokumen titik akhir URL indeks Anda (lihat Dokumen - Indeks). Isi permintaan HTTP adalah penyajian JSON dari dokumen yang akan diindeks:

POST https://[search service].search.windows.net/indexes/securedfiles/docs/index?api-version=2026-04-01
{
    "value": [
        {
            "@search.action": "upload",
            "file_id": "1",
            "file_name": "secured_file_a",
            "file_description": "File access is restricted to Human Resources.",
            "group_ids": ["group_id1"]
        },
        {
            "@search.action": "upload",
            "file_id": "2",
            "file_name": "secured_file_b",
            "file_description": "File access is restricted to Human Resources and Recruiting.",
            "group_ids": ["group_id1", "group_id2"]
        },
        {
            "@search.action": "upload",
            "file_id": "3",
            "file_name": "secured_file_c",
            "file_description": "File access is restricted to Operations and Logistics.",
            "group_ids": ["group_id5", "group_id6"]
        }
    ]
}

Jika Anda perlu memperbarui dokumen yang sudah ada dengan daftar grup, Anda bisa menggunakan merge atau mergeOrUpload tindakan:

{
    "value": [
        {
            "@search.action": "mergeOrUpload",
            "file_id": "3",
            "group_ids": ["group_id7", "group_id8", "group_id9"]
        }
    ]
}

Menerapkan filter keamanan dalam kueri

Untuk memangkas dokumen berdasarkan akses group_ids, Anda harus mengeluarkan kueri pencarian dengan filter group_ids/any(g:search.in(g, 'group_id1, group_id2,...')), di mana 'group_id1, group_id2,...' adalah grup tempat penerbit permintaan pencarian berada.

Filter ini cocok dengan semua dokumen group_ids yang bidangnya berisi salah satu pengidentifikasi yang diberikan. Untuk detail selengkapnya tentang mencari dokumen menggunakan Pencarian Azure AI, Anda dapat membaca Cari Dokumen.

Sampel ini memperlihatkan cara menyiapkan kueri menggunakan permintaan POST.

Terbitkan permintaan HTTP POST, menentukan filter dalam isi permintaan:

POST https://[service name].search.windows.net/indexes/securedfiles/docs/search?api-version=2026-04-01

{
   "filter":"group_ids/any(g:search.in(g, 'group_id1, group_id2'))"  
}

Anda sebaiknya mendapatkan dokumen kembali di mana group_ids berisi "group_id1" atau "group_id2". Dengan kata lain, Anda mendapatkan dokumen yang dapat diakses oleh penerbit permintaan.

{
 [
   {
    "@search.score":1.0,
     "file_id":"1",
     "file_name":"secured_file_a",
   },
   {
     "@search.score":1.0,
     "file_id":"2",
     "file_name":"secured_file_b"
   }
 ]
}

Langkah berikutnya

Artikel ini menjelaskan pola untuk memfilter hasil berdasarkan identitas pengguna dan search.in() fungsi. Anda dapat menggunakan fungsi ini untuk meneruskan pengidentifikasi utama agar pengguna yang meminta cocok dengan pengidentifikasi utama yang terkait dengan setiap dokumen target. Saat permintaan pencarian ditangani, fungsi search.in memfilter hasil pencarian yang tidak ada pengguna utama yang memiliki akses baca. Pengidentifikasi utama dapat mewakili hal-hal seperti grup keamanan, peran, atau bahkan identitas pengguna sendiri.

Untuk contoh, demo, dan video lainnya:

• Mulai menggunakan keamanan dokumen obrolan di Python
• Menyiapkan masuk opsional dan kontrol akses di tingkat dokumen (modifikasi pada aplikasi AzureOpenAIDemo)
• Video: Mengamankan Aplikasi Cerdas Anda dengan Microsoft Entra