İ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)

Azure Data Lake Storage (ADLS) 2. Nesil, access denetim listeleri (ACL'ler) ve role tabanlı erişim denetimi (Azure RBAC) aracılığıyla dizinlere ve dosyalara kullanıcı başına erişimi destekler. Attribute tabanlı erişim denetimi (Azure ABAC) desteklenmez.

Azure Yapay Zeka Arama önizleme REST API'sini kullanarak belge içeriğinin yanı sıra bu izin meta verilerini (önizleme) alabilir. Depolama alanında bir dizine veya dosyaya erişimi olmayan kullanıcılar, arama sonuçlarında ilgili belgeleri görmez. Bu, Azure Yapay Zeka Arama document düzeyinde erişim denetimi için çeşitli stratejilerden biridir.

Bu makalede, izin meta verilerini otomatik olarak bir arama dizinine çekmek için ADLS 2. Nesil dizin oluşturucu veya ADLS 2. Nesil blob bilgi kaynağını yapılandırma işlemi açıklanmaktadır. ADLS 2. Nesil'den Dizin verilerini destekler ve ADLS 2. Nesil için izin alımına özgü bilgilerle bir blob bilgi kaynağı oluşturur. İzin meta verilerini el ile göndermek için bkz. Gönderme API'sini kullanarak belge ACL'lerini dizine alma.

Önkoşullar

• Microsoft Entra ID kimlik doğrulaması ve yetkilendirme. Hizmetler ve uygulamalar aynı kiracıda olmalıdır. Tüm kiracılar Microsoft Entra ID kullandığı sürece kullanıcılar farklı kiracılarda olabilir. Rol atamaları, kimliği doğrulanmış her bağlantı için kullanılır.

• Azure Yapay Zeka Arama, herhangi bir bölgede Temel veya daha yüksek faturalanabilir bir katmanda. Arama hizmetinin rol tabanlı erişimi etkinleştirilmiş ve sistem tarafından atanan veya kullanıcı tarafından atanan yönetilen kimliği olmalıdır.

• ADLS 2. Nesil blobları, kullanıcı izinlerinin ACL'ler veya roller aracılığıyla verildiği hiyerarşik bir ad alanında bulunur.

• Dizin oluşturucu izin alımı için REST API sürüm 2025-05-01-preview veya üzeri. Bilgi kaynağı desteği için REST API sürümü 2025-11-01-preview veya daha sonraki bir sürüm gerekir. en son önizleme REST API'sini veya izin filtrelerini destekleyen bir önizleme SDK'sı paketini kullanın.

Sınırlama

• Azure portalı bu özelliği desteklemez.

• Rol atamaları ve ACL girişleri için ADLS 2. Nesil sınırları geçerlidir.

• owning users, owning groupsve Other (all) ACL kimlik kategorileri önizleme sırasında desteklenmez. Bunun yerine named users ve named groups atamalarını kullanın.

• Aşağıdaki dizin oluşturucu özellikleri, ADLS 2. Nesil'den kaynaklanan dizine alınan belgelerde izin devralmayı desteklemez. Bu özelliklerden herhangi birini beceri kümesinde veya dizin oluşturucuda kullanırsanız, belge düzeyi izinleri dizine alınan içeriğe dahil değildir.

  • Özel Web API'si becerisi

  • Bilgi deposu; ajan tabanlı almada görüntü sunumu (önizleme) için gereken varlık deposu da buna dahildir. Bu nedenle, ACL'leri veya RBAC kapsamlarını alan bilgi kaynakları için görüntü sunma desteklenmez.

  • Dizin oluşturucu zenginleştirme önbelleği

  • Oturumlarda hata ayıklama

İzin modeli desteği

Bu bölümde, ADLS 2. Nesil ile Azure Yapay Zeka Arama arasındaki belge düzeyinde erişim denetimi özellikleri karşılaştırır. AI Search'in hangi Azure Data Lake Storage (ADLS) 2. Nesil erişim denetimi mekanizmalarını desteklediğini veya eşlediği açıklanmaktadır. Bu, izinlerin belge düzeyinde nasıl uygulandığını anlamanıza yardımcı olur.

Sorgu zamanında, Azure Yapay Zeka Arama önce kapsayıcı düzeyinde RBAC'yi değerlendirir ve sonra belge düzeyi ACL girdilerini denetler. Erişim, herhangi bir mekanizma izin verirse verilir.

ACL'nin hiyerarşik izinleri hakkında

Dizin oluşturucular ve bilgi kaynakları, ADLS 2. Nesil hiyerarşik erişim değerlendirme akışını izleyerek belirtilen kapsayıcıdan ve her dosyaya yol açan tüm dizinlerden ACL atamalarını alabilir. Her dosya için son etkin erişim listeleri hesaplanır ve farklı erişim kategorileri ilgili dizin alanlarına dizinlenir.

Örneğin, izinlerle ilgili yaygın senaryolar olarak ADLS Gen2'de, dosya yolu /Oregon/Portland/Data.txt şeklindedir.

Dizin oluşturucu veya bilgi kaynağı her kapsayıcıdan ve dizinden ACL'leri toplar. Daha sonra daha düşük düzeylerde etkin erişimi belirler ve her dosya için izinleri çözene kadar devam eder.

/ assigned access vs Oregon/ assigned access
  => Oregon/ effective access vs Portland/ assigned access
    => Portland/ effective access vs Data.txt assigned access
      => Data.txt effective access

ADLS 2. Nesil'i yapılandırma

Dizin oluşturucu veya bilgi kaynağı, aşağıdaki ölçütlere uyuluysa depolama hesabındaki ACL'leri alabilir. ACL atamaları hakkında daha fazla bilgi için bkz. ADLS 2. Nesil ACL atamaları.

Yetkilendirme

Dizin oluşturma için arama hizmeti kimliğinizin Depolama Blobu Veri Okuyucusu iznine sahip olması gerekir.

Yerel olarak test yapıyorsanız, Depolama Blobu Veri Okuyucusu rol atamanız da bulunmalıdır. Daha fazla bilgi için bkz. Azure Depolama'a yönetilen kimlik kullanarak bağlanma.

Kök kapsayıcı izinleri:

1. Kök kapsayıcı Group'de tüm User ve / kümelerini (güvenlik asıl kimlikleri) Read ve Execute izinleriyle atayın.

2. Read ve Execute her ikisinin de yeni oluşturulan dosya ve dizinlere otomatik olarak yayılabilmesi için "Varsayılan izinler" olarak eklendiğinden emin olun.

İzinleri dosya hiyerarşisine yayma

Yeni dizinler ve dosyalar izinleri devralsa da, mevcut dizinler ve dosyalar bu atamaları otomatik olarak devralmaz.

AdLS 2. Nesil aracını kullanarak mevcut içeriğe atama yayma işlemi için ACL'leri özyinelemeli olarak uygulayın . Bu araç kök kapsayıcının ACL atamalarını bütün alt dizinlere ve dosyalara yayar.

Fazla izinleri kaldırma

ACL'leri özyinelemeli olarak uyguladıktan sonra, her dizin ve dosya için izinleri gözden geçirin.

Belirli dizinlere veya dosyalara erişimi olmaması gereken Group veya User kümelerini kaldırın. Örneğin, User2 klasöründe Portland/ öğesini kaldırın ve Idaho klasöründen Group2 ve User2 gibi atamaları kaldırın.

Örnek ACL atama yapısı

ADLS 2. Nesil belgelerinde kurgusal dizin hiyerarşisi için ACL atama yapısının diyagramı aşağıdadır.

Zaman içinde ACL atamalarını güncelleştirme

Zamanla, yeni ACL atamaları eklendiğinde veya değiştirildiğinde, düzgün yayılım ve izin hizalamasını sağlamak için önceki adımları tekrarlayın. Dizin oluşturucuyu veya bilgi kaynağını kullanarak içeriği yeniden aldığınızda ADLS 2. Nesil'deki güncelleştirilmiş izinler arama dizininde güncelleştirilir.

Azure Yapay Zeka Arama'u yapılandırın

Arama hizmetinin aşağıdakilere sahip olması gerektiğini unutmayın:

• Rol tabanlı erişim etkin
• Yönetilen kimlik yapılandırıldı

Yetkilendirme

Dizin oluşturma için, API çağrısını veren istemcinin nesneleri oluşturmak için Arama Hizmeti Katkıda Bulunanı iznine, veri içeri aktarma gerçekleştirmek için Dizin Veri Katkıda Bulunanı Arama iznine ve dizin sorgulamak için Dizin Veri Okuyucusu'na arama izni olmalıdır.

Yerel olarak test ediyorsanız, aynı rol atamalarına sahip olmanız gerekir. Daha fazla bilgi için bkz. Roller kullanarak Azure Yapay Zeka Arama'e bağlanma.

Bilgi kaynağı yapılandırma

Bilgi kaynağı kullanıyorsanız, tam dizin oluşturma işlem hattı (dizin oluşturucu, veri kaynağı ve dizin) oluşturmak için bilgi kaynağındaki tanımlar kullanılır. ACL atamaları algılanıp oluşturulan dizine otomatik olarak eklenir. Dizine alınan içeriğinizde izin devralmak istiyorsanız, oluşturulan nesnelerin hiçbirini değiştirmeniz gerekmez.

Bu senaryo için çalışmasını sağlayan yapılandırmayla ilgili önemli noktalar:

• isADLSGen2 true olarak ayarlanır ve bu senaryo için veri kaynağı gereksinimi karşılanır.
• ingestionPermissionOptions kullanıcı ve grup kimliklerini belirtir.

# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2026-08-01-preview
api-key: {{key}}
Content-Type: application/json
 
{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source",
    "azureBlobParameters": {
        "connectionString": "{{blob-connection-string}}",
        "containerName": "blobcontainer",
        "folderPath": null,
        "isADLSGen2": true,
        "ingestionParameters": {
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": true,
            "ingestionSchedule": null,
             "ingestionPermissionOptions": [
                "userIds","groupIds"
                           ],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}
###

Dizin oluşturucu tabanlı dizin oluşturmayı yapılandırma

İndeksleyici kullanıyorsanız, ADLS Gen2 bloblarından izin meta verilerini çekmek için indeksleyiciyi, veri kaynağını ve dizini yapılandırın.

Veri kaynağını oluşturma

Bu bölüm, ADLS Gen2'den gelen indeks verilerini, belge içeriğinin yanı sıra bir Azure Yapay Zeka Arama dizinine alma izinlerine özgü bilgilerle tamamlar.

• Veri Kaynağı türü olmalıdır adlsgen2.

• Veri kaynağında indexerPermissionOptions, userIds, groupIds ve/veya rbacScope olmalıdır.

  • rbacScope için bağlantı dizesini yönetilen kimlik formatını kullanarak yapılandırın.

  • Kullanıcı tarafından atanan yönetilen kimliği kullanan bağlantı dizeleri için identity özelliğini de belirtmeniz gerekir.

Sistem tarafından yönetilen kimliğe sahip JSON örneği:

{
    "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": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    }
}

Bağlantı dizesinde kullanıcı tarafından yönetilen kimlikle ilgili JSON şema örneği:

{
    "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": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    },
    "identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
    }
}

Dizinde izin alanları oluşturma

Azure Yapay Zeka Arama'de dizininizin izin meta verileri için alan tanımları içerdiğinden emin olun. veri kaynağı tanımında belirtildiğinde indexerPermissionOptions izin meta verileri dizine eklenebilir.

ACL (UserIds, GroupIds) ve RBAC Kapsamı için önerilen şema öznitelikleri:

• permissionFilter değerine sahip userIds kullanıcı tanımlayıcısı (ID) alanı.
• groupIds izinFiltre değeriyle Grup Kimlikleri alanı.
• permissionFilter değerine sahip rbacScope RBAC kapsam alanı.
• Sorgulama zamanında filtrelemeyi etkinleştirmek için özellik permissionFilterOption .
• İzin meta verileri için dize alanlarını kullanma
• filterable değerini tüm alanlarda true olarak ayarlayın.

retrievable'ün yanlış olduğuna dikkat edin. İzinlerin mevcut olduğunu doğrulamak için geliştirme sırasında bunu true olarak ayarlayabilirsiniz, ancak üretim ortamına dağıtmadan önce false olarak geri almayı unutmayın.

JSON şema örneği:

{
  ...
  "fields": [
    ...
    { "name": "UserIds", "type": "Collection(Edm.String)", "permissionFilter": "userIds", "filterable": true, "retrievable": false },
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false },
    { "name": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

Dizin oluşturucuyu yapılandırma

Dizin oluşturucu içindeki alan eşlemeleri, veri yolunu dizindeki alanlara ayarlar. İsim veya veri türüne göre değişiklik gösteren kaynak ve hedef alanlar için açık bir alan eşlemesi gerekir. AdLS 2. Nesil'deki aşağıdaki meta veri alanlarının, alan adını değiştirmeniz durumunda alan eşlemeleri gerekebilir:

• metadata_user_ids (Collection(Edm.String)) - ACL kullanıcı kimlikleri listesi.
• metadata_group_ids (Collection(Edm.String)) - ACL grup kimlikleri listesi.
• metadata_rbac_scope (Edm.String) - kapsayıcı RBAC kapsamı.

Dizin oluşturma sırasında izin meta verilerini hedef alanlara yönlendirmek için dizin oluşturucuda belirtin fieldMappings .

JSON şema örneği:

{
  ...
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Öneriler ve en iyi yöntemler

• Herhangi bir klasör oluşturmadan önce ADLS 2. Nesil klasör yapısını dikkatlice planlayın.

• Kimlikleri gruplar halinde düzenleyin ve tek tek kullanıcılara doğrudan erişim vermek yerine mümkün olduğunca grupları kullanın. Grupları uygulamak yerine tek tek kullanıcıların sürekli eklenmesi, izlenmesi ve değerlendirilmesi gereken erişim denetimi girdilerinin sayısını artırır. Bu en iyi yönteme uyulmuyorsa, bu meta veriler değiştikçe dizinde daha sık güvenlik meta verisi güncelleştirmeleri yapılması gerekebilir ve bu da yenileme işleminde gecikmelerin ve verimsizliklerin artmasına neden olabilir.

Dizinlenmiş içerik ve kaynak içerik arasındaki izinleri eşitleme

Dizin oluşturucuda ACL veya RBAC zenginleştirmesini etkinleştirmek yalnızca iki durumda otomatik olarak çalışır:

• İlk tam dizin oluşturucu çalıştırması / veri gezinmesi: Her belge için o anda var olan tüm izin meta verileri yakalanır.

• ACL/RBAC desteği etkinleştirildikten sonra eklenen yepyeni belgeler şunlardır: ACL/RBAC bilgileri içerikleriyle birlikte alınıyor.

ACL'ye kullanıcı ekleme veya rol atamasını güncelleştirme gibi belge izinlerini değiştirirseniz, dizin oluşturucuya belgenin izin meta verilerinde yeniden gezinmesini söylemediğiniz sürece değişiklik arama dizininde görünmez.

Kaç öğenin değiştiğine bağlı olarak aşağıdaki mekanizmalardan birini seçin:

Resetdocs (önizleme) API örneği:

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2026-08-01-preview
{ 
  "documentKeys": [ 
    "1001", 
    "4452" 
  ]
}

Api'yi yeniden eşitleme (önizleme) örneği:

POST https://{service}.search.windows.net/indexers/{indexer}/resync?api-version=2026-08-01-preview
{ 
  "options": [ 
    "permissions" 
  ] 
} 

Silme izleme

Blob silme işlemini etkili bir şekilde yönetmek için, dizin oluşturucunuz ilk kez çalışmadan önce silme izlemenin etkinleştirildiğinden emin olun. Bu özellik, sistemin kaynağınızdaki silinmiş blobları algılamasına ve bunları dizinden kaldırmasına olanak tanır.

İlgili içerik

• Rolleri kullanarak Azure Yapay Zeka Arama'e bağlanın
• Sorgu zamanı ACL ve RBAC uygulaması
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API