Azure Yapay Zeka Arama'te sorgu sırasında ACL ve RBAC uygulanması (önizleme)

Sorgu zamanı erişim denetimi (önizleme), kullanıcıların kimliklerine, grup üyeliklerine, rollerine veya özniteliklerine göre yalnızca erişim yetkisine sahip oldukları arama sonuçlarını almasını sağlar. Bu işlevsellik, güvenli kurumsal arama ve uyumluluk odaklı iş akışları için gereklidir.

Yetkili erişim, dizin oluşturma sırasında alınan izin meta verilerine bağlıdır. Azure Data Lake Storage (ADLS) 2. Nesil ve Microsoft 365 SharePoint gibi yerleşik erişim modellerine sahip dizin oluşturucu veri kaynakları için, dizin oluşturucu her belge için izin meta verilerini otomatik olarak çekebilir. Diğer veri kaynakları için, belge yükünü kendiniz derlemeniz ve yük hem içeriği hem de ilişkili izin meta verilerini içermelidir. Ardından, dizini yüklemek için gönderme API'lerini kullanırsınız.

Bu makalede, sonuçları filtrelemek için izin meta verilerini kullanan sorguların nasıl ayarlanacağı açıklanmaktadır.

Önkoşullar

• İzin meta verileri filterable dize alanlarında yer almalıdır. Sorgularınızda filtreyi kullanmayacaksınız, ancak arama altyapısı yetkisiz içeriği dışlamak için dahili olarak bir filtre oluşturur.

• İzin meta verileri, erişim düzeyini ve grup veya kullanıcı kimliğini tanımlayan POSIX stili izinlerden ya da RBAC kapsamı kullanıyorsanız ADLS 2. Nesil'deki kapsayıcının kaynak kimliğinden oluşmalıdır.

• Özel alım ile ACL tabanlı uygulama için, userIds ve groupIds öğelerini filtrelenebilir alanlarda Microsoft Entra nesne kimlikleri (GUID'ler) olarak depolayın. Sorgu sırasında hizmet, x-ms-query-source-authorization içindeki kimlikleri saklanan kimliklerle eşleştirir. Şema ayrıntıları için bkz . Anında iletme REST API'lerini (önizleme) kullanarak belge erişim denetim listelerini (ACL' ler) dizinleme.

• Veri kaynağına bağlı olarak:

  • ADLS 2. Nesil veri kaynakları için, kapsayıcı düzeyinde erişim denetim listelerini (ACL) ve/veya rol tabanlı erişim denetimi (RBAC) rollerini Azure yapılandırmış olmanız gerekir.
  • Azure Blob veri kaynakları için kapsayıcıda rol atamalarınız olmalıdır. Yerleşik bir dizin oluşturucu, bilgi kaynağı veya dizininizdeki izin meta verilerini dizine almak için API'leri gönderebilirsiniz.
  • SharePoint veri kaynakları için erişim denetim listelerini (ACL' ler) yapılandırmanız gerekir. built-in SharePoint dizin oluşturucu kullanabilir ve ACL alma özellikleri ile yapılandırabilirsiniz. Ayrıca dizine alınan SharePoint bilgi kaynağını kullanabilir ve belge düzeyi izinlerini zorunlu kılabilir şekilde yapılandırabilirsiniz. Microsoft 365 Grupları da dahil olmak üzere grup tabanlı izinler, Entra nesne kimlikleri olarak içe aktarıldığında desteklenir. Grup genişletme, Microsoft Graph aracılığıyla sorgu zamanında gerçekleşir.

• Dizini veya bilgi kaynağını sorgulamak için en son önizleme REST API veya Azure SDK önizleme paketini kullanın. Bu API sürümü, yetkisiz sonuçları filtreleyen iç sorguları destekler.

Sınırlama

• ACL değerlendirmesi başarısız olursa (örneğin, Graph API kullanılamaz), hizmet 5xx döndürür ve not kısmen filtrelenmiş bir sonuç kümesi döndürür.

• ACL'nin güncelliği alım yöntemine bağlıdır. Eski yetkilendirme kararlarını önlemek için, her kaynağın izin değişikliklerini dizine nasıl yaymasını planlayın:

  • Zamanlanmış SharePoint dizin oluşturucu, her çalıştırmada öğe düzeyi izin değişikliklerini yeniler. Alt öğelerin devraldığı ana kapsamda (site, kitaplık, liste veya klasör) yapılan değişiklikler yeniden eşitleme gerektirir.
  • ADLS 2. Nesil dizin oluşturucu, ACL'leri yenilemek için yeniden eşitleme gerektirir.
  • Özel veya anında iletme alımı, etkilenen belgeleri yeniden oluşturmanızı gerektirir.

• Belge görünürlüğü için her ikisi de gerekir:

  • Çağıran uygulamanın RBAC rolü (Yetkilendirme üst bilgisi).
  • x-ms-query-source-authorization tarafından iletilen kullanıcı kimliği.

• İlk ACL tabanlı sorgular, önbelleğe alma ve izin çözümleme ek yükü nedeniyle sonraki isteklere kıyasla daha yüksek gecikme süresiyle karşılaşabilir.

• Dizinlenmiş SharePoint içeriğinde, bir SharePoint grubu içinde iç içe geçmiş bir Microsoft Entra grubu genişletilmez. Microsoft Entra geçişli grup çözümlemesi bu karma ilişkiyi desteklemez. Bkz . Desteklenen grup ilişkileri.

Veri kaynağı başına ACL giriş sınırları

Erişim denetimi listesi (ACL) giriş sınırları, bağlı bir veri kaynağındaki bir dosya, klasör veya öğeyle kaç ayrı izin kaydının ilişkilendirilebileceğini tanımlar. Her girdi tek bir kullanıcı veya grup kimliğini ve bu kimliğe verilen erişim haklarını (örneğin, Okuma, Yazma veya Yürütme) temsil eder.

Azure Yapay Zeka Arama işlevselliği tarafından desteklenen en fazla ACL girdisi sayısı, veri kaynağı türüne bağlı olarak değişir:

Azure Data Lake Storage 2. Nesil (ADLS 2. Nesil): Her dosya veya dizin en fazla 32 ACL giriş izinleri olabilir. Bu bağlamda bir giriş, belirli bir izin kümesine sahip tek bir sorumlu (kullanıcı veya grup) anlamına gelir. Örnek: "Herkes" okuma erişimi ve "Azure kullanıcıları" yürütme erişimi atamak iki ACL girdisi olarak sayılır.

Microsoft 365 SharePoint: Aramadaki SharePoint veri kaynağı, dosya başına en fazla 1.000 izin girdisini destekler. Her girdi, öğenin izin listesindeki benzersiz bir kullanıcı veya grup atamasını temsil eder. Bu, liste veya kitaplık başına toplam benzersiz izin kapsamları sınırından farklıdır ve bu sınır, benzersiz izinlere sahip olabilecek öğe sayısını yönetir.

Bu sınırlar, Azure Yapay Zeka Arama arama sonuçlarını dizine eklerken veya filtrelerken öğe düzeyi izinlerine ne kadar uygun olabileceğini belirler. Bir öğe bu ACL giriş sınırlarını aşarsa, sınırın ötesindeki izinler sorgu sırasında uygulanmayabilir.

Sorgu zamanı zorlama nasıl çalışır?

Bu bölümde sorgu zamanında ACL zorlama işlemlerinin sırası listelenir. İşlemler, Azure RBAC kapsamını mı yoksa Microsoft Entra ID grubunu mu yoksa kullanıcı kimliklerini mi kullandığınıza bağlı olarak değişir.

1. Kullanıcı izinleri girişi

Son kullanıcı uygulaması, arama sorgusu isteğinin bir parçası olarak bir sorgu erişim belirteci içerir ve bu erişim belirteci genellikle kullanıcının kimliğidir. Aşağıdaki tabloda, ACL zorlaması için Azure Yapay Zeka Arama tarafından desteklenen kullanıcı izinlerinin kaynağı listelenmektedir:

2. Güvenlik filtresi oluşturma

dahili olarak, Azure Yapay Zeka Arama güvenlik filtrelerini sağlanan kullanıcı izinlerine göre dinamik olarak oluşturur. Bu güvenlik filtreleri, dizinde izin filtresi seçeneği etkinse sorguyla birlikte gelen tüm filtrelere otomatik olarak eklenir.

Azure RBAC için izinler kaynak kimliği dizelerinin listeleridir. Veri kaynağında, yetkilendirme üst bilgisindeki güvenlik ilkesi belirtecine erişim izni veren bir Azure rol ataması (Depolama Blob Veri Okuyucusu) olmalıdır. İstekte erişim belirtecinin arkasındaki sorumlu için rol ataması yoksa, filtre belgeleri dışlar.

3. Sonuç filtreleme

Güvenlik filtresi, istekteki userId'leri, groupId'leri ve rbacScope'larını, arama dizinindeki her belgedeki ACL listeleriyle verimli bir şekilde eşleştirerek yalnızca kullanıcının erişebileceği sonuçların döndürülmesini sağlar. Her filtrenin bağımsız olarak uygulandığını ve herhangi bir filtre başarılı olursa belgenin yetkilendirilmiş olarak kabul edildiğini unutmayın. Örneğin, bir kullanıcının userId'ler aracılığıyla bir belgeye erişimi varsa ancak groupId'ler aracılığıyla erişmiyorsa, belge yine de geçerli kabul edilir ve kullanıcıya döndürülür.

Sorgu sırasında SharePoint grupları

Azure Yapay Zeka Arama, 2026-05-01-preview REST API sürümünden itibaren, sorgu sırasında Sahipler, Üyeler, Ziyaretçiler ve özel site grupları gibi SharePoint site grubu üyeliklerini dikkate alabilir. Bu senaryoyu etkinleştirmek için dizin şunları içermelidir:

• Kullanıcı adına SharePoint'i çağırmak için kullanılan Microsoft Entra uygulamasının federe kimlik kimlik bilgisine başvuran bir sharePointConnectorAppRegistration özelliği.
• Dizine alınan her öğe için SharePoint site URL'sini depolayan sharepointSiteUrl: true özniteliğiyle işaretlenmiş bir alan (genellikle SharePointSiteUrl olarak adlandırılır ve metadata_spo_site_url kaynak alanından doldurulur).

Sorgu sırasında Azure Yapay Zeka Arama, her aday belgede yer alan kayıtlı uygulamayı ve site URL’sini kullanarak çağrıyı yapan kullanıcının o sitedeki SharePoint grup üyeliklerini belirler. Çözümlenen gruplar, izin filtresi alanında depolanan spg: ön ekli değerlerle eşleştirilirgroupIds. spg: ön eki, SharePoint site gruplarını ön ek olmadan depolanan Microsoft Entra grup nesnesi kimliklerinden ayırır.

Yapılandırma ayrıntıları ve sınırlamaları için bkz. SharePoint grupları desteğini yapılandırma.

SharePoint izin filtrelemesi eksik veya beklenmeyen sonuçlar döndürüyorsa bkz. SharePoint izin filtreleme sorunlarını giderme.

Örnek: SharePoint site grubu zorlamalı sorgu

İstek, standart ACL tarafından zorlanan sorguyla aynıdır. Arama hizmeti, çağıran adına SharePoint grubu üyeliğini çözümlemek için dizinin sharePointConnectorAppRegistration'ını kullanır. Yanıtta GroupIds önekli değerleri görmek için, select ifadesini spg: yan tümcesine ekleyin.

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

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

Sorgu örneği

aşağıda sample code sorgu isteği örneği verilmiştir. Sorgu belirteci, sorgulayan kullanıcı için Microsoft Entra erişim belirtecidir.

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

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

Yanlış sonuçları araştırmak için yükseltilmiş izinler (önizleme)

Arama sonuçları her kullanıcıya özgü olduğundan, izin meta verilerini içeren hata ayıklama sorguları sorunlu olabilir. Geliştirici veya yönetici olarak, yetkisiz içerik döndüren sorgularla ilgili sorunları araştırmak için izin meta verilerinden bağımsız olarak sonuçları döndürmek için yükseltilmiş izinlere ihtiyacınız olabilir.

Araştırmak için şunları yapabilmeniz gerekir:

• Son kullanıcının izinlerine göre görüntüleyebileceği belge kümesini görüntüleyin.

• Bazı belgelerin neden son kullanıcı tarafından görülemediğini araştırmak için dizindeki tüm belgeleri görüntüleyin.

Bu görevleri, sorguya özel bir üst bilgi x-ms-enable-elevated-read: trueekleyerek gerçekleştirebilirsiniz.

Yükseltilmiş okuma istekleri için izinler

Arama Dizini Veri Katkıda Bulunanı izinlerine veya Yükseltilmiş Okuma iznini içeren özel bir role sahip olmanız gerekir.

Sorgular bir veri düzlemi işlemidir, bu nedenle özel rol yalnızca atomik veri düzlemi izinlerinden oluşabilir. Özel rol için Microsoft.Search/searchServices/indexes/contentSecurity/elevatedOperations/read iznini ekleyin.

Sorguya geliştirilmiş okuma başlığı ekleyin

İzinleri ayarladıktan sonra sorguyu çalıştırabilirsiniz. Aşağıdaki örnek, arama dizinine yönelik bir sorgu isteğidir.

POST {endpoint}/indexes('{indexName}')/search.post.search?api-version=2026-08-01-preview
Authorization: Bearer {AUTH_TOKEN}
x-ms-query-source-authorization: {TOKEN}
x-ms-enable-elevated-read: true

{
    "search": "prototype tests",
    "select": "filename, author, date",
    "count": true
}

Belirli önizleme API'sindeki önemli ACL işlev davranışı değişikliği

REST API sürümünden 2025-11-01-previewönce, önceki önizleme sürümleri 2025-05-01-preview ve 2025-08-01-preview kullanıcı belirteci sağlanmamış olsa bile bir hizmet API anahtarı veya yetkili Entra rolleri kullanılırken tüm belgeleri döndürdü. Kullanıcı belirtecinin varlığını doğrulamayan uygulamalar, doğru şekilde uygulanmadıklarında veya en iyi uygulamalara uygun geliştirilmediklerinde, çıktıları istemeden son kullanıcılara gösterebilir.

Kasım 2025'te bu davranış değişti:

• ACL izin filtreleri artık ACL'nin destek olduğu tüm sürümlerde yalnızca hizmet API anahtarları veya Entra kimlik doğrulaması kullanılırken bile geçerlidir.
• Kullanıcı belirteci atlanırsa, ACL korumalı içerik döndürülemez.
• Sorun giderme amacıyla tüm belgeleri görüntülemek için, REST API'nin 2026-05-01-preview veya sonraki bir sürümünü kullanırken elevated-read üst bilgisini açıkça eklemeniz gerekir.

Bu güncelleştirme, uygulamalar belirteç doğrulaması için en iyi yöntemleri uygulamadığında içeriğin korunmasına yardımcı olur.

İlgili içerik

• Öğretici: ADLS Gen2’den izin meta verilerini dizinine ekleme ve izinlere göre filtrelenmiş sonuçları sorgulama (önizleme)
• Anında iletme REST API'lerini kullanarak belge erişim denetim listelerinin (ACL' ler) dizinini oluşturma (önizleme)
• İzin meta verilerini almak ve arama sonuçlarını kullanıcı erişim haklarına göre filtrelemek için ADLS 2. Nesil dizin oluşturucu kullanma (önizleme)
• RBAC kapsamlarının meta verilerini almak için bir blob dizin oluşturucu veya bilgi kaynağı kullanın
• İzin meta verilerini almak ve arama sonuçlarını kullanıcı erişim haklarına göre filtrelemek için SharePoint dizin oluşturucu kullanma (önizleme)