RBAC kapsamları meta verilerini almak için blob dizin oluşturucu veya bilgi kaynağı kullanma (önizleme)

Azure Depolama, blob depolamada kapsayıcılara rol tabanlı erişim sağlar. Depolama Blob Veri Okuyucusu veya Depolama Blob Veri Katkıda Bulunanı gibi roller, birisinin içeriğe erişimi olup olmadığını belirler. Azure Yapay Zeka Arama, arama sonuçlarına erişimi denetlemek için bu izinleri kullanabilmeniz için belge alımıyla birlikte kullanıcı izinlerinin (önizleme) alımını destekler. Bir kullanıcı Azure Depolama'da belirli bir dizin veya dosya üzerinde izinlere sahip değilse, siz Arama İndeksi Veri Okuyucusu ataması indeks üzerinde yapılmış olsa bile kullanıcının Azure Yapay Zeka Arama sonuçlarındaki ilgili belgelere erişimi yoktur.

• 2025-05-01-preview ve üzeri sürümlerde, RBAC kapsamları meta verileri Blob dizin oluşturucu kullanılarak alınabiliyor.
• 2025-11-01-preview ve sonraki sürümler, Azure Depolama Blob bilgi kaynakları için eşdeğer destek sağlar.

RBAC kapsamı kapsayıcı düzeyinde ayarlanır ve izin devralma yoluyla tüm bloblara (belgelere) aktarılır. Dizin oluşturma sırasında RBAC kapsamı, izin metaverisi olarak kaydedilir. İçeriği ve izin meta verilerini el ile karşıya yüklemek ve dizine eklemek için gönderim API'lerini kullanabilirsiniz (bkz. Gönderme REST API'sini kullanarak İzinleri Dizinleme) veya veri alımını otomatikleştirmek için bir dizin oluşturucu veya bilgi kaynağı kullanabilirsiniz. Bu makale, dizin oluşturma otomasyonuna odaklanır.

Sorgu zamanında, çağıranın kimliği parametresi aracılığıyla istek üst bilgisine x-ms-query-source-authorization eklenir. Kullanıcının arama sonuçlarını görmesi durumunda kimlik belgelerdeki izin meta verileriyle eşleşmelidir.

Bu makalede, bu temele dayalı olarak oluşturulan dizin oluşturma otomasyonu yaklaşımlarına odaklanmaktadır:

• Azure Depolama rol tabanlı erişim denetimi (Azure RBAC) kullanılarak güvenli hale getirilen bloblar. Öznitelik tabanlı erişim denetimi (Azure ABAC) için destek yoktur.

• Azure Blob dizin oluşturucu veya izin filtreleri de dahil olmak üzere veri ve meta verileri alan ve işleyen bir Blob bilgi kaynağı. İzin filtresi desteği almak için en son önizleme REST API'sini veya özelliği destekleyen bir Azure SDK önizleme paketini kullanın.

• Alınan belgeleri ve ilgili izinleri içeren bir dizin Azure Yapay Zeka Arama'te . İzin meta verileri dizinde alanlar olarak depolanır.

• İzin filtrelerini kullanan bir sorgu. İzin filtrelerine uyan sorgular ayarlamak için en son önizleme REST API'sini veya özelliği destekleyen bir Azure SDK önizleme paketini kullanın.

Önkoşullar

• Microsoft Entra ID kimlik doğrulaması ve yetkilendirme. Hizmetler ve uygulamalar aynı kiracıda olmalıdır. Kullanıcılar, tüm kiracılar Microsoft Entra ID olduğu sürece 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ölge, ancak yönetilen kimlik desteği için faturalanabilir bir katmanınız (temel ve üzeri) olmalıdır. Arama hizmetinin rol tabanlı erişim için yapılandırılması ve yönetilen bir kimliğe (sistem veya kullanıcı) sahip olması gerekir.

• Azure Depolama, Standart performans (genel amaçlı v2), sık erişim, seyrek erişim ve soğuk erişim katmanlarında, RBAC güvenli kapsayıcılar veya bloblar ile.

• Dizin oluşturucuların ve bilgi kaynaklarının nasıl çalıştığını ve dizin oluşturmayı anlamanız gerekir. Bu makalede, veri kaynağı ve dizin oluşturucu için yapılandırma ayarları açıklanmaktadır, ancak dizin oluşturma adımlarını sağlamaz. İzin filtreleri için tasarlanmış dizinler hakkında daha fazla bilgi için bkz. İzin filtresi alanlarıyla dizin oluşturma.

Sınırlamalar

• Azure portalı bu özelliği desteklemez.

• 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

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

  • Oturumlarda hata ayıklama

Blob Depolama'ı yapılandır

Blob kapsayıcınızın rol tabanlı erişim kullandığını doğrulayın.

1. Azure portalında oturum açın ve depolama hesabınızı bulun.

2. Kapsayıcıları genişletin ve dizine eklemek istediğiniz blobları içeren kapsayıcıyı seçin.

3. Rol atamalarını denetlemek için Access Control (IAM) öğesini seçin. Depolama Blobu Veri Okuyucusu veya Depolama Blob Verileri Katkıda Bulunanı olan kullanıcılar ve gruplar, kapsayıcı dizine eklendikten sonra dizindeki belgeleri aramaya erişebilir.

Yetkilendirme

Dizin oluşturucu yürütmesi için arama hizmeti kimliğinizin Depolama Blob Veri Okuyucusu iznine sahip olması gerekir. Daha fazla bilgi için bkz. Azure Depolama'a yönetilen kimlik kullanarak bağlanma.

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şturucu yürütmesi için API çağrısını veren istemcinin, nesne oluşturmak için Search Service Contributor iznine, veri içeri aktarmak için Search Index Data Contributor iznine ve bir dizini sorgulamak için Search Index Data Reader iznine sahip olması gerekir. Daha fazla bilgi için rolleri kullanarak Azure Yapay Zeka Arama'e bağlanma bölümüne bakın.

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. RBAC kapsamı algılanır ve 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 false olarak ayarlanır; bu da veri kaynağının Azure Blob Depolama olduğu anlamına gelir.
• ingestionPermissionOptions belirtir rbacScope.

# 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": false,
        "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": ["rbacScope"],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}

Başvuru:Bilgi Kaynağı Oluşturma veya Güncelleştirme (REST API)

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

Dizin oluşturucu kullanıyorsanız, izin meta verilerini bloblardan çekmek için dizin oluşturucuyu, veri kaynağını ve dizini yapılandırın.

Veri kaynağını oluşturma

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

• Veri kaynağı ayrıştırma modu varsayılan olmalıdır.

• Veri kaynağı, indexerPermissionOptions ve rbacScope ile birlikte 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 kimlik ve indexerPermissionOptionsile JSON örneği:

{
    "name" : "my-blob-datasource",
    "type": "azureblob",
    "indexerPermissionOptions": ["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-query-used-for-selecting-specific-blobs>"
    }
}

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

{
    "name" : "my-blob-datasource",
    "type": "azureblob",
    "indexerPermissionOptions": ["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-query-used-for-selecting-specific-blobs>"
    },
    "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.

RBAC Kapsamı için önerilen şema öznitelikleri

• 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 güvenlik sorumlusu kimliklerinin sonuçlarda görünmemesi için üretim ortamına dağıtmadan önce false olarak geri almayı unutmayın.

JSON şema örneği:

{
  ...
  "fields": [
    ...
    { 
        "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. Azure Blob Depolama'deki aşağıdaki meta veri alanları, alan adını değiştirdiğinizde alan eşlemeleri gerekebilir:

• 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_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Dizin oluşturucuyu çalıştırma

Dizin oluşturucunuz, veri kaynağınız ve dizininiz yapılandırıldıktan sonra işlemi hareket halinde ayarlamak için dizin oluşturucuyu çalıştırın. Yapılandırma veya izinlerle ilgili bir sorun varsa, bu sorunlar bu adımda ortaya çıkar.

Varsayılan olarak, bir dizin oluşturucu bir arama hizmetine gönderdiğiniz anda çalışır, ancak dizin oluşturucu yapılandırması disabled true olarak ayarlanırsa, dizin oluşturucuyu el ile çalıştırabilmeniz için devre dışı durumda postalanır.

Durumu ve iletileri izleyebilebilmeniz için Azure portalından dizin oluşturucuyu çalıştırmanızı öneririz.

Hata olmadığı varsayıldığında, dizin artık doldurulur ve sorgular ve testlerle ilerleyebilirsiniz.

Silme izleme

Blob silmeyi etkili bir şekilde yönetmek için, dizin oluşturucunuz ilk kez çalışmadan önce silme izlemeyi etkinleştirdiğinizden emin olun. Bu özellik, sistemin kaynağınızdan silinen blobları algılamasına ve ilgili içeriği dizinden silmesine olanak tanır.

Ayrıca bkz.

• 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

• Azure Blob Depolama içeriği üzerinde arama
• Blob dizin oluşturucusunu yapılandır