Azure Yapay Zeka Arama'te Microsoft Purview duyarlılık etiketlerinin sorgu sırasında uygulanması (önizleme)

Sorgu sırasında Azure Yapay Zeka Arama, Microsoft Purview'de tanımlanan duyarlılık etiketi ilkelerini (önizleme) uygulayabilir. Bu ilkeler, her belgeyle ilişkili kullanım haklarınınEXTRACT değerlendirilmesi ile kullanıcıların yalnızca erişim iznine sahip oldukları belgeleri alabilmesini sağlar.

Bu özellik belge düzeyinde erişim denetimini, Microsoft Purview'da yönetilen kuruluşunuzun bilgi koruma ve uyumluluk gereksinimleri ile uyumlu hale getirir.

Purview duyarlılık etiketi dizin oluşturma etkinleştirildiğinde, Azure Yapay Zeka Arama sorgu sırasında her belgenin etiket meta verilerini denetler. Yalnızca istekte bulunan kullanıcının erişmesine izin verilen sonuçları döndürmek için Purview ilkelerine dayalı erişim filtreleri uygular.

Bu makalede, sorgu zamanındaki duyarlılık etiketi uygulamasının nasıl çalıştığı ve güvenli arama sorgularının nasıl yapılacağı açıklanmaktadır.

Önkoşullar

• Azure Yapay Zeka Arama dizinleyicilerini kullanarak Microsoft Purview duyarlılık etiketlerini almak için gereken tüm adımları tamamlayın.

• Azure Yapay Zeka Arama hizmetinin sistem tarafından atanan yönetilen kimliğinin (kullanıcı tarafından atanan yönetilen kimlik değil) etkinleştirildiğini ve ve Content.SuperUser rol atamalarını barındırdığını UnifiedPolicy.Tenant.Read doğrulayın. Sorgu zamanında zorunlu kılma, yalnızca sistem tarafından atanan kimlik doğru yapılandırmaya sahip olduğunda dizin oluşturucunun ayıklayabildiği etiket meta verilerine bağlıdır. Dizin oluşturucu kurulum makalesindeki 1. adıma bakın.

• Hem Azure Yapay Zeka Arama hizmeti hem de sorguyu veren kullanıcı aynı Microsoft Entra kiracısında olmalıdır.

• Dizini sorgulamak için REST API'nin 2025-11-01-preview veya sonraki bir sürümü ya da eşdeğer bir önizleme SDK paketi. Yükseltilmiş okuma özelliği ve Purview denetim günlüğü, 2026-05-01-preview veya sonraki bir sürümü gerektirir.

• API anahtarlarını değil Azure rol tabanlı erişim denetimini (RBAC) kullanarak sorguların kimliğini doğrulama. Purview duyarlılık etiketleri etkinleştirildiğinde, API anahtarı erişimi dizin şeması alma ile sınırlıdır.

Sınırlama

• Konuk hesapları ve kiracılar arası sorgular desteklenmez.

• Purview özellikli dizinler için otomatik tamamlama ve ÖNERI API'leri desteklenmez.

• Etiket değerlendirmesi başarısız olursa, hizmet kısmi veya filtrelenmemiş bir sonuç kümesi yerine belirli bir HTTP hata kodu döndürür. Hata kodlarının ve nedenlerinin tam listesi için bkz. Sorgu hatalarını giderme.

• Sistem etiketleri yalnızca son dizin oluşturucu çalıştırması sırasında mevcut oldukları şekilde değerlendirir. Son etiket değişiklikleri bir sonraki zamanlanmış yeniden dizine yansıtılmayabilir.

Sorgu zamanında duyarlılık etiketi uygulanması nasıl çalışır?

Microsoft Purview duyarlılık etiketleri içeren bir dizini sorguladığınızda Azure Yapay Zeka Arama sonuçları döndürmeden önce ilişkili Purview ilkelerini denetler. Bu şekilde sorgu yalnızca kullanıcı belirtecinin erişmesine izin verilen belgeleri döndürür.

1. Kullanıcı kimliği ve uygulama rolü girişi

Sorgu zamanında Azure Yapay Zeka Arama her ikisini de doğrular:

• Çağrı yapan uygulamanın RBAC rolü, Authorization başlıkta sağlanır. Gereken en düşük rol Search Index Data Reader'dir. Diğer ayrıntılar için Azure Yapay Zeka Arama RBAC kılavuzu bölümünü gözden geçirin.
• Üst bilgide x-ms-query-source-authorization sağlanan belirteç aracılığıyla kullanıcı kimliği.

Her ikisi de etiket tabanlı görünürlüğü yetkilendirmek için gereklidir.

2. Duyarlılık etiketi değerlendirmesi

Sorgu isteği alındığında Azure Yapay Zeka Arama şunları değerlendirir:

1. Dizine alınan her belgedeki sensitivityLabel alanı (alma sırasında Microsoft Purview ayıklanır).
2. Microsoft Entra ID ve Purview etiket ilkesi tarafından tanımlanan kullanıcının etkin Purview izinleri.

Kullanıcı, izinlere sahip EXTRACT bir belgenin duyarlılık etiketi için yetkilendirilmezse, bu belge sorgu sonuçlarından dışlanır.

3. Güvenli sonuç filtreleme

Azure Yapay Zeka Arama, tüm kullanıcı tanımlı filtreler ve puanlama adımlarından sonra güvenlik filtresini uygular.
Son sonuç kümesine yalnızca aşağıdaki durumlarda bir belge eklenir:

• Çağıran uygulamanın geçerli bir rol ataması var (RBAC aracılığıyla) ve
• x-ms-query-source-authorization tarafından temsil edilen kullanıcı kimliği belirteci geçerlidir ve belgenin duyarlılık etiketine sahip içeriği görüntülemesine izin vermektedir.

Her iki koşuldan biri başarısız olursa, belge sonuçlardan atlanır.

Kullanıcı erişim belirteci alma

Kullanıcı bağlamını kullanarak Azure Yapay Zeka Arama sorgulamak için oturum açmış kullanıcıyı temsil eden bir erişim belirteci almanız gerekir. Kullandığınız yaklaşım, kendi belirtecinizle yerel olarak test edip etmediğinize, kaynak belgeye erişiminiz olup olmadığına veya son kullanıcı belirtecinin geçirilmesini gerektiren uygulama akışını uygulamaya bağlıdır.

Test senaryoları için

Yerel test için, Azure CLI kullanarak bir kullanıcı erişim belirteci alabilirsiniz:

$token = az account get-access-token `
  --resource https://search.azure.com `
  --query accessToken `
  --output tsv

Bu yaklaşım geçerli Azure CLI oturum açma oturumunuzu kullandığından, duyarlılık etiketleri aracılığıyla atanmış EXTRACT izinlerine sahip olduğunuz belgeler üzerinde bağlamı kullanabilirsiniz. Bu yöntem yalnızca geliştirme ve doğrulama senaryolarına yöneliktir.

OBO senaryoları için jeton alma

Adına (OBO) akışı uygulayan uygulamalar, Microsoft Authentication Library (MSAL) gibi desteklenen bir kimlik doğrulama kitaplığı kullanarak Microsoft Entra ID aracılığıyla belirteçler almalıdır.

OBO senaryolarında, uygulamanın çağırdığını aşağı akış API'sinin belirtecini isteyin. Örneğin, Azure Yapay Zeka Arama çağrılırken kaynak URI'si https://search.azure.com/.default.

.default kapsamı, uygulamanın belirtilen kaynak için önceden onaylanmış tüm devredilmiş izinlerini ister.

Duyarlılık etiket izinleri, EXTRACT dahil olmak üzere OAuth kapsamları olarak temsil edilmez. Azure Yapay Zeka Arama gibi aşağı akış hizmeti, belirteçteki kullanıcı kimliğine ve uygulanan duyarlılık etiketi ilkesine göre çalışma zamanında bu izinleri değerlendirir.

Sorgu örneği

Aşağıda Microsoft Purview duyarlılık etiketi zorlaması kullandığı bir sorgu isteği örneği verilmiştir.

Uygulama belirtecini Authorization üst bilgisinde Bearer belirteci olarak iletin. Kullanıcı belirtecini, x-ms-query-source-authorization ön eki olmadan, Bearer üst bilgisinde ham belirteç değeri olarak iletin.

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

{
    "search": "*",
    "select": "title,summary,sensitivityLabel",
    "orderby": "title asc"
}

Yönetim araştırmaları için yükseltilmiş okuma (önizleme)

Yükseltilmiş okuma, yetkili bir geliştiricinin çağrı yapan kullanıcının normalde göremeyebileceği etiketli belgeleri döndürmesine olanak tanırken, isteğin döndürdüğü her belge için bir Microsoft Purview denetim günlüğü girişi yayar. Erişimin denetlenebilir bir kaydının gerekli olduğu uyumluluk incelemeleri, eKeşif, olay müdahalesi ve diğer idari soruşturmalar için kullanın.

Yükseltilmiş okuma, REST API sürüm 2026-05-01-preview ve sonraki sürümlerde Purview özellikli dizinlerde kullanılabilir.

Yükseltilmiş okuma nasıl çalışır?

1. Çağıran uygulama, arama isteğinde x-ms-enable-elevated-read: true üst bilgisini ayarlar.

2. Azure Yapay Zeka Arama, belge başına etiket tabanlı erişim denetimini atlar ve her etikette istekte bulunan kullanıcının EXTRACT izinlerinden bağımsız olarak eşleşen belgeleri döndürür.

3. Yanıttaki her belge için, Azure Yapay Zeka Arama istekte bulunan kiracı adına Microsoft Purview denetim günlüğüne bir giriş yayar. N belge döndüren tek bir arama isteği N denetim girdileri üretir.

4. Denetim girdileri, arama yanıtı döndürüldükten sonra zaman uyumsuz olarak Purview'a yüklenir.

Gerekli rol ataması

Çağıran geliştirici kullanıcının, arama hizmetinde veya dizin düzeyinde Arama Dizini Veri Katkıda Bulunanı rolüne sahip olması gerekir. Arama Dizini Veri Okuyucusu yeterli değildir. Yükseltilmiş okuma, rol atanmamışsa 403 Forbidden ile başarısız olur. Azure Yapay Zeka Arama rolleri hakkında daha fazla bilgi için Azure Yapay Zeka Arama’e roller kullanarak bağlanma konusuna bakın.

x-ms-enable-elevated-read üst bilgisi true olarak ayarlandığında, x-ms-query-source-authorization üst bilgisinin kullanılmasına izin verilmez.

Yükseltilmiş okuma örneği

POST  {{endpoint}}/indexes/sensitivity-docs/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{contributor-token}}
x-ms-enable-elevated-read: true
Content-Type: application/json

{
    "search": "*",
    "select": "title,summary,sensitivityLabel",
    "orderby": "title asc"
}

Microsoft Purview’a gönderilen denetim alanları

Her denetim girdisi Office 365 yönetim etkinliği API şemasını izler ve aşağıdaki alanları içerir.

Zarif bozulma

Azure Yapay Zeka Arama, örneğin geçici bir Purview kesintisi sırasında bir sorgu işlenirken Microsoft Purview’a ulaşamazsa, bu istek için etiket değerlendirmesini atlar. Davranış, isteğin bir kullanıcı kimliği belirteci içerip içermediğine bağlıdır:

• Artan okuma istekleri (x-ms-enable-elevated-read: true): İstek, 5xx hatasıyla başarısız olur. Azure Yapay Zeka Arama, önce denetim günlükleri oluşturamadan etiketlenmiş belgeleri döndürmez.

• Standart etiket zorlamalı istekler (x-ms-query-source-authorization ile): İstek, 5xx ile başarısız olur. Azure Yapay Zeka Arama, etiket ilkelerini değerlendiremediğinde kısmi veya filtrelenmemiş sonuçlar döndürmez.

• x-ms-query-source-authorization içermeyen çağrılar: En az Arama Dizini Veri Okuyucusu rolüne sahip bir uygulama tarafından yapıldığında istek başarılı olur ve yalnızca duyarlılık etiketi olmayan belgeleri döndürür. Etiketli belgeler yanıttan atlanır.

Bu degrade edilmiş yol, yalnızca etiketsiz sonuçları açıkça kabul eden, kullanıcıya yönelik olmayan iş akışları için tasarlanmıştır. Son kullanıcı arama deneyimleri için buna güvenmeyin.

Sorgu zamanı duyarlılık etiketi değerlendirmesi sırasında döndürülen hata kodlarının tam listesi için bkz. Sorgu hatalarını giderme.

Microsoft Purview'da yükseltilmiş okuma denetim günlüklerini bulma

Azure Yapay Zeka Arama, denetim girdilerini çağıran kiracının Microsoft Purview denetim günlüğüne yükler. Yükseltilmiş okuma etkinliğini araştırmak için:

1. Microsoft Purview portalıSolutions>Audit öğesini seçin.

2. Audit Search öğesini seçin ve tarih aralığına, kullanıcıya veya Azure Yapay Zeka Arama kayıt türüne göre filtreleyin.

3. standart şema alanlarını ve SensitivityLabelName, DocumentDataSourceType ve DocumentDataSourceId gibi Azure Yapay Zeka Arama özel alanları görüntülemek için bir giriş açın.

Denetim aramalarını gerçekleştirmeye, saklama davranışına ve gerekli Purview rollerine ilişkin adım adım yönergeler için bkz: Microsoft Purview portalıında denetim günlüğünde arama yapma.

Azure Yapay Zeka Arama duyarlılık etiket işlemi

Azure Yapay Zeka Arama belge içeriğini SharePoint, Azure Blob ve diğer kaynaklardan duyarlılık etiketleriyle dizine eklediğinde, hem içeriği hem de etiket meta verilerini depolar. Arama sorgusu, yalnızca kullanıcının duyarlılık etiketi tanımı aracılığıyla atanan belge için veri EXTRACT erişimine sahip olması durumunda belgeye uygulanan duyarlılık etiketini tanımlayan GUID ile birlikte dizine alınan içeriği döndürür. Bu GUID etiketi benzersiz olarak tanımlar, ancak etiket adı veya ilişkili izinler gibi insan tarafından okunabilen özellikleri içermez.

Duyarlılık etiketleri genellikle Microsoft Purview Bilgi Koruması tarafından zorunlu kılınan diğer ilke denetimlerini taşıdığından, kullanıcı arabirimi içeren senaryolar için tek başına GUID'nin yeterli olmadığını unutmayın; örneğin: yazdırma izinleri veya ekran görüntüsü ve ekran yakalama kısıtlamaları. Azure Yapay Zeka Arama bu özellikleri ortaya çıkarmıyor.

Etiket adlarını görüntülemek ve/veya kullanıcı arabirimine özgü kısıtlamaları zorunlu kılmak için uygulamanızın tam etiket meta verilerini ve ilişkili izinleri almak için Microsoft Purview Bilgi Koruması uç noktasını çağırması gerekir.

Etiket özelliklerini çözümlemek ve etiket adını, açıklamasını ve ilke ayarlarını getirmek için Purview Etiketleri API'lerini çağırmak için Azure Yapay Zeka Arama tarafından döndürülen GUID'yi kullanabilirsiniz.

Sorgu hatalarını giderme

Sorgu zamanı duyarlılık etiketi değerlendirmesi başarısız olduğunda, Azure Yapay Zeka Arama nedeni tanımlayan belirli bir HTTP hata kodu döndürür. Hizmet hiçbir zaman kısmi veya filtrelenmemiş bir sonuç kümesi döndürmez. Etiket ilkeleri değerlendirilemiyorsa, etiketlenmemiş veya yetkisiz içeriği açığa çıkarmak yerine sorgu başarısız olur.

400 Hatalı İstek

400 hatası, dizin yapılandırması veya istek üst bilgileriyle ilgili bir sorun olduğunu gösterir. Yeniden denemeden önce yapılandırmayı düzeltin.

401 Yetkisiz

401 hatası yetkilendirme belirteciyle veya uygulamanın Purview izinleriyle ilgili bir sorun olduğunu gösterir.

502 Hatalı Ağ Geçidi

502 hatası, Azure Yapay Zeka Arama ile Microsoft Purview arasında bağlantı hatası olduğunu gösterir. Bu hatalar genellikle geçicidir.

504 Ağ Geçidi Zaman Aşımı

504 hatası, Microsoft Purview izin verilen süre içinde yanıt vermediğini gösterir.

Uçtan uca test kurulumu

Azure Yapay Zeka Arama’te duyarlılık etiketi yapılandırmanızı doğrulamanıza yardımcı olması için örnek uçtan uca kuruluma bakın.

Bu depo aşağıdakilerin nasıl yapılacağını gösterir:

• Azure Yapay Zeka Arama’te duyarlılık etiketlerini eşitlemeyi ve bunlara uymayı yapılandırma
• Duyarlılık etiketlerine sahip belgeler için içeri aktarma ve sorgu sırasında uygulama senaryolarını test edin
• Etiket adını ayıklayın ve RAG uygulamalarınızda veya aracılarınızda kullanılan alıntıların bir parçası olacak şekilde görünür hale getirin.