Azure Yapay Zeka Arama'te sonuçları kırpmaya yönelik güvenlik filtreleri

yerleşik erişim denetimi listesi (ACL) desteğini belge düzeyinde yetkilendirme için kullanamayan arama çözümleri için Azure Yapay Zeka Arama, grup veya kullanıcı kimliği içeren bir dizeye göre arama sonuçlarını filtreleyen bir filtre oluşturmayı destekler.

Bu makalede, aşağıdaki adımları içeren bir güvenlik filtreleme düzeni açıklanmaktadır:

Demolara ve uygulamalı öğrenme sağlayan örneklere bağlantılarla sona erer. Düzeni anlamak için önce bu makaleyi gözden geçirmenizi öneririz.

Güvenlik filtresi düzeni hakkında

Güvenlik filtresi deseni, bir güvenlik ilkesinden oluşan bir dizge temelinde bir arama sonucunu içerecek veya dışlayacak şekilde normal bir OData filtresi kullanarak belge düzeyinde yetkilendirmeyi simüle eder. Güvenlik sorumlusu aracılığıyla kimlik doğrulaması veya yetkilendirme yoktur. "Principal, arama sonuçlarına bir belgeyi dahil etmek veya çıkarmak için filtre ifadesinde kullanılan bir yazı dizisidir."

Güvenlik filtrelemesi yapmanın çeşitli yolları vardır. Bunun bir yolu, eşitlik ifadelerinin karmaşık bir şekilde ayrıştırılmasıdır: örneğin, Id eq 'id1' or Id eq 'id2'vb. Bu yaklaşım hataya açıktır, bakımı zordur ve listenin yüzlerce veya binlerce değer içerdiği durumlarda sorgu yanıt süresini birkaç saniye yavaşlatır.

Daha iyi bir çözüm, bu makalede açıklandığı gibi güvenlik filtreleri için işlevini kullanmaktır search.in . Eşitlik ifadesi yerine kullanırsanız search.in(Id, 'id1, id2, ...') , altsaniye yanıt süreleri bekleyebilirsiniz.

Önkoşullar

• Microsoft Entra nesne tanımlayıcısı gibi bir grup veya kullanıcı kimliği içeren dize alanı.

• Aynı belgedeki diğer alanlar, bu grup veya kullanıcı tarafından erişilebilen içeriği sağlamalıdır. Aşağıdaki JSON belgelerinde "security_id" alanları güvenlik filtresinde kullanılan kimlikleri içerir ve arayanın kimliği belgenin "security_id" ile eşleşiyorsa ad, maaş ve evlilik durumu dahil edilir.

  {  
      "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"
      } 
  }  
  

Güvenlik alanı oluşturma

Arama dizininde, alanlar koleksiyonunda, önceki örnekteki kurgusal "security_id" alanına benzer şekilde grup veya kullanıcı kimliğini içeren bir alana ihtiyacınız vardır.

1. Güvenlik alanını olarak Collection(Edm.String)ekleyin.

2. Alanın filterable özniteliğini true olarak ayarlayın.

3. Arama yanıtının bir parçası olarak döndürülmeyecek şekilde alanın retrievable özniteliğini false olarak ayarlayın.

4. Dizinler bir belge anahtarı gerektirir. "file_id" alanı bu gereksinimi karşılar.

5. Dizinler de aranabilir ve alınabilir içerik içermelidir. "file_name" ve "file_description" alanları bu örnekte bunu temsil eder.

   Aşağıdaki dizin şeması alan gereksinimlerini karşılar. Azure Yapay Zeka Arama’te dizine eklediğiniz belgeler, group_ids dahil bu alanların tümü için değerlere sahip olmalıdır. Güvenlik filtresi file_name veya secured_file_b içerdiğinde, bir sorgu group_id2group_id1 içeren belgeyi döndürür.

   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 }
        ]
    }
   

REST API kullanarak dizininize veri gönderme

Arama dizininizi, güvenlik alanının değerleri de dahil olmak üzere alanlar koleksiyonundaki her alan için değer sağlayan belgelerle doldurun. Azure Yapay Zeka Arama, güvenlik alanını özellikle doldurmaya yönelik API'ler veya özellikler sağlamaz. Ancak, bu makalenin sonunda listelenen örneklerden bazıları bu alanı doldurma tekniklerini açıklar.

Azure Yapay Zeka Arama'te veri yükleme yaklaşımları şunlardır:

• Tüm alanlarla doldurulmuş belgeleri içeri aktaran tek bir gönderme veya çekme (dizin oluşturucu) işlemi
• Birden çok gönderme veya çekme işlemi. İkincil içeri aktarma işlemleri doğru belge tanımlayıcısını hedeflediği sürece, alanları birden çok içeri aktarma işlemi aracılığıyla tek tek yükleyebilirsiniz.

Aşağıdaki örnekte, dizininizin URL uç noktasının docs koleksiyonuna yönelik tek bir HTTP POST isteği gösterilmektedir (bkz . Belgeler - Dizin). HTTP isteğinin gövdesi, dizine eklenecek belgelerin JSON işlemesidir:

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"]
        }
    ]
}

Var olan bir belgeyi grup listesiyle güncellemeniz gerekiyorsa, merge veya mergeOrUpload eylemini kullanabilirsiniz.

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

Sorguya güvenlik filtresi uygulama

Belgeleri erişime göre group_ids kırpmak için filtre içeren bir group_ids/any(g:search.in(g, 'group_id1, group_id2,...')) arama sorgusu vermelisiniz; burada "group_id1, group_id2,..." arama isteği verenin ait olduğu gruplardır.

Bu filtre, group_ids alanının verilen tanımlayıcılardan birini içerdiği tüm belgelerle eşleşir. Azure Yapay Zeka Arama kullanarak belge aramayla ilgili tüm ayrıntılar için Belgeleri Ara'yı okuyabilirsiniz.

Bu örnek, POST isteği kullanarak sorguyu ayarlamayı gösterir.

İstek gövdesinde filtreyi belirterek HTTP POST isteğini gönderin:

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'))"  
}

Belgeleri group_ids etiketi "group_id1" veya "group_id2" içerdiğinde geri almanız gerekir. Başka bir deyişle, istek verenin okuma erişimine sahip olduğu belgeleri alırsınız.

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

Sonraki adımlar

Bu makalede, kullanıcı kimliğine ve işleve göre sonuçları filtrelemek için bir desen açıklanmaktadır search.in() . Bu işlevi, istekte bulunan kullanıcının temel tanımlayıcılarını hedef belgelerin her biriyle ilişkilendirilmiş temel tanımlayıcılarla eşleştirmek amacıyla kullanabilirsiniz. Bir arama isteği işlendiğinde, search.in işlevi kullanıcının ana unsurlarından hiçbirinin okuma izni olmayan arama sonuçlarını filtreler. Asıl tanımlayıcılar güvenlik grupları, roller ve hatta kullanıcının kendi kimliği gibi öğeleri temsil edebilir.

Daha fazla örnek, tanıtım ve video için:

• Python'da sohbet belgesi güvenliğini kullanmaya başlama
• İsteğe bağlı oturum açma ve belge düzeyi erişim denetimini ayarlama (AzureOpenAIDemo uygulamasında yapılan değişiklikler)
• Video: Microsoft Entra ile Akıllı Uygulamalarınızın Güvenliğini Sağlama